Forem: Craig Broughton

Learning Nix(OS) - My Experience

Craig Broughton — Wed, 11 Mar 2026 08:21:43 +0000

I've dived down a bit of a rabbit hole over the last few months, and I'm coming back out to talk about my new lord and saviour, Nix (and more recently, NixOS).

If you're like me, and you love to tinker with software, you've probably found yourself running some variant of Linux at some point in your life. I've gone through a typical journey: rocking vanilla Ubuntu and Kubuntu, migrating over to Pop!_OS for a few years and finding a home there, and ultimately finding myself wanting something more.

I've also had a parallel journey at work, using a Mac M2 Pro for more than a year and struggling to maintain the myriad settings, dotfiles, and various tweaks I end up making to ensure I can properly do my job.

It all started at work. We're just about to enter standup, and a fellow engineer (Henry, you are to blame 😛) and I are talking software and computers when the topic of Nix comes up. For those of you not in the know (I can certainly count myself in that group before this journey), Nix is a 'declarative' package manager, meaning instead of running commands to add packages or general changes to your system, you instead add those packages and changes to a configuration file, and then Nix applies that configuration file against your computer to apply the changes. These changes can be committed to a Git repository, meaning you can define your entire system in configuration files.

I had a separate issue at the time. Volta, our chosen package manager for Node, is no longer receiving regular updates, and I needed to migrate us to something sustainable. Light bulbs go off in my head, and I decide to bury that illuminated head in a bucket full of Nix for the better part of a month (strictly as part of my learning and development time, I promise).

When I come back to the team, I had explored Nix and created a bit of an IT tool wrapped around it, a basic CLI to allow them to conveniently set up an entire Nix environment, with the ability to add and remove packages without really interacting with Nix at all. I quickly become a Nix disciple at work, speaking the gospel to anyone who will listen (unfortunately for them, they often have to).

The system worked well (we're still actively using it at Tillo), though I realised it had equal application at home. I have a PC, a laptop, a small refurbished server from Amazon, and a Raspberry Pi, all running differing variants of Linux. I also semi-regularly visit my parents, where I still have a PC (the Pop!_OS one from earlier), and I always dread going back, knowing it's highly likely to implode when I next sudo apt upgrade -y.

What is an engineer supposed to do with newfound IT management superpowers and several devices itching for a new Linux distribution and orchestrated maintenance? It started innocently enough: migrating my existing laptop (Fedora) and PC (CachyOS) to use Nix as a package manager, and moving configuration and dotfiles across so Nix could manage them instead.

You quickly realise that a lot of time goes into a computer, be it Linux, Windows, or Mac, and we're always at risk of just losing it all, however within a week or so, I was able to wipe my laptop and restore it to an identical working environment in less than an hour, and for this reason I found that Nix alone was worth it, but I kept running into issues that would have been more easily resolved had I just bitten the bullet and dived fully into NixOS.

For the next few months, I kept an almost identical configuration across my work and home laptops, with only a few differences required for the Mac. We now also use Nix shells to manage those pesky Node versions!

At this point, I'd learnt that:

Nix can easily reproduce my system, saving me time if I ever need to do so again (e.g. a new laptop)
Nix can be used to more quickly onboard engineers at a company (sane defaults, modules and packages for different disciplines)
Lock files for installed packages help protect you from upstream changes (similar to my existing workflows with package lock files)
It gives better visibility into how engineers actually use their systems (your IT team will either love you or hate you for it)

However I still had the following issues:

NixOS has better documentation, and often references you'll find online point more towards NixOS, less towards Nix. It's a confusing blurry line for beginners.
Each machine in my life is physically different; If I wanted to create a shared configuration for all, with the guarantee of being as identical as possible across both, I'd have to switch to NixOS
Starting this journey, my configuration was a mess! Now that I had absorbed quite a bit of information, a configuration refactor was in order, and there's no better excuse to switch.

This is where the story of Nix ends. It does its job and does it well. But I wanted more. I could now reproduce my system with ease, yet the remaining pain points I had could be resolved with NixOS.

Starting with the existing Nix configuration I'd built up over the last few months, I decided to entirely refactor my computing life. Branching away from what I already had, I revamped the entire setup for NixOS, iterating over the course of a week to create a highly modular system that works for every device I own, and even other people's devices in my household.

If you're curious about such a configuration, you're in luck! I've also created a minimal template to help you bootstrap your way to a NixOS life: https://github.com/CRBroughton/nix-starter-template/tree/master/nixos-template/template

template/
├── flake.nix                              # Entry point
├── justfile                               # Common commands
├── lib/
│   └── default.nix                        # mkHost helper (wires up nixpkgs, home-manager, modules path)
├── modules/                               # Reusable, opt-in system modules
│   └── desktop/
│       └── gnome.nix                      # GNOME + GDM + Pipewire (uncomment in host to enable)
└── users/
    └── username/                          # Your user
        ├── default.nix                    # Home-manager config
        └── hosts/
            └── hostname/                  # Your machine
                ├── default.nix            # Host config
                ├── hardware.nix           # Hardware config (generated)
                └── vm-testing.nix         # VM settings (remove for real hardware)

The above is a folder map of the most minimal setup. I've been using Just, which is a super simple command runner to simplify those annoyingly long commands that you'll never quite remember.

Top level 'modules' can be re-used across any user, and any machine. Do you want GNOME on your laptop, and KDE on your desktop? Just swap out a single line of code in your hosts default.nix, and you have that desktop. This of course has opened the door to me trying 'all the things!', especially those desktops that previously I would have had to distro hop for (Hyprland soon?).

Each user has a dedicated folder, in which the 'hosts' folder has each machine the user owns (in my case, my PC, laptop, server and Pi). You can imagine a user might have common configuration across all machines, so those files can live in the users folder, however machines might have specific requirements for hardware or software, so those files are directly within their respective hosts folder.

Each machine has a vm-testing.nix, which allows the user to simply run just vm to run the entire system in a virtual machine. This has been a godsend when migrating to NixOS, allowing me to verify the entire system is working and safely knowing I haven't lost any packages I rely on.

And that's where I'm currently at. In summary, Nix has saved my sanity when it comes to maintaining various computers in my life (it sounds crazy, but I'm seriously considering moving my mother to NixOS just so I can remote manage her PC and deploy packages at my leisure). I no longer worry about the maintenance of machines hundreds of miles away from me, that I haven't turned on in a few months. I can hop between my laptop and my desktop, and get an identical experience, or if I choose to, 'fearlessly' swap out parts of that experience, knowing I can rollback if something goes wrong or completely change my setup without breaking changes being a worry.

If you're curious, you can find my full configuration here - https://github.com/CRBroughton/nix-configuration. And if you know me, I apologise in advance for talking about Nix.

How I've been trying to improve mocking with Zod

Craig Broughton — Fri, 27 Dec 2024 16:38:34 +0000

If you're a Frontend Engineer, you've likely been in a situation where you've been required to start implementing a feature before the API that serves the back end portion of that feature exists. Engineers will often turn to mocking to enable parallel development (meaning both the front-end and back-end portions of the feature are developed in parallel).

Mocking however can come with some disadvantages. The first and most obvious is that mocks can drift from the actual implementation, causing them to be unreliable. A second problematic issues is that mocks can often be verbose; With mocks that contain a lot of data, it might be unclear as to what a certain mock response is actually mocking.

The below data is an example of some data you might find in a code-base:

type Order = {
  orderId: string;
  customerInfo: CustomerInfo; // omitted these types for brevity
  orderDate: string;
  items: OrderItem[];
  paymentInfo: PaymentInfo;
  subtotal: number;
  shippingCost: number;
  tax: number;
  totalAmount: number;
  status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
  trackingNumber: string | null;
};

const mockOrders: Order[] = [
  {
    orderId: "ORD-2024-001",
    customerInfo: {
      id: "CUST-1234",
      name: "Alice Johnson",
      email: "alice.j@email.com",
      shippingAddress: {
        street: "123 Pine Street",
        city: "Portland",
        state: "OR",
        zipCode: "97201",
        country: "USA"
      }
    },
    orderDate: "2024-03-15T14:30:00Z",
    items: [
      {
        productId: "PROD-789",
        name: "Organic Cotton T-Shirt",
        quantity: 2,
        pricePerUnit: 29.99,
        color: "Navy",
        size: "M"
      },
      {
        productId: "PROD-456",
        name: "Recycled Canvas Tote",
        quantity: 1,
        pricePerUnit: 35.00,
        color: "Natural"
      }
    ],
    paymentInfo: {
      method: "credit_card",
      status: "completed",
      transactionId: "TXN-88776655"
    },
    subtotal: 94.98,
    shippingCost: 5.99,
    tax: 9.50,
    totalAmount: 110.47,
    status: "shipped",
    trackingNumber: "1Z999AA1234567890"
  },
  // Imagine more objects here, with various values changed...
];

The data I work with everyday looks a lot like this. Arrays of orders or some sort of customer focused information, featuring nested values that help populate tables, popups and cards detailed with all sorts of information.

As an engineer tasked with maintaining applications that heavily rely on such mocks, you might ask 'what is this particular object in the response mocking?'. I've often found myself scrolling through hundreds of examples just like the one above, being unsure as to what each objects purpose was.

As I've become more sure of myself as an engineer, I've tasked myself with solving the above issue; What if every mock could more easily display its purpose? What if an engineer only had to write the lines they were intending to mock?

Whilst playing around with some code and a library called Zod, I found the following method called parse, which attempts to validate incoming data against a known type:

const stringSchema = z.string();

stringSchema.parse("fish"); // => returns "fish"
stringSchema.parse(12); // throws error

This was a light-bulb moment; This little example in the Zod documentation was exactly what I had been looking for! If the parse method could accept a value and return it, then if I passed in a value, I would get it back. I also already knew that I could define default values to a Zod schema. What if passing an empty object would return a full object, with its values? Lo and behold it did; I could define default values on a Zod schema, and return the defaults:

const UserSchema = z.object({
  id: z.string().default('1'),
  name: z.string().default('Craig R Broughton'),
  settings: z.object({
    theme: z.enum(['light', 'dark']),
    notifications: z.boolean()
  }).default({
    theme: 'dark',
    notifications: true,
  })
});

const user = UserSchema.parse({}) // returns a full user object

Now I had a way to generate objects, however it was still not quite what I was looking for. What I really wanted was a way to only write the exact lines I was 'mocking'. A simple solution might look like:

const UserSchema = z.object({
id: z.string().default('1'),
name: z.string().default('Craig R Broughton'),
settings: z.object({
  theme: z.enum(['light', 'dark']),
  notifications: z.boolean()
}).default({
  theme: 'dark',
  notifications: true,
})
});


const user = UserSchema.parse({})
const overridenUser = {...user, ...{
  name: "My new name",
  settings: {}, // I would need to write every key:value for settings :(
} satisfies Partial<z.infer<typeof UserSchema>>} // overrides the base object

However this has it's own flaws; What if the value I wish to override is itself an object or array? I'd then have to manually type out each line that was previously required for that feature to continue to work and be mocked as expected, which defeats the purpose of our work in progress solution.

For a long while, this is as far as I had got, until very recently when I had another stab at improving the above. The first step was defining the 'API'; How did I want my users to interact with this functionality?

const UserSchema = z.object({
  id: z.string().default('1'),
  name: z.string().default('Craig R Broughton'),
  settings: z.object({
    theme: z.enum(['light', 'dark']),
    notifications: z.boolean()
  }).default({
    theme: 'dark',
    notifications: true,
  })
});

const user = zodObjectBuilder({
  schema: UserSchema,
  overrides: { name: 'My new name', settings: { theme: 'dark' } } // setting is missing the notifications theme :(
}); // returns a full user object with the overrides

The above API would allow the user to specify a schema of their choice, and then provide the appropriate overrides and return a user object! Of course we'd want to properly account for arrays as well as a single object. For that purpose, a simple type check against the incoming overrides type proved sufficient:

  // Some of the implementation of zodObjectBuilder
  if (overrides && Array.isArray(overrides)) {
    const objects: z.infer<T>[] = []
    overrides.forEach((override) => {
      if (config.preserveNestedDefaults) {
        const base = buildDefaultObject(schema)
        const newObject = merge(base, override)
        objects.push(newObject)
      }
      else {
        const base = schema.parse({})
        objects.push({ ...base, ...override })
      }
    })
    return objects
  }

The above is effectively the same code as before, however it's now encapsulating the parsing internally so users don't have to manually do so or know detailed information about Zods parsing method. As you might of guessed from reading through if/else statement included, we've also solved the preservation of nested objects and arrays through the use of a recursive builder function that parses each value and returns its default values specified in the Zod schema.

The above is quite a bit to wrap your head around, but the result is that a user can do the following:

const UserSchema = z.object({
  id: z.string().default('1'),
  name: z.string().default('Craig R Broughton'),
  settings: z.object({
    theme: z.enum(['light', 'dark']),
    notifications: z.boolean()
  }).default({
    theme: 'dark',
    notifications: true,
  })
});

const user = zodObjectBuilder({
  schema: UserSchema,
  config: { preserveNestedDefaults: true },
  overrides: { name: 'My new name', settings: { theme: 'dark' } }
}); // returns a full user object with the overrides, including nested values!

When providing the preserveNestedDefaults configuration option to the builder, a user can preserve the key value pairs within a nested object or array! This solves the issue of a user overriding a key that is not a primitive type like a string, and is instead a more complex type and retains all the values minus the ones we choose to override.

This has already been quite a read, so let us end with the result of all our hard work. Lets revisit that first mock, and how we could write it with zodObjectBuilder. First lets define our types and our default values, and pass the resulting schema into the zodObjectBuilder:

const addressSchema = z.object({
  street: z.string(),
  city: z.string(),
  state: z.string(),
  zipCode: z.string(),
  country: z.string()
}).default({
  street: "123 Pine Street",
  city: "Portland",
  state: "OR",
  zipCode: "97201",
  country: "USA"
});

const customerInfoSchema = z.object({
  id: z.string().regex(/^CUST-\d{4}$/),
  name: z.string().min(1),
  email: z.string().email(),
  shippingAddress: addressSchema
}).default({
  id: "CUST-1234",
  name: "Alice Johnson",
  email: "alice.j@email.com",
});

const paymentInfoSchema = z.object({
  method: z.enum(['credit_card', 'paypal']),
  status: z.enum(['completed', 'pending', 'failed']),
  transactionId: z.string()
}).default({
  method: 'credit_card',
  status: 'pending',
  transactionId: 'TXN-88776655'
});

const orderItemSchema = z.object({
  productId: z.string().regex(/^PROD-\d{3}$/),
  name: z.string().min(1),
  quantity: z.number().int().positive(),
  pricePerUnit: z.number().positive(),
  color: z.string().optional(),
  size: z.enum(['XS', 'S', 'M', 'L', 'XL', 'XXL']).optional(),
  variety: z.string().optional(),
  weight: z.enum(['8oz', '12oz', '16oz', '1lb']).optional()
}).default({
  productId: "PROD-001",
  name: "Sample Product",
  quantity: 1,
  pricePerUnit: 29.99,
  color: "Black",
  size: "M"
});

const generateOrderId = () => {
  const year = new Date().getFullYear();
  const randomNum = Math.floor(Math.random() * 1000).toString().padStart(3, '0');
  return `ORD-${year}-${randomNum}`;
};

const orderSchema = z.object({
  orderId: z.string().regex(/^ORD-\d{4}-\d{3}$/).default(generateOrderId()),
  customerInfo: customerInfoSchema,
  orderDate: z.string().datetime().default(new Date().toISOString()),
  items: z.array(orderItemSchema).min(1).default([orderItemSchema.parse(undefined)]),
  paymentInfo: paymentInfoSchema,
  subtotal: z.number().positive().default(29.99),
  shippingCost: z.number().nonnegative().default(5.99),
  tax: z.number().nonnegative().default(3.00),
  totalAmount: z.number().positive().default(38.98),
  status: z.enum(['pending', 'processing', 'shipped', 'delivered', 'cancelled']).default('pending'),
  trackingNumber: z.string().default('1Z999AA1234567890')
});

const orderItem = zodObjectBuilder({
  schema: orderSchema,
});

The above implementation will return a single object using all of the default values! But we can do better than that, we can now (with the help of a few overload definitions and internal parsing) create arrays of objects, perfect for the use case of mocking API responses:

const orders = zodObjectBuilder({
  schema: orderSchema, // Passing in that same schema from the previous example
  config: { preserveNestedDefaults: true },
  overrides: [
    { // Each object is a fully defined object with the default values! :)
      status: "delivered"
    },
    {
      status: "shipped"
    },
    {
      status: "pending"
    },
    {
      status: "processing"
    },
    {
      status: "cancelled"
    },
  ]
});

The above outputs an array of orders will the full default values, with overridden delivery statuses! Hopefully this demonstrates how the zodObjectBuilder function can minimise the effort required to create a new mock based on a reliable type safe schema.

With that little demonstration we've reached the end of my first article :) I hope you've enjoyed reading this journey of exploration into improving mocking. zodObjectBuilder is still being built, but it's serving my needs well to minimise mocked objects. If you'd like to play around with the current version, you can find it at https://www.npmjs.com/package/@crbroughton/ts-utils which includes the function.