This is the ninth post in my series about offline support in web applications. Today, I want to cover prefetching strategies: how to proactively prepare data for offline use, and more importantly, how to do it without hurting the user experience.

Why Prefetching Matters

If you only persist data that the user explicitly fetched, your offline support is technically correct — but practically limited.

The core issue is: users don’t know what will be available offline.

Imagine a todo app where a user opens a board while online, so the app fetches and stores its data. Later, they go offline and try to open an item from that board — something that, from their perspective, should just work. But since that specific item was never fetched before, it isn’t available, and the app feels inconsistent: the board is there, but the item isn't. It feels inconsistent.

Users don’t typically plan their navigation around connectivity, so in our example the app becomes unpredictable when offline. This leads to an important UX problem: a lack of trust. The user doesn’t know what will work. This inconsistency is probably worse than a full failure. At least with a full failure, the user understands the limitation.

Prefetching is a way to fix that. Instead of relying purely on user-driven fetching, we proactively prepare data ahead of time. Offline support becomes much more useful when the system, not the user, does the planning.

Step 1 — Decide When Prefetching Happens

First, we need to choose how we want to handle data prefetching for users.

Automatic Prefetching

The app automatically gets data in the background without the user doing anything. At first, this sounds ideal — and in many cases, it is. But there’s a catch. If you’re not careful, prefetching competes for resources in a critical moment: the first interaction.

Imagine this:

1. The user opens the app.

2. The UI renders.

3. The user starts interacting with the application.

4. At the same time, 20 background requests start firing.

The user network requests are effectively competing for resources with prefetching requests. Even if everything is working, the app will feel sluggish. Interactions become less responsive. This doesn’t feel like a great first experience.

Automatic prefetching optimises for readiness, but often at the cost of responsiveness. In my experience, naive automatic prefetching often does more harm than good.

User-controlled Prefetching

The alternative is to give control to the user. This could mean a “Prepare for offline” button, a settings toggle or a specific flow (e.g. downloading a project). This avoids the performance problem entirely. But it introduces another one: discoverability.

Users need to:

1. Know the feature exists.

2. Understand when to use it.

3. Remember to trigger it.

User-controlled prefetching optimises for performance, but often at the cost of adoption. In practice, this often means the feature is underused — or not used at all.

Hybrid Approach

In most cases, I find that a hybrid approach works best: some level of automatic prefetching combined with user-triggered actions for larger datasets.

This gives you a decent default behavior, with an escape hatch for power users, leading to more predictable performance characteristics. The key is to keep automatic prefetching conservative.

Step 2 — Introduce Prefetching in Your Data Layer

Once you’ve decided when to prefetch, the next step is making it possible in your data layer.

Here's an example with using React Query, which makes this quite straightforward. Typically, this is how you'd fetch a list of todos.

const fetchTodo = async (id: string) => {
  return request.get(`/todos/${id}`);
};

export const useTodo = (id: string) => {
  return useQuery({
    queryKey: queryKeys.todo(id),
    queryFn: () => fetchTodo(id),
  });
}; 

Here's what will allow us to prefetch the same data.

const fetchTodo = async (id: string) => {
  return request.get(`/todos/${id}`);
};

const todoQueryOptions = (id: string) => {
  return queryOptions({
    queryKey: queryKeys.todo(id),
    queryFn: () => fetchTodo(id),
  });
};

export const prefetchTodo = (
  queryClient: QueryClient,
  id: string,
) => queryClient.prefetchQuery(todoQueryOptions(id));

export const useTodo = (id: string) => {
  return useQuery(todoQueryOptions(id));
};

You now have a reusable query definition, a function to fetch data without rendering a component, and a clear separation between reading and preparing data.

Step 3 — Control the Impact of Prefetching

This is where most nuanced work happens. Prefetching is relatively easy to add — but hard to do well. If you take one thing from this post, it’s this:

Prefetching should never compete with the user.

Here are a few practical rules I try to follow.

Limit Concurrency

Firing dozens of requests at once is rarely a good idea. Instead, I recommend introducing a simple concurrency limit. Even a small cap (1–2 concurrent requests, possibly with delay in between) can significantly improve perceived performance.

Here’s a minimal example:

const MAX_CONCURRENT_PREFETCH = 3;

let active = 0;
const queue: (() => Promise<unknown>)[] = [];

const runNext = () => {
  if (active >= MAX_CONCURRENT_PREFETCH || queue.length === 0)
    return;

  const task = queue.shift();
  if (!task) return;

  active++;
  
  task().finally(() => {
    active--;
    runNext();
  });
};

export const schedulePrefetch = (task: () => Promise) => {   
  queue.push(task);
  runNext();
};

You can then wrap your prefetch calls:

schedulePrefetch(() =>
  queryClient.prefetchQuery(todoQueryOptions(id))
);

This is intentionally simple, but it already gives you much better control.

Prefetch When the App Is Idle

One of the simplest and most effective strategies is to only prefetch when the app isn’t busy. The browser gives you a useful primitive for this: requestIdleCallback.

const scheduleIdlePrefetch = (task: () => void) => {
  if ('requestIdleCallback' in window) {
    requestIdleCallback(() => task());
  } else {
    // Fallback
    setTimeout(() => task(), 1000);
  }
};

Usage:

scheduleIdlePrefetch(() =>
  schedulePrefetch(() =>
    queryClient.prefetchQuery(todoQueryOptions(id))
  )
);

This ensures that prefetching happens when the main thread is less busy, which helps preserve responsiveness.

Respect Network Conditions

Not all connections are equal, and prefetching blindly can be wasteful — or even harmful. You can use the navigator.connection API to make basic decisions:

const shouldPrefetch = () => {
  const connection =
    (navigator as any).connection ||
    (navigator as any).mozConnection ||
    (navigator as any).webkitConnection;

  if (!connection) return true;

  const slowTypes = ['slow-2g', '2g'];
  if (slowTypes.includes(connection.effectiveType)) {
    return false;
  }

  if (connection.saveData) {
    return false;
  }

  return true;
};

Usage:

if (shouldPrefetch()) {
  scheduleIdlePrefetch(() =>
    schedulePrefetch(() =>
      queryClient.prefetchQuery(todoQueryOptions(id))
    )
  );
}

This doesn’t need to be perfect — even basic checks can make a noticeable difference.

Be Selective About What You Prefetch

Not all data is worth prefetching. First, focus on high-probability user paths, small to medium payloads and data required for core flows. You can skip rarely accessed data and large datasets.

A good rule of thumb:

Prefetch what the user is likely to need next — not everything they might need.

Prioritise User-Initiated Requests

This is the last point I'll bring up. In the beginning of this section, I mentioned that user actions should always win. That means not saturating the network, avoiding blocking important requests and being ready to pause or deprioritise prefetching.

In practice, this is harder than it sounds. Doing this properly usually requires a centralised request handling mechanism, awareness of in-flight requests and the ability to cancel or deprioritise prefetch requests.

I won’t go deep into this here, but it’s worth calling out — this is where simple setups often hit their limits. If you reach this point, it’s usually a sign that prefetching should be treated as a first-class concern in your data layer — not just an add-on.

Takeaways

Prefetching is one of those things that sounds simple but has a lot of nuance.

Done well, it makes your offline experience feel seamless and reliable. Done poorly, it slows down your app for everyone and wastes resources.

To summarise:

• Persisting fetched data is not enough for great offline UX

• Prefetching improves predictability and trust

• A hybrid approach usually works best

• Control when and how prefetching happens — carefully

In the next part, I’ll focus on a more concrete (and often overlooked) piece of the puzzle — how to reliably serve images when there’s no network at all.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further Reading and References

• MDN — requestIdleCallback

• Photo by Anna Maria Gnadl on Unsplash

This post is an attempt to capture how I currently work with AI agents when building software. Think of it as a snapshot in time rather than a definitive guide.

About six months ago I wrote that I was getting roughly 50% of my working code from AI agents. A lot has changed since then — and so has my approach.

AI Agent is Just Another Engineer

As AI tools have advanced, my workflow has evolved accordingly. Now, I believe that in most cases, there is no legitimate reason to write code by hand anymore.

I will only type code manually when I’m confident it’s faster than prompting an agent — which usually means a few lines at most. If the change requires thinking about structure, edge cases, or multiple files, I involve an agent. In practice, this means 95–100% of the code I deliver is AI-generated. My role shifts more toward guiding the work than writing the implementation.

More importantly, agents are no longer just a code generation tool for me. They are part of the entire development workflow. Instead of thinking about them as autocomplete on steroids, I treat them more like collaborators that help with:

1. Exploring possible approaches.

2. Structuring work.

3. Implementing changes.

4. Reviewing code.

5. Refining the final solution.

What helped me the most was adopting a simple mental model:

Work with AI as if you're guiding another engineer through a task.

In that situation, you would typically explain the problem clearly, share the relevant context, discuss constraints, agree on a rough plan, review the implementation and refine the result together.

Working with AI agents turns out to be surprisingly (or perhaps unsurprisingly) similar. The quality of the result is largely determined by how well the work is prepared and guided.

Once I started thinking about agents as collaborators rather than tools, my workflow naturally evolved around that idea. What emerged is a simple process that I now follow for most non-trivial changes.

The workflow

The process I currently follow looks roughly like this.

Step 1 — Describe the Problem Clearly

Everything starts with a clear problem description.

This step sounds trivial, but it's where many failures start. You have to know what the problem is. Even better if you roughly know what the solution should look like. If the problem description is vague, the agent will produce vague solutions.

I try to ensure the description covers four elements:

1. The exact problem.

2. Current behavior.

3. Desired behavior.

4. Constraints.

Here's a simplified example of this pattern.

Problem:
Offline mutations sometimes disappear when the page reloads.

Current behavior:
The foreground queue stores mutations in memory.

Desired behavior:
Mutations should persist across reloads using IndexedDB.

Constraints:
- Must not block UI rendering
- Must support retry logic
- Should work with React Query mutations

This does two things — it forces clarity of thinking and it gives the agent a precise target. In my experience, spending an extra minute here saves several iterations later.

Step 2 — Prepare the Context

Before touching the codebase, I usually expand the context around the problem. This step is essentially research with the help of agents, either outside or within the codebase, depending on how much I want the agent to recognize existing patterns.

Typical questions I ask include:

• What are common solutions to this problem?

• What patterns are used in similar systems?

• What trade-offs should I consider?

• What implementation approaches might work here?

At this stage I’m not asking the agent to plan or write code yet. Instead, I’m gathering ideas, architectural options, potential pitfalls and possible implementation patterns.

The goal is to enter the codebase with a rough map in mind.

Step 3 — Plan the Implementation

Once the problem is clear and the context is prepared, I ask the agent to help produce an implementation plan. I do this for almost every task and I highly recommend it, even if it feels like overkill. In my experience, it drastically reduces the number of iterations needed after the initial implementation attempt.

When creating a plan, the most important rule here is:

Encourage the agent to ask questions.

You probably haven't thought of everything you should up front and you certainly didn't specify everything in your prompt. Have the agent discuss edge cases, simplify the approach, or describe assumptions. Keep the discussion going as the agent reads relevant files, identify affected areas of the codebase, propose structural changes, and outline the implementation steps.

In my experience, a good plan has two characteristics:

1. Concrete enough to visualise the solution. You should be able to roughly imagine how the system will look after the change.

2. Flexible enough to benefit from delegation. Agents are most useful when they can still adjust implementation details while working.

The result should feel like a clear but adaptable roadmap.

Step 4 — Implementation and Iteration

Now the agent begins implementing the plan, and what follows is highly iterative.

Even with a good plan, I expect several things to happen — imperfect structure, missed edge cases, minor architectural drift or suboptimal abstractions.

That’s normal. Instead of trying to get everything perfect in one prompt, I treat this phase as guided iteration. The loop usually looks like this — the agent implements a change, I briefly review the diff and check the behavior and request further refinements.

During this phase I typically focus on three things in this order.

1. Behavior. Does the feature actually work how it should?

2. Structure. Is the code organised in a way that makes sense? Is it going to be easy to maintain and change over time?

3. Readability. Would another engineer (or agent) understand this code quickly?

I usually continue this process until I'm happy with the functionality and the code structure.

Step 5 — Full Review Pass

Once the feature works, I always run a final review pass. This step is important because agent-generated code can accumulate small issues during iteration.

There are multiple layers to it. First, I read through the code myself. Second, I usually ask the agent to do the same for me. Finally, I add additional tools on top, like CodeRabbit or Cursor Bugbot, to cover the change holistically, double check alignment with project rules, and find subtle bugs.

Step 6 — Ship 🚀

At this point the feature should be ready to go.

The important part is that the implementation has already gone through multiple structured passes — planning, iteration and review. Not every change requires every step in this workflow, but in my experience, most meaningful changes benefit from the full process.

The key idea is not the exact sequence — it's the process discipline.

Conclusion

To sum it up in one sentence:

Agentic software engineering is mostly about structured problem decomposition and process discipline.

The better the process, the more effective the agents become.

This is just a snapshot in time. Six months ago my workflow looked different, and six months from now it probably will again.

For now, most of my work still involves a single agent at a time. One direction I'm already exploring is parallel agent workflows — orchestrating multiple agents working on different parts of a problem simultaneously.

Either way, it’s a fascinating time to be building software.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further Reading and References

• A structured workflow for building features with AI coding agents by Daniel Dewhurst

• An LLM Codegen Hero's Journey by Harper Reed

• Photo by Tine Ivanič on Unsplash

In this post, I want to show how the queue is actually used inside a React application — how we safely store offline mutations and sync them when connectivity returns. In other words, we’re moving from queue implementation to application integration.

Accessing the Queue from React

In the third article in this series, we integrated the queue with React using a small context factory. The goal was simple: ensure there is exactly one queue instance per persisted queue, while still making it easily accessible throughout the component tree.

The factory creates three things — a QueueProvider, a useQueue hook and a configured queue instance.

Here’s the configuration snippet from that article as a quick reminder:

const { QueueProvider, useQueue } = createQueueContext(() => ({
  name: 'todo-mutations',
  storageKey: 'todo-mutation-queue-v1',
  identityKey: (item) => item.id,
  processor: async (item) => api.post('/todos', item),
}));

The important part is that the queue instance is created once and shared. Every component interacting with the queue talks to the same object, which prevents race conditions and keeps the persisted state consistent.

In practice, integration is straightforward. We wrap the application (or a feature subtree) with the provider:

export default function App() {
  return (
    <QueueProvider>
      <AppContent />
    </QueueProvider>
  )
}

From this point on, any component can call useQueue() and interact with the queue directly.

With the queue accessible throughout the application, we can now focus on the part that actually matters: using it to capture offline mutations. Let’s start with the most common scenario: executing mutations conditionally depending on the network state.

Capturing Offline Mutations

We need the queue for our mutation logic. In this example, we’re updating the status of a todo item. The key idea is simple:

• Offline: store the intent in the queue.

• Online: execute the request immediately.

The key idea is simple: mutations should behave the same from the UI perspective, regardless of network state. The mutation itself decides whether to execute immediately or store the action in the queue.

export const useTodoStatusUpdate = (id: string) => {
  const queue = useQueue();
  const isOnline = useNetworkStatus();

  return useMutation({
    networkMode: 'always',
    mutationFn: async (status: string) => {
      if (!isOnline) {
        await queue.enqueue({ id, status });
        return { queued: true };
      }

      await api.post(`/todos/${id}`, { status });
      return { queued: false };
    },
  });
};

When the user is offline, we store the user’s intent in the queue. This means the action is not lost. The application can safely retry it later. When the user is online, we call the API immediately and complete the mutation normally.

This approach keeps the mutation API consistent while transparently supporting offline scenarios. With this pattern, the UI doesn’t need to know about the queue directly. It simply calls the mutation, and the mutation decides whether to enqueue or execute.

Interlude: Knowing if the User Is Online

In the code we looked at, we mentioned that we can check whether the user is online. Detecting whether the user is online sounds trivial, but it turns out to be surprisingly nuanced.

Browsers expose a property called navigator.onLine. Based on the MDN documentation:

The onLine property of the Navigator interface returns whether the device is connected to a network.

if (!navigator.onLine) {
  // Definitely no network
}

At first glance this looks like exactly what we need. Unfortunately, it's not always reliable enough for application logic.

The property returns a boolean: true when the browser detects the device has some network connection, false when the browser detects there is no connection. Browsers typically determine this using OS-level heuristics such as whether a network interface is active or whether the device is connected to Wi-Fi or Ethernet.

There are several practical issues with this approach.

1. It does not guarantee Internet access. A device might be connected to a Wi-Fi network that has no Internet connectivity. In that situation, navigator.onLine still returns true.

2. Browser and OS differences. Some browsers treat any local network connection as "online", even if external connectivity is unavailable. Others behave differently.

3. Delays and false positives. The online / offline events can lag behind real connectivity changes. Short network interruptions may also go undetected.

In practice, your best bet is to use a two-step approach — use navigator.onLine as a quick heuristic and verify connectivity with a real network request.

fetch('/health-check', { method: 'HEAD' })
  .then(() => {
    // Internet reachable
  })
  .catch(() => {
    // Still offline or server unreachable
  });

This ensures that the browser is connected to a network, that network has access to the internet, and it can actually reach your backend. In our example hook (useNetworkStatus), this logic can be encapsulated so the rest of the application doesn't need to worry about the details.

Showing Pending Work

When users work offline, actions are queued but not immediately executed. This means the UI should communicate that there is pending work waiting to sync. Our approach is to subscribe to the queue state and check whether the current item appears in the queue.

Here is a simplified example component.

type TodoCardProps = {
  id: string;
  title: string;
  description?: string;
}

type TodoQueueState = {
  isPending: boolean;
  isProcessing: boolean;
}

export function TodoCard({ id, title, description }: TodoCardProps) {
  const queue = useQueue();
  const [state, setState] = useState<TodoQueueState>({
    isPending: false,
    isProcessing: false,
  });

  useEffect(() => {
    const unsubscribe = queue.subscribe((s) => {
      setState({
        isProcessing: s.isProcessing,
        isPending: s.items.some((item) => item.id === id),
      });
    });

    return unsubscribe;
  }, [queue, id]);

  return (
    <Card>
      <CardTitle>
        {title}
        {state.isPending && !state.isProcessing && (
          <Badge>
            Pending sync
          </Badge>
        )}
        {state.isProcessing && (
          <Spinner size="sm" />
        )}
      </CardTitle>
      <CardDescription>{description}</CardDescription>
    </Card>
  );
}

When the queue state changes, we update the UI state to know if the queue is processing or if this item is in the queue.

From there, the UI can show helpful indicators such as a “pending sync” badge and a spinner while processing. The exact UI depends on the application, but the important part is that users can see that their action was captured, even if it hasn’t reached the server yet.

In my experience, this greatly improves user trust when working offline.

Running the Sync

Finally, we need to decide when the queued work should be processed.

In this series, I intentionally keep the sync model simple: with the foreground queue model, queue runs only when the user transitions from offline to online. This keeps the implementation predictable and avoids overlapping sync processes.

Here's a simplified component example that handles this automatically.

export function QueueAutoSync() {
  const queue = useQueue();
  const isOnline = useNetworkStatus();

  useEffect(() => {
    // Run when status changes to online...
    if (isOnline) {
      queue.sync()
    }
  }, [isOnline, queue]);

  return null;
}

This component doesn't render anything. Its only responsibility is to observe the network status and trigger a sync when connectivity is restored.

One small caveat here: depending on your application, you may also want additional triggers such as manual “Sync now” actions, sync pausing when the user goes back offline, periodic background sync or syncing on app focus. Starting with “sync when connection is restored” is often a good default.

Conclusion

That's it for today! In this post, we moved from the queue implementation to how it integrates with a React application.

Here's what we've covered:

• expose and consume the queue through React Context

• enqueue mutations when offline and execute them immediately when online

• show pending work in the UI using state listeners

• run a sync when connectivity returns

The queue captures user intent immediately and executes it when the network allows, making offline interactions reliable without complicating the UI.

Now that we know how mutations behave offline, the next step is improving the read side of the application — starting with data prefetching strategies.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further Reading and References

• Photo by John Price on Unsplash

So far, the queue processes each mutation exactly once. If it succeeds, we’re done. If it fails, we mark it as failed and move on. That’s a reasonable baseline, but in real-world offline scenarios it breaks down quickly.

In this post, I want to focus on error handling and retry strategies. In particular, how to handle transient failures automatically, without pushing that complexity or frustration onto the user.

Why a single attempt isn’t enough

In the implementation so far, the foreground queue attempts to process each item exactly once. If it succeeds, great. If it fails, we mark it as failed and move on. That’s a reasonable starting point, but in practice it’s not enough.

The main issue is that failures during sync can be transient — the network might briefly drop, the backend could be restarting, or unavailable for a few seconds. None of these mean the mutation itself is invalid — they just mean now is a bad time to process it.

When everything happens online, this is usually fine. If a form submission fails, the user sees an error and can retry immediately. The context is still fresh, the UI is still on screen, and retrying is typically one click away. Placing that burden on the user is acceptable, and in many cases expected.

Offline workflows are very different.

An offline mutation may have been recorded minutes or hours ago. By the time the app comes back online and starts syncing, the user may be doing something entirely unrelated. Asking them to manually retry a background failure at that point is both disruptive and unrealistic. From the user’s perspective, the action already happened. They filled in the form, pressed submit, and moved on. Any failure during sync is an implementation detail they shouldn’t have to care about unless it truly cannot be resolved.

This is where retries become essential. We can smooth over temporary issues without involving the user at all by adding automated retries. Only after multiple attempts should we consider the mutation genuinely failed and surface that state to the user. To put it in one sentence: assume failures are temporary until proven otherwise.

With all of this in mind, let’s zoom in and talk about retry strategies.

Exponential backoff for foreground retries

There are different strategies you can choose from. Linear retries, fixed delays, adaptive algorithms, circuit breakers — it’s a deep topic. I won’t be diving into all of them here. If you want a broader overview, Sam Who wrote a great article that’s well worth reading.

For foreground queues in offline-capable apps, I find exponential backoff hits a good balance between effectiveness and simplicity.

What exponential backoff actually means

Exponential backoff is a retry strategy where the delay between retry attempts increases exponentially after each failure, usually by doubling, until it reaches a maximum cap. Instead of retrying immediately or waiting a fixed amount of time, each failed attempt waits longer than the previous one.

A typical sequence might look like this:

• 1st retry after 500ms

• 2nd retry after 1s

• 3rd retry after 2s

• 4th retry after 4s

• …until a retry limit is reached

This simple change in timing has surprisingly large effects on system behaviour:

• Reduced load on struggling services. When many clients fail at once, immediate retries can create a thundering herd. Backoff spreads retries out over time instead of amplifying the problem.

• Better odds of success for errors. Short outages often resolve themselves quickly. Waiting a bit before retrying dramatically increases the chance that the next attempt succeeds.

Finally, a few guardrails are essential to keep retries from turning into hidden problems.

• Cap the delay. Without a cap, delays can grow so large that retries become effectively useless or block important resources for too long.

• Limit the number of retries. If something has persistently failed six times, continuing might no longer make sense.

• Add jitter. If many clients retry with the same timing, they can still synchronise. Adding a small random offset (jitter) to each delay helps spread retries out and avoids retry spikes.

This usually translates into fewer visible errors and less aggressive retry noise while the user is waiting.

With the strategy chosen, the remaining work is the implementation: capture retry state, compute delays, and teach the sync loop how to wait. Everything that follows assumes retries are safe — meaning the mutation is idempotent or can tolerate last-write-wins semantics. I’ll come back to cases where this isn’t true at the end.

Retry configuration

We'll start by adding configuration for the retries for our queue. The shape below captures all the controls needed to implement the exponential backoff strategy.

export interface BackoffConfig {
  baseDelay?: number; // Default: 500 ms
  maxDelay?: number; // Default: 30 s 
  maxRetries?: number; // Default: 5
  jitter?: boolean; // Default: true
}

Implementing backoff logic

Let’s start with drafting a simple module specifically for backoff. We’ll need a couple of utility functions to help us track and manage items in backoff. I’ll briefly explain what each function does without going into the implementation details, as they are mostly straightforward.

// Checks if an item should be retried based on attempt count.
export function shouldRetry(
  attemptCount: number,
  config: BackoffConfig = {}
): boolean {}

// Calculates the remaining delay until an item is ready for retry.
// Accounts for elapsed time since last attempt.
export function getRetryDelay(
  attemptCount: number,
  lastAttemptAt: number | null,
  config: BackoffConfig = {}
): number {}

These two functions will be needed to implement the retries in out startSync function in the Queue class. I won't include the entire function implementation, but I'll add the important parts here (I'll indicate unchanged sections with comments).

export class Queue<T> {
  async startSync(): Promise<SyncResult<T>> {
    // Block unchanged compared to the previous posts...

    // Track items already reported as failures...
    const failureIds = new Set<string>();

    try {
      // Single ongoing processing loop (now with retries)
      while (true) {
        // Block unchanged compared to the previous posts...

        // Keep track of items that are to be removed...
        const itemsToRemove = new Set<string>();
        // Keep track of items that are to be updated (we need to update attempt info)...
        const itemsToUpdate = new Map<string, QueueItem<T>>();
        // Keep track of items in backoff...
        const itemsInBackoff: Array<{ item: QueueItem<T>; delay: number }> = [];

        for (const item of items) {
          // Block unchanged compared to the previous posts...

          // Check if we can still retry...
          if (!shouldRetry(item.attemptCount, this.config.backoff)) {
            // Check if we haven't reported this item yet...
            if (!failureIds.has(item.id)) {
              failureIds.add(item.id);
              result.failure.push(item);
            }
            continue;
          }

          // Caclucate the backoff delay for an item and the current attempt...
          const delay = getRetryDelay(
            item.attemptCount,
            item.lastAttemptAt,
            this.config.backoff
          );

          // Check if we still need to wait...
          if (delay > 0) {
            itemsInBackoff.push({ item, delay });
            continue;
          }

          // Otherwise, the item is ready to be processed...
          try {
            // Block unchanged compared to the previous posts...
          } catch (error) {
            // The item processing has failed...
            // We no longer mark it as failure, but update the information,
            // so that we can continue retries in the next loop...
            itemsToUpdate.set(item.id, {
              ...item,
              attemptCount: item.attemptCount + 1,
              lastAttemptAt: Date.now(),
            });
          }
        }

        // All items have been processed...
        await this.withLock(async () => {
          const currentItems = await this.loadItems();

          const updatedItems = currentItems
            // Remove the items marked to be removed (success)...
            .filter((item) => !itemsToRemove.has(item.id))
            // Update the items in backoff...
            .map((item) => itemsToUpdate.get(item.id) ?? item);

          await this.saveItems(updatedItems);
        });

        // Check if there are items in backoff...
        if (itemsInBackoff.length > 0) {
          // Find the shortest delay...
          const minDelay = Math.min(...itemsInBackoff.map((i) => i.delay));
          // ...and wait
          await this.sleep(minDelay);
          continue;
        }

        // No items processed successfully or failed...
        // There's nothing else to process...
        if (itemsToRemove.size === 0 && itemsToUpdate.size === 0) {
          break;
        }
      }
    } finally {
      // Block unchanged compared to the previous posts...
    }

    return result;
  }
}

Here’s what we’ve effectively implemented in the sync loop:

1. We run an infinite loop with an inner loop over all queued items. This is where the “loop-in-a-loop” structure becomes useful. Previously, we processed each item exactly once. Now, we may process the same item multiple times — up to the maximum number of attempts allowed by the backoff configuration. The outer loop only exits when these conditions is met—no items were processed in a full pass and no items are currently waiting in backoff. At that point, there’s nothing left to do and the sync is finished.

2. Before processing an item, we first check whether it’s still eligible for retries. This is where we respect the backoff configuration and the current attempt count. If the item has already exhausted all allowed attempts, we mark it as failed and exclude it from further processing. Importantly, we ensure each failed item is reported exactly once, even if the loop continues for other items.

3. We compute the retry delay for the item. This determines whether enough time has passed since the last attempt, based on the current attempt count and the item’s last processing timestamp. If the item isn’t ready yet, we don’t try to process it. Instead, we add it to a list of items that are currently in backoff and move on to the next item.

4. Once we’ve looped over all items, we check whether any are waiting in backoff. If so, we find the smallest remaining delay across them and wait for exactly that duration (we’ll expand on this idea in the next section). This ensures the sync loop wakes up only when the next item becomes eligible for processing, avoiding unnecessary polling or busy waiting.

There's one more interesting aspect to discuss: how waiting for items in backoff interacts with sync pausing.

Making sure syncing can still be paused

You might remember that our queue supports pausing via the pauseSync method. Before retries were introduced, this worked well enough. Processing was always asynchronous, but calling pauseSync would take effect immediately after the current attempt finished.

Retries change that behaviour.

With exponential backoff in place, the syncing function may now sit idle for several seconds, waiting for the next item to become ready for processing. If we do nothing, the effects of calling pauseSync would only become visible after that wait finishes. That’s not great — pausing should be observable immediately, even if the sync loop is currently waiting.

The root problem here isn’t retries themselves, but time-based waiting. Once we start awaiting delays, those waits need to be cancelable. That’s why we’ve introduced an interruptible sleep function.

Here’s a simplified version of how this can be implemented.

export class Queue<T> {
  // Calling results in interrupting sleep function...
  private interruptSleep: (() => void) | null = null;

  private async sleep(ms: number): Promise<void> {
    return new Promise<void>((resolve) => {
      // When `interruptSleep`, the promise resolved immediately...
      this.interruptSleep = resolve;
      setTimeout(() => {
        // Otherwise, it resolves when the timeout function is called...
        this.interruptSleep = null;
        resolve();
      }, ms);
    });
  }

  pauseSync(): void {
    this.isPaused = true;
    // We interrupt sleep when syncing is paused...
    this.interruptSleep?.();
    this.interruptSleep = null;
  }
}

Conceptually, this turns time-based waiting into a cancelable operation.

When the sync loop is waiting for the next retry window, calling pauseSync now immediately resolves the pending sleep. This allows the loop to observe the paused state right away instead of being stuck waiting for a timeout to expire. This implementation can still leave a pending timeout behind, which isn’t ideal but acceptable for a simplified, illustrative example.

When retries get complicated

I want to close with a few points about edge cases and broader system considerations. Our offline todo status example has several properties that make retries and backoff much simpler than they might be in other scenarios.

Most importantly, we can accept last-write-wins semantics. That immediately removes the need for explicit conflict resolution. On top of that, the status update itself is idempotent — calling the mutation twice has the same effect as calling it once. Given a single client (or last-write-wins), retries are safe by default.

These properties are convenient, but they don’t generalize to all systems. In more complex setups, there are a few additional factors you’ll likely need to account for. Most of them require explicit back-end support.

• Request idempotency. For non-idempotent operations (for example, “charge a credit card” or “append to a log”), retries require extra safeguards. Common approaches include transaction tokens, client-generated IDs, or server-side deduplication.

• Non-retryable errors. Not all failures should be retried. Client-side errors (such as certain 4xx responses) often indicate permanent failure. Your sync logic should be able to recognize these cases and stop retrying early.

• Conflict resolution. Once multiple clients or concurrent updates are involved, conflict resolution becomes unavoidable. A simple approach is to refetch the latest state before mutating, which can work but is still prone to race conditions. More robust solutions require explicit conflict resolution on the back end, often combined with sending the initial state from the client so the server can detect and resolve conflicts deterministically.

The right approach to retries ultimately depends on the type of mutation. If you can accept last-write-wins, retries relatively simple — no special handling is required around the edges. If you can’t, retries quickly turn into a coordination problem that spans both the client and the back end.

Summary

That’s it for today. We’ve covered why retries are a core requirement for offline-first syncing, not just a nice-to-have, and how to go about implementing them. Here are the key takeaways:

• Submission failures can be temporary. Network hiccups and brief backend outages shouldn’t surface as user-facing errors. Automated retries let the system absorb these issues quietly.

• Exponential backoff is a good default. It’s simple to implement, reduces load on struggling services, and significantly improves success rates compared to immediate or fixed retries.

• Guardrails matter. Capping delays, limiting retries, and adding jitter prevent retries from turning into hidden performance or reliability problems.

• Retries change control flow. Once you introduce waiting, we must handle time explicitly.

• Retry safety depends on semantics. Idempotent, last-write-wins mutations make retries easy. Non-idempotent operations, permanent errors, and conflicts require explicit backend support and more careful coordination.

In the next article, I’ll shift gears and look at data prefetching, and how proactive data access fits into an offline-capable architecture.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Future reading and references

• Photo by Maria on Unsplash

• Retries — An interactive study of common retry methods by Sam Rose

Today, we’re switching gears a little and moving closer to the user interface layer. We’ll cover how to expose queue state, how UI components subscribe to it, and how to wire everything into React without turning the queue into yet another state store.

Subscribing to queue state

Let’s start with exposing the queue state. I want React components to react to changes in a way that doesn’t involve sharing all of the queue state with the whole React component tree.

State as a derived view

The source of truth for the queue is the list of items stored in IndexedDB. In practice, the UI usually needs a bit more context than just “what’s in the database”, so I expose a small, read-only snapshot. I treat this snapshot as a derived view — it’s mainly for display and indicators, not for driving business logic.

export interface QueueState<T> {
  items: Array<QueueItem<T>>;
  isProcessing: boolean;
  isPaused: boolean;
}

A few important constraints:

• The queue itself is the only place that reads and writes this state.

• I don’t need full, reactive synchronisation like you’d expect from a state management library.

• IndexedDB is async, so any snapshot can technically be stale.

That last point is worth calling out. Because all reads go through async APIs, there’s always a chance the state you’re looking at is slightly out of date. For this use case—showing indicators or counts in the UI—that trade-off is most likely acceptable. Just keep it in mind and avoid relying on this state for critical logic.

A simple subscription pattern

I decided to go with a simple subscription pattern for publishing the queue state updates. Instead of pushing state continuously, I let the queue decide when listeners should be notified.

From the consumer’s point of view, it looks like so:

queue.subscribe((state) => {
  console.log(state.items.length);
});

The UI subscribes, reacts to updates, and doesn’t worry about how or when the state is produced.

Implementing subscriptions in the queue

Under the hood, this is implemented with a lightweight listener registry.

export type QueueListener<T> = (state: QueueState<T>) => void;

export class Queue<T> {
  private listeners = new Set<QueueListener<T>>();

  subscribe(listener: QueueListener<T>) {
    // Store `listener` function...
    this.listeners.add(listener);
    this.notifyListener(listener);
    // Allow to unsubscribe...
    return () => {
      this.listeners.delete(listener);
    };
  }

  private async notifyAllListeners() {
    this.listeners.forEach((listener) => this.notifyListener(listener));
  }

  private async notifyListener(listener: QueueListener<T>) {
    const state = await this.getState();
    // Notify a single listener with the current state
    listener(state);
  }

  private async getState() {
    const items = await this.read();
    
    return {
      items: [...items],
      isProcessing: this.isProcessing,
      isPaused: this.isPaused,
    };
  }
}

A few things are worth highlighting here:

• subscribe is a public method that registers a listener and returns an unsubscribe function.

• New listeners are notified immediately with the current state.

• Listeners are only notified when the queue explicitly calls notifyAllListeners.

That last point is intentional. Whenever the queue processes an item, pauses, resumes, or mutates storage, I manually trigger notifications, calling notifyAllListeners. You need to be aware that with this pattern, state updates won't be sent out automatically.

Additionally, because getState() is async, rapid successive notifications may resolve out of order. In my case, this hasn’t been an issue, but it’s something to be aware of if you extend this pattern.

This pattern makes it straightforward to build small UI features like showing “3 actions pending” or “queue is currently syncing”. In my experience, this level of state awareness strikes a good balance. It's simple and clear, yet it provides a good separation between the queue's internals and the UI.

React integration via context

Now we have everything we need to connect the queue to the UI layer. As mentioned in previous articles, my example will focus on React, but the same or similar principles can be applied to any other framework.

First of all, the queue is stateful, long-lived, and tied to a single IndexedDB key. Creating multiple instances is a fast path to race conditions and corrupted state. To eliminate this, the safest approach is to treat the queue as a singleton per feature and make it available once, for example through React context.

One queue, one configuration

In practice, it translates to the following requirement: there must be exactly one queue instance for any one persisted queue. That means:

• the configuration is defined once

• the queue instance is created once

• every component talks to the same object

This doesn’t mean there can only ever be one queue in the app—only that there should be one queue per storage key and feature. The solution I chose was a small factory that creates a context, along with a provider component and a hook for accessing a specific queue.

const { QueueProvider, useQueue } = createQueueContext(() => ({
  name: 'todo-mutations',
  storageKey: 'todo-mutation-queue-v1',
  identityKey: (item) => item.id,
  processor: async (item) => api.post(`/todos/${item.id}`, item.status),
}));

This keeps feature code clean. I define the config once, and from that point on I just use QueueProvider and useQueue. With this setup, integration is straightforward. I wrap the application—or just a feature subtree—with the provider.

Anywhere below that, I can call useQueue() and interact with the queue directly:

• enqueue new items

• start sync processing

• subscribe to state changes

There’s no extra indirection or proxy state. Components talk to the queue object itself.

The context factory

Here’s the factory implementation that makes this work.

export function createQueueContext<T>(configFactory: () => QueueConfig<T>) {
  // Define a context for the queue...
  const QueueContext = createContext<Queue<T> | null>(null);

  type QueueProviderProps = {
    children: ReactNode;
  }

  // Define a provider for the queue
  function QueueProvider({ children }: QueueProviderProps) {
    // Create the config using the factory function...
    const config = configFactory();
    // Create a ref to store the queue...
    const queueRef = useRef<Queue<T> | null>(null);

    if (!queueRef.current) {
      // Only create the queue once, so the reference to the object is stable....
      queueRef.current = new Queue(config);
    }

    return (
      <QueueContext.Provider value={queueRef.current}>
        {children}
      </QueueContext.Provider>
    );
  }

  // Define a hook to access the queue...
  function useQueue() {
    const ctx = useContext(QueueContext);
    if (!ctx) {
      throw new Error('useQueue must be used within QueueProvider');
    }
    return ctx;
  }

  return { QueueProvider, QueueContext, useQueue };
}

A few details here are worth calling out.

• Factory owns the configuration. That makes the queue explicit and self-contained, instead of relying on global setup or hidden dependencies.

• Queue instance is created exactly once. Using a ref ensures that React re-renders won’t recreate it.

• Provider only renders once. It always provides a stable reference to the same queue object, even if the state inside of the queue changes. In this case, using context is perfectly fine because we’re not pushing changing values through it. From React’s perspective, the context value is stable; all the change happens inside the queue.

• The hook gives direct access to the queue. From React’s point of view, the queue is just an external object. Components can call queue.enqueue() or queue.subscribe() without coupling UI renders to internal queue state.

Summary

That’s it! We covered the UI-facing side of a foreground queue and how it fits into a React codebase.

• The queue remains the single source of truth, backed by IndexedDB.

• The UI consumes a small, read-only snapshot of derived state.

• State updates are delivered through an explicit subscription mechanism.

• React context is used purely to share a single, long-lived queue instance.

• Components interact directly with the queue object, keeping concerns clearly separated.

This setup has worked well for me in practice. It’s simple, explicit, and avoids accidental complexity while still enabling useful UI feedback like pending counts or sync indicators.

In the next article, I’ll build the final piece that the queue implementation is still missing, diving into error handling and retry strategies—arguably the most subtle parts of making offline queues reliable.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further reading and references

• Photo by Sorina Bindea on Unsplash

We’ll look at how to make the queue correct and predictable under concurrent access: guaranteeing atomic read–modify–write operations, handling deduplication and bounded queue size at enqueue time, and running an explicit, single-flight sync loop that can be paused safely.

Atomicity and correctness

Using IndexedDB for queue storage is great because it doesn't stop users from interacting with the interface. Reads and writes to IndexedDB are asynchronous. However, this can lead to potential issues when reads and writes occur almost simultaneously.

Imagine that during a long-running sync, a user might want to add another item to the queue. If we're not careful about how we read and write to the async storage, we could accidentally overwrite some user actions, which we definitely want to avoid.

To avoid race conditions, every persistence operation has to run inside a mutex-protected critical section. Here's a simple example of the code needed to make this work.

export class Queue<T> {
  private lock: Promise<void> = Promise.resolve();

  private async withLock<T>(fn: () => Promise<T>): Promise<T> {
    let release!: () => void;

    const previousLock = this.lock;
    // Create a new lock and hold on to it's `resolve` function...
    this.lock = new Promise<void>((resolve) => {
      release = resolve;
    });

    // Wait for the previous lock to be released...
    await previousLock;

    try {
      // Execute the wrapped function...
      return await fn();
    } finally {
      // Release the lock once the wrapped function finishes...
      release();
    }
  }
}

Here's how the queue might use this mechanism: we read and write modified items in a single, atomic operation (at the queue abstraction level) to ensure that no other queue method can overwrite items during this process.

await this.withLock(async () => {
  const items = await this.read();
  // Modify items...
  await this.write(items);
});

It’s sufficient for a single JS execution context, it won’t protect against multiple tabs or workers.

Enqueueing with deduplication and bounded size

Next, we'll talk about deduplication and bounded size together because they happen at the same time during the enqueue operation. First, let's update the config by adding two more fields:

• identityKey returns a unique identifier for each item (needed for deduplication).

• maxDepth defines the maximum depth of the queue.

Here is a simplified version of the enqueue method. Since we need to read all items to decide whether to replace or add an item, the entire operation is atomic, starting with a read and ending with a write.

export interface QueueConfig<T> {
  name: string;
  storageKey: string;
  processor: (item: T) => Promise<void>;
  identityKey: (item: T) => string;
  maxDepth?: number;
  // Other configuration fields...
}

export class Queue<T> {
  async enqueue(item: T): Promise<void> {
    return this.withLock(async () => {
      const items = await this.read();
      const identityKey = this.config.identityKey(item);
      const existingIndex = items.findIndex((i) => i.id === identityKey);

      const queueItem: QueueItem<T> = {
        id: identityKey,
        // Other queue item fields...
      };

      if (existingIndex >= 0) {
        // An item with the same key already exists - replace it...
        items[existingIndex] = queueItem;
      } else {
        // No item with the same key found - push it to the queue...
        items.push(queueItem);

        // If exceeding the max depth, remove oldest items...
        if (items.length > this.config.maxDepth) {
          items.splice(0, items.length - this.config.maxDepth);
        }
      }

      await this.write(items);
    });
  }
}

Whether you want to add deduplication or reorder the items depends on the use case. In our todo list example, if a user changes the status of a single todo item multiple times, we only want to keep the last change, as this reflects the user’s intent. The order of the operations doesn't really matter.

A rule of thumb: deduplication works best for idempotent or “last-write-wins” mutations, for append-only or causal operations, this approach may be wrong.

Manual sync with guardrails

As mentioned in the previous article, syncing is explicit. I decided that the queue should have two public methods—one to start the sync and the other to pause it. This allows the clients of the queue to toggle syncing when the user's network status changes.

if (isOnline) {
  await queue.startSync();
} else {
  queue.pauseSync();
}

Before we sketch out the implementation, here are a few design decisions that matter a lot:

1. Items are processed sequentially. There's no right or wrong choice here, but processing items one at a time might be a bit easier on the server.

2. Only one sync can run at a time. Each queue holds a single list, so it only makes sense for one sync process to happen at a time.

3. Sync can be paused mid-flight. This is something we already discussed above.

Retries are also an important consideration, and we will discuss them in future posts. However, we will design the methods so that adding retry behaviour is straightforward.

export interface SyncResult<T> {
  status: 'completed' | 'paused';
  success: Array<QueueItem<T>>;
  failure: Array<QueueItem<T>>;
}

export class Queue<T> {  
  // Fields for controling the state (could be represented as a single field)...
  private isProcessing = false;
  private isPaused = false;

  pauseSync(): void {
    // Setting a flag that will be read during sync before every item is processed...
    this.isPaused = true;
  }

  async startSync(): Promise<SyncResult<T>> {
    // Only allow for a single sync to take place...
    if (this.isProcessing) {
      return {
        status: 'completed',
        success: [],
        failure: [],
      };
    }

    // Reset the flag if the sync has previously been paused...
    this.isPaused = false;

    const result: SyncResult<T> = {
      status: 'completed',
      success: [],
      failure: [],
    };

    try {
      // Single ongoing processing loop (to accommodate for retries later)...
      while (true) {
        // Read the queue items...
        const items = await this.withLock(async () => {
          return await this.read();
        });

        // If the queue is empty, finish processing...
        if (items.length === 0) {
          break;
        }

        // If the sync has been paused, finish processing...
        if (this.isPaused) {
          result.status = 'paused';
          break;
        }

        this.isProcessing = true;

        // Keep track of items that are to be removed...
        const itemsToRemove = new Set<string>();

        for (const item of items) {
          // If the sync has been paused, finish processing...
          if (this.isPaused) {
            result.status = 'paused';
            break;
          }

          try {
            await this.process(item);
            // The item has been processed...
            // Add it to `success` array and mark to be removed...
            result.success.push(item);
            itemsToRemove.add(item.id);
          } catch (error) {
            // The item has failed...
            // Add it to `failure` array...
            result.failure.push(item);
          }
        }

        // All items have been processed...
        // Read the fresh items from the queue and save changes as one operation...
        await this.withLock(async () => {
          const items = await this.read();
          const newItems = items.filter((item) => !itemsToRemove.has(item.id));
          await this.write(newItems);
        });
      }
    } finally {
      this.isProcessing = false;
    }

    return result;
  }

This simple processing takes care of the happy path — when every item is processed exactly once, without retries (again, we’ll add them in a later post). There are a few areas worth highlighting in this implementation.

• Items are read only during the beginning of the sync. The loop operates on this in-memory snapshot. Newly enqueued items during processing are not picked up immediately. They’ll be handled in the next iteration of the loop. This is mainly for simplicity and determinism: you always know which items you’re attempting to process, and you’re not mixing in reads mid-loop.

• Pausing only affects the next item after the queue is paused. This means the currently running item is always allowed to finish. Pausing stops future work, not in-flight work. Again, this is made for simplicity and predictability — interrupting an active mutation would require request cancellation and make error handling significantly.

• Changes are saved after reading from queue again in a single operation. This avoids partial updates. Either all successfully processed items are removed together, or none are. It also ensures the queue state reflects any changes that may have happened while processing was ongoing.

Summary

That’s it for today! This article walks through the core implementation details of a foreground queue for offline mutations:

• Atomicity and correctness are enforced by wrapping every read–modify–write cycle in a mutex. This prevents race conditions when users enqueue items during an ongoing sync.

• Deduplication and bounded size happen at enqueue time, using a stable identity key and optional maximum depth. This lets the queue reflect user intent rather than raw action history.

• Explicit sync control keeps behaviour predictable. Only one sync runs at a time, items are processed sequentially, and pausing affects future work—not in-flight requests.

• Deterministic processing comes from operating on a snapshot of the queue and committing changes in a single atomic write after processing completes.

This gives us a robust foundation that handles the happy path and leaves room for retries, backoff, and more advanced error handling later. Next, we’ll introduce state awareness and show how to integrate the queue with React, so the UI can respond to sync progress and failures without tight coupling.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further reading and references

• Photo by Aaron Burden on Unsplash

This is the fourth post in my series about offline support in web applications. In the previous articles, I covered general approaches, app shell loading, and data persistence. In this post, I want to focus on a very practical piece of the puzzle: implementing a foreground queue for pending mutations.

In my experience, a well-designed foreground queue is the backbone of reliable offline writes. It keeps your app honest about what happened, what still needs syncing, and what went wrong.

Introducing: queue

Before going any further, it’s worth touching on what I mean by a queue in this context. Formally, a queue is a data structure used to hold items that need to be processed later, in a defined order. You add items to the end, and you process them one by one from the front.

Most queues follow the FIFO rule — first in, first out. The first item you enqueue is the first one you process. In practice, the queue I describe in this article behaves this way implicitly: items are processed sequentially in the order they were added, unless deduplication replaces an older entry with a newer one.

This model turns out to be a very natural fit for offline mutations:

• User actions become explicit units of work

• Each mutation is processed exactly once, in a predictable order

• Failures are isolated to individual items instead of breaking the whole flow

Finally, this is simply an application-level queue, not a message broker or background job system.

Why a foreground queue?

Once you allow users to mutate data offline, you need a place to put those mutations. You can’t just “fire and forget” API calls anymore.

Saving these pending mutations in queue gives you:

• Explicit control over when syncing happens

• Clear visibility into pending and failed operations

• Predictable behaviour when connectivity changes

As mentioned in the first article, choosing between background sync and a foreground queue mainly depends on the user experience you want and the level of complexity you can handle. Compared to background sync, this approach is less complex, simpler to reason about and easier to debug.

I won't go into the exact details of the queue implementation I was working on, but I'll focus on the key principles and the most important parts of the implementation. Let’s dive in!

What I wanted from the queue

Before writing any code, I wrote down a short list of requirements and characteristics I wanted my queue implementation to have. Here’s what I considered:

• Persistence: queued mutations must survive reloads, crashes, and restarts (same principles for data persistence apply as we discussed in the previous article)

• Retryability: failures should be retried automatically, using exponential backoff to avoid hammering the network or backend

• Observability: every important operation should be trackable, so I can log, measure, and reason about what the queue is doing

• State awareness: the application should be able to subscribe to queue state changes and react in real time

• Deduplication: only the latest intent for a given entity should be kept

• Bounded size: the queue must have a maximum depth to prevent unbounded growth

These constraints strongly shaped the design, which you’ll see throughout this and the following posts.

Queue class

At its core, the queue is just a class. There’s no magic here — you create an instance, configure it, and interact with it through a small, explicit API.

Here's a simplified example. We'll add more details as we proceed.

export interface QueueConfig<T> {
  name: string;
  storageKey: string;
  processor: (item: T) => Promise<void>;
  // Other configuration fields...
}

export class Queue<T> {
  private config: QueueConfig<T>;

  constructor(config: QueueConfig<T>) {
    this.config = config;
  }

  // Public and private methods...
}

I’ve found this approach works quite nice because it keeps responsibilities clear. The queue owns persistence, ordering, and retries. The rest of the application just tells it what to do (such as passing the processor function to be called on each item during syncing).

Managing items

There are a handful of public methods the queue needs. The first set of public methods handles the lifecycle of items in the queue, reading and writing to the IndexedDB using the storageKey property.

• enqueue adds a new item to the queue and persists it immediately

• dequeue removes a specific item by identity, permanently discarding it

• clear removes all items from the queue (useful for resets and tests)

Controlling syncing

The second group controls when and how items are processed:

• startSync begins processing queued items sequentially

• pauseSync stops processing after the current item finishes

Syncing is always a foreground action. Only one sync operation can run at a time, and additional calls are ignored while a sync is in progress. This keeps behaviour predictable and avoids subtle race conditions.

The trade-off is that the client needs to decide when syncing should occur. The queue implementation doesn't rely on the network state (whether the user is online or offline); this is managed externally by the queue users. In practice, startSync is called when the user goes online, and pauseSync is called when the user goes offline.

Queue item shape

To wrap up this section, let's examine the structure of a queue item. This is how entries are stored in IndexedDB. Each entry in the queue is a small, self-contained record that represents a single user action. I keep this structure intentionally simple, but every field is there for a specific reason.

export interface QueueItem<T> {
  id: string;
  payload: T;
  enqueuedAt: number;
  attemptCount: number;
  lastAttemptAt: number | null;
}

Here’s how I think about each field:

• id - a unique identifier for the item. This is the foundation for deduplication we’ll touch on later — if a new item is enqueued with the same id, it replaces the old one. In practice, this usually maps to the domain entity being mutated (like changing a status on a todo twice while offline).

• payload - the actual data needed to perform the mutation. The type here is configured by the client, which makes the whole implementation generic. The queue doesn’t care what’s inside, only that it can hand it to the processor.

• enqueuedAt - a timestamp of when the item was added to the queue, useful for monitoring.

• attemptCount - tracks how many times processing has been attempted for the item. This drives retry behaviour and determines when an item should be considered permanently failed.

• lastAttemptAt - records when the item was last processed. Combined with attemptCount, this allows exponential backoff and makes retry timing explicit and observable.

This structure strikes a balance for me: it’s rich enough to support retries, backoff, and monitoring, while keeping it fairly compact and easy to manage (item statuses can be derived from existing fields).

Summary

That’s it for this article! We introduced the idea of a foreground queue as a practical foundation for handling offline mutations in web apps.

• We covered the core responsibilities of such a queue: persistence, retries, observability, state awareness, deduplication, and bounded growth.

• We outlined a simple class-based design, the public API for managing items and controlling syncing,

• We described the shape of a queue item — to enable retries, backoff, and monitoring.

To sum it up in one sentence: in a foreground queue, treat every offline mutation as durable work that must be explicitly tracked.

In the next articles, I’ll dive into the most important implementation details and show how to actually satisfy the characteristics outlined at the beginning — from persistence mechanics and retry strategies to deduplication and state subscriptions in practice.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further reading and references

• Photo by freestocks on Unsplash

• Queue (abstract data type) on Wikipedia

This is the third post in a short series on building offline-capable applications. Today we discuss a fundamental aspect of offline-ready software — data persistence.

Regardless of whether you use a foreground queue, background sync, or a hybrid approach, you need a place to store data locally. In my experience, getting data persistence right from the start saves a lot of friction later when you start adding the actual features.

Why persistence matters

From the user's perspective, offline support begins with being able to see something meaningful. Ideally, it should be exactly what they saw when they were still online, like a list of to-dos, a previously opened document, a screen they were just interacting with. If the app can't display any data when the network is unavailable, there's not much the user can do.

This post is entirely about one very specific thing: caching data fetched from the server so it’s still available offline. Without persisted server data, there is no foundation for offline support.

The key decision, and the one I find most important early on, is establishing what data is critical to cache. Not everything needs to be persisted, but some queries are essential: global context, core dynamic configuration, and the data that’s in the offline-capable features.

This decision becomes the basis for all offline functionality:

• which screens should be rendered without a network,

• which actions are going to be possible offline,

• and how much complexity you’ll need later for syncing and recovery.

Once this boundary is clearly defined, the offline story becomes much easier.

Storage options in the browser

Browsers give us a few options for storing data for offline sessions, each with very different trade-offs.

The simplest ones are localStorage and sessionStorage. They’re synchronous, easy to use, and available everywhere. Unfortunately, that simplicity comes with hard limits: small storage quotas, blocking APIs, and no support for structured or large data. For anything beyond feature flags or tiny bits of state, this is really not suitable.

Cookies are even less attractive for this use case. They’re size-constrained, sent with every request, and optimised for server communication rather than client-side persistence.

That leaves IndexedDB. It’s asynchronous, built for larger datasets, and designed to work well with structured data. The API itself is not particularly friendly, which is why I recommend using a library for, as the interface.

In my experience, IndexedDB is the most practical choice for offline persistence because:

• it doesn’t block the main thread,

• it scales well as your cache grows,

• and it works reliably across modern browsers.

There are edge cases where other storage options make sense, but for persisted data caches and offline-first features, IndexedDB is usually the right default.

React Query persistence

It's hard to imagine a single-page React application of a decent size without using React Query to manage client-side server state. It's definitely my go-to choice for this purpose. Keeping data persistence close to the library simplifies the entire mental model.

The approach I’ll describe here is:

• based on @tanstack/react-query-persist-client,

• backed by IndexedDB,

• and intentionally selective about what gets persisted.

This approach is general enough to work across different apps, as long as they use React with React Query as the primary data-caching solution.

The example: todos with offline status updates

I’ll use a small todos app as a concrete example:

• the app displays a list of todos,

• each todo has a completed status,

• toggling the status should work offline,

• and the list should still render after a reload.

That gives us a clear persistence requirement: the todos query must survive reloads and offline sessions.

Step 1 — Choosing what to persist (selective persistence)

Persisting everything that goes through React Query is rarely what you want. It unnecessarily increases storage usage. Instead, I recommend selective persistence:

• global queries required for the app to function,

• and queries directly related to offline-capable features.

In a todos app, that usually means the todos list itself.

A common pattern is to filter queries by key prefixes:

const persistedQueryPrefixes = [
  'me', // Global - user context
  'todos', // Feature-specific - list of todos
];

export const shouldPersistQuery = (query: Query) => {
  return persistedQueryPrefixes.includes(query.queryKey[0]);
};

In practice, I prefer using query key factories so this stays type-safe and refactor-friendly.

The trade-off here is you need to think about query ownership. The upside is a much smaller and more predictable cache.

Step 2 — Building a persister with IndexedDB

You can use idb-keyval for read and write operations and implement React Query’s Persister interface.

import { set, get, del } from 'idb-keyval'

const STORAGE_KEY = 'rq-cache';

export const persister: Persister = {
  persistClient: async (client) => {
    await set(STORAGE_KEY, client);
  },
  restoreClient: async () => {
    return get(STORAGE_KEY);
  },
  removeClient: async () => {
    await del(STORAGE_KEY);
  },
};

Step 3 — Wiring persistence into providers

React Query handles most of the lifecycle for you via PersistQueryClientProvider.

This is where configuration starts to matter:

• maxAge — how long persisted queries are kept (for example, 3 days),

• buster — value to increment when you make breaking cache changes.

<PersistQueryClientProvider
  client={queryClient}
  persistOptions={{
    persister,
    maxAge: 1000 * 60 * 60 * 24 * 3,
    buster: 'v1',
    dehydrateOptions: {
      shouldDehydrateQuery: shouldPersistQuery,
    },
  }}
>
  {children}
</PersistQueryClientProvider>

One important piece of configuration in your regular query client is staleTime — this is when data becomes stale but still usable. Queries marked as stale will be fetched from the API when the app is online. Keep in mind, they won't be fetched again after a refresh because the client now lives in persisted storage.

Finding the right configuration is a balancing act. In my experience, longer living cache is fine for offline-friendly data, as long as you still refetch aggressively when the app is online.

Once persistence in place, the next step is to record status changes while offline.

The easiest way would be to optimistically update the cached todos query, and React Query will automatically persist that change. The system doesn't care whether the change comes from the server or a mutation.

This is not enough. The tricky part is replaying the action or actually saving the state on the server. What happens next—like reconciliation, retries, and handling conflicts—depends on the offline model you choose, which I’ll discuss later in the series.

A word on migrations

One important realisation is that with data stored on the client side, there's one additional place where data exists independently from the rest of your system. There might be a situation where you change the structure of the API being used. You update the application code to match, so everything works together. So what happens in the application?

When a new version of the application launches, the client loads the stored data, and it breaks because the code now expects different data, while the client still has the old format. You have two options.

• Run a migration. This means running a script to transform the already stored client-side data into the new format expected by the updated application code. The benefit is a seamless user experience with preserved data and, most importantly, no data loss. The trade-off is added complexity, careful versioning, and the risk of bugs if migrations fail or are only partially applied.

• Invalidate the cache. This means discarding all previously stored client-side data and forcing the application to fetch fresh data from the server. This approach is way simpler to implement, but users may lose some offline data.

Summary

Data persistence is the foundation of offline support. With React Query, you can get surprisingly far by:

• persisting only what’s needed,

• using IndexedDB for storage behind a small abstraction,

• and letting React Query manage cleanup and hydration.

Once this is in place, higher-level offline features become much easier to reason about.

If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further reading and references

• Photo by Erol Ahmed on Unsplash

• Effective React Query Keys from TkDodo

This post is the second article in a series about offline support in web apps. Here, we're defining what's needed to make the application available when the network is down, in its most basic form. This is not about full offline functionality just yet. It’s a clear baseline we can build on later.

The Offline Availability

For this article, “offline” availability is intentionally scoped to a very specific and narrow case:

1. The user opens the app while online.

2. The device loses network connectivity.

3. The user reloads the page.

Without any support, the browser would show its default offline error screen. Instead, we want the application to load successfully. That’s it. If your app can handle this scenario, you’ve cleared the first real offline hurdle.

We’re not attempting to solve data persistence, handling mutations, synchronisation, conflict resolution or retries just yet. We’ll get to them in later posts.

The Default Offline Failure

Most websites or web applications fail offline in exactly the same way.

1. The user opens the app while online.

2. The app loads successfully.

3. The network disappears.

4. The user refreshes the page.

5. The browser tries to re-fetch index.html.

6. The request fails.

7. The browser shows a generic offline error page.

Notice how nothing “breaks” in your code — the browser simply refuses to load the app at all.

In practice, this is often the first thing users notice — a refresh on a train, plane, or unstable connection that instantly breaks the app. Importantly, this happens even if the app was previously loaded, JavaScript bundles are cached by the HTTP cache and the app is a SPA with client-side routing.

The key insight here is this: without explicit offline support, the browser treats your app as unavailable, regardless of how much code it already has locally.

App Shell Availability

The smallest meaningful offline capability is simple — the application shell must load without a network connection. If you achieve that, your app moves from “completely broken offline” to “offline-aware”.

For the purposes of this post, the app shell is the minimal set of HTML, CSS, and JavaScript required for the core user interface of a web application such as navigation, layout, and basic styling. It does not include anything that’s required to handle dynamic content.

If these assets load, the user will at least be able to see something — even if it’s just a clear “You’re offline” state. Showing any intentional UI is the first step towards offline-capable web app.

Introducing: PWA

Browsers do not guarantee that index.html will be available offline via normal HTTP caching. If you want reliable offline loading of the app shell, you need explicit control over how the browser serves your application’s core files when the network is unavailable.

This is where Progressive Web Applications (PWAs) come into play. PWAs are web apps that opt into a set of browser features designed to improve reliability, and the most important one for offline access is the service worker. A service worker allows your app to intercept network requests and serve pre-cached assets instead, making it possible to apply a cache-first strategy for the app shell and reliably load the application even when the network is gone.

Here’s the minimal required PWA feature set to make this happen.

• Service worker registration.

• Pre-caching of app shell assets.

• Cache-first fetch handling for those assets.

There are other PWA features, such as the Web App Manifest (which defines icons and allows the application to be installed) or push notifications. While these features enhance the offline experience, you can still have offline app-shell loading without install prompts or home screen icons.

Using vite-plugin-pwa

It’s safe to say Vite is currently the go-to way of building modern single-page web applications, the example here is using that build tool.

For Vite-based apps, vite-plugin-pwa provides a low-friction way to add just enough PWA capabilities without having to hand-write or deeply understand a service worker. It integrates with the Vite build pipeline, takes care of asset hashing at build time, and gives you pre-caching out of the box.

Most importantly, it lets you focus on deciding what should be cached, instead of worrying about how the service worker is implemented. A conceptual configuration might look like this:

import { VitePWA } from 'vite-plugin-pwa'

export default {
  plugins: [
    VitePWA({
      registerType: 'autoUpdate',
      strategies: 'generateSW',
      workbox: {
        globPatterns: ['**/*.{js,css,html,svg,png}'],
      },
    }),
  ],
}

With this in place, the app shell is pre-cached at build time and served from cache when the network is unavailable, making offline page reloads possible without any deeper offline functionality. The same principles apply if you use other build tools, but Vite makes this particularly straightforward.

Lazy-Loaded Routes

It's important to point out that modern web applications are often split into multiple JavaScript chunks that are only loaded when they are actually needed. When code-splitting is done by route (very common in SPAs) the code responsible for rendering a specific page might only be fetched when the user navigates to that route for the first time. With offline support, this becomes a problem because that code may simply never have been downloaded before the user goes offline.

A typical example looks like this:

const SettingsPage = lazy(() => import('./pages/settings'))

This works perfectly fine online. When the user tries to access the settings page for the first time, a new chunk of code is requested, and the user can see the page. However, if the user goes offline and then tries to navigate to /settings, the browser won't have the JavaScript chunk for that route. If it isn't already cached, the navigation will fail, even though the app shell itself loaded successfully.

The practical implication is straightforward: any route you expect users to access while offline must not depend on a chunk that was never cached. If a route must work offline, its code must be available before the network disappears. You can solve this in a couple of ways.

1. Eagerly import critical routes. This increases your initial bundle size but guarantees the code is available offline.

2. Include route chunks in your pre-cache configuration. This preserves the benefits of code-splitting but requires a bit more awareness of what your build actually produces.

This is not necessarily about making every route work offline. It’s about identifying the offline-critical path — usually landing pages, dashboards, or explicit offline states — and making sure those parts of the application are ready before the network is gone.

Summary

To wrap it up, for a web app to be accessible offline in the most basic sense:

• A service worker must exist

• The app shell must be pre-cached and served cache-first

• Critical routes must not rely on uncached lazy chunks

With this baseline in place, the next step is deciding how data behaves offline — which is where things start to get more interesting. If you enjoyed the article or have a question, feel free to reach out on Bluesky! 👋

Further Reading and References

• Photo by Galina N on Unsplash

• MDN — Service Worker API

• Vite PWA Plugin documentation

This post kicks off a short series on building offline-capable applications. I want to start with two core architectural patterns that most often form the foundation of almost every offline strategy: Foreground Queue and Background Sync.

I’ll explore both approaches from the client perspective—your SPA, Electron shell, or mobile web wrapper. PWAs can come later as a progressive enhancement.

What Problem Are We Solving?

When the client loses connectivity, the user still wants to do things—create tasks, edit notes, send messages, update settings. At some point, those changes must reach the server. The question is how and when the sync happens, and what the user sees while it’s happening.

Most designs naturally fall into one of two models.

Foreground Queue — Explicit, Traceable, User-Visible

The Foreground Queue model focuses on showing current state, giving clarity and predictability to the user. The idea is simple: whenever the user performs an action that needs to reach the server, the app writes that operation into a durable queue (most often IndexedDB). Those operations sit there until the app decides it’s time to replay them. Foreground Queue is about recording intent and replaying it later.

This is an application-level queue, not a message broker.

And “decides” really means while the app is running. Nothing magical happens in the background. If the user closes the tab or the desktop client isn’t active, the queue stops moving. Sync only resumes when the user comes back.

In practice, this makes the logic easy to reason about. You detect that you’re online, you pull pending items out of the queue, and you try sending them one by one. If something fails, you mark it as failed, apply your backoff strategy, and try again later. FIFO ordering works well, but you can get fancy if your domain requires it.

Here’s a simplified sketch of the sync function:

async function sync() {
  const items = await queue.loadItems();

  for (const item of items) {
    try {
      await item.process();
      await queue.markCompleted(item);
    } catch {
      await queue.markFailed(item);
      break;
    }
  }
}

The UX that this approach brings is what I think of as visibility-first. Users know what’s pending because you show it to them—an Outbox, a little “pending” pill next to items, a count of unsent changes. You don’t pretend the server is up to date—the user understands others won’t yet see the change, and they get less surprised if a conflict appears after submission.

If you want straightforward reasoning and explicit status for a handful of clearly defined actions, and can accept relying on retries and making sure requests are idempotent, Foreground Queue is hard to beat.

Background Sync — Optimistic, Continuous, Seamless

Background Sync takes a different approach. Instead of queuing operations and waiting for a coordinated replay, the app immediately updates local state and behaves as though the server has already accepted the change. Background Sync is about maintaining a local copy of server state and continuously reconciling it.

Despite the name, this isn’t the browser’s Background Sync API. It’s an architectural pattern where the app continuously reconciles local and server state while it’s running.

This model can be incredibly pleasant to use. The whole app feels fast because the UI never waits on the network. Under the hood, though, you’re doing more work: you label objects as “dirty,” schedule periodic sync attempts, push changes whenever you detect connectivity, and then reconcile any differences between the client and server versions. A lot of things can go wrong here.

Because changes apply locally right away, you also have to be more thoughtful about conflict resolution. If the server disagrees with your optimistic edit, the user may see a correction or merge state later. Handling that gracefully makes or breaks the experience.

The core loop can look something like this:

async function backgroundSync() {
  const dirty = await store.getDirtyEntities();
  for (const entity of dirty) {
    try {
      const updated = await push(entity);
      await store.applyServerState(updated);
    } catch {
      /* retry later */
    }
  }
}

In a browser-only environment, however, it’s worth remembering that this isn’t real background sync. Nothing runs after the tab closes in the browser. Electron and native shells can give you genuine background execution, which makes this model far more practical.

The trade-off is complexity in maintaining a client-side replica of the server state. That means concurrency issues, periodic synchronisation, retries, and merges. And because users assume everything succeeded instantly, any visible rollback is more noticeable and must be communicated carefully.

Practical Recommendations

Here are a few practical guidelines I’ve found helpful when choosing and implementing an offline strategy.

1. Use IndexedDB for persistent storage. With rich storage quota, ability to handle complex data (like blobs/files), asynchronous API and browser support, it’s probably the safest bet for client data storage in any approach.

2. Design for at-least-once delivery. Use stable operation IDs and idempotent endpoints. Assume every request can be sent twice, and design endpoints accordingly.

3. Pick UX deliberately. Users need clarity and control? Foreground Queue. Users expect seamless, fast, “everything just saves”? Background Sync. Decide upfront whether users should ever see ‘pending’ as a first-class state.

4. Don’t treat the architecture as a binary choice. Many real-world apps mix both models—for example, using a Foreground Queue for destructive or high-risk actions, and Background Sync for low-risk, high-frequency edits.

5. Be honest about your runtime. If your app can’t run code in the background, don’t promise background behavior. If the tab closing stops all work, reflect that in copy and product expectations.

Takeaway

To sum it up in one rule: Foreground Queue prioritises transparency; Background Sync prioritises smoothness. Both are solid approaches, and both can coexist in the same architecture. The right choice depends on your environment, your users, and how much complexity you’re willing to take on. The real decision isn’t only technical—it’s whether you want users to see uncertainty or hide it.

If you have thoughts or want to share your own offline challenges, feel free to reach out on Bluesky! 👋

Further reading and references

• Photo by Ray Hennessy on Unsplash

Rules

One of the most important factors in making agents even directionally correct, especially early on, is establishing clear rules. At the start of a project, agents are almost useless without them.

As with many other things, I’ve found it best to begin with a small, simple set of rules, then expand and organize them as the project grows—first in a single file, then across multiple files, and eventually into directories when needed. A really useful mental model around agent rules is to ask, each time you correct an agent or have a discussion within the team, should this become a new rule?

I also now keep most of the documentation about the code in README files within the codebase, rather than in any external services, which makes it easier for both humans and agents to stay aligned.

Finally, it’s worth revisiting and refining the rules periodically. One effective way to do this is by asking a model to evaluate the existing rules, suggest improvements tailored to your tech stack, and identify any gaps:

Evaluate the rules below and suggest an improved version that works best with my tech stack.
If any important rules are missing, suggest adding them.

Prompting

With the basic rules in place, the next focus should be on prompting. It's been said time and time again, but it's worth mentioning—the quality of the LLM's output directly depends on how you prompt it.

Over time—through trial, error, and digging around online—I’ve collected a handful of instructions that tend to cut down on unnecessary back-and-forth. These tips aren’t quite as critical when working with in-editor agents (since the feedback loop there is much tighter), but for background agents they really help keep things on track.

Emphasize the rules:

• Make sure to read the rules in the repository and follow them when implementing the feature.

Improve reasoning:

• Think hard before starting implementation.

• Plan your steps before writing code.

• Prefer using existing components over creating custom ones, even if designs differ slightly.

Final checks:

• Double-check requirements and handle any potential edge cases.

• Make sure the added code follows standards defined in the codebase.

• Ensure existing behavior isn’t broken.

• Run formatting and linting before submitting code.

Workflow

I’ve heard (and read) that some people spin up multiple agents at once and only orchestrate them. I can’t see myself doing that yet, for a few reasons.

Running multiple agents in parallel still requires a fair amount of mental overhead, since each one needs preparation and follow-up adjustments. On top of that, at the beginning of any project, you probably don’t have enough distinct areas of work to parallelize effectively. And while agent output is usually a good starting point, it always requires significant adjustments—whether that’s making the design closer to spec, improving the user experience, or restructuring the code in a way that fits better.

Some of these issues can be mitigated by writing better rules, but many of them only come up during code review or while actually testing the solution. Still, I think agents can be very effective—even when used one at a time.

Having said all that, here’s my current workflow supported by background agents.

1. Prep work for the agent. I usually work with very short issue descriptions, so I generate richer descriptions first to provide more context to the agent.

   Help me prepare a well-defined issue description to implement the following:
   <feature_description>

2. Create a ready-to-use prompt. With the richer description, I generate a background-agent prompt (including my prompting instructions):

   Create a prompt optimized for Cursor Background Agents based on the feature description below.
   Additionally: <prompting_instructions>
   Feature description: <richer_feature_description>

3. Run the agent and work on something else in parallel (e.g., code reviews, or writing a post like this).

4. Review results and adjust in sequence:

   • Background agents → biggest follow-up changes (e.g., missing tests, mocks).

   • In-editor agents → medium-size adjustments.

   • Inline edits → small changes like styling or readability.

Takeaway

Right now, background agents give me about the first 50% of a feature. In theory, in-editor agents could do the same, but I find that the stronger models and the more open environment of background agents produce a better starting point, faster. I hope to slowly increase that initial percentage.

I’m curious: does this align with your experience using similar tools? How does your workflow differ?

If you enjoyed the article or have a question, feel free to reach out to me on Bluesky or leave a comment here! 👋

Further reading and references

• Photo by Joshua Whitney on Unsplash

Recently, at Salesloft, I had the opportunity to lead such an initiative: integrating Knip, a dependency management and automated unused code removal tool, in our main front-end application monorepo. This guide comes directly from that project. I will walk you through a step-by-step process for introducing large-scale tooling changes in software engineering projects.

Before we begin, here's an important note: The approach in this document is quite general and should work with different tools and situations. However, when adding new tools, it's crucial to think about the specific needs of your project and team. While it's usually better to introduce tools gradually, some can fit smoothly into existing workflows all at once.

Step 1 — Evaluate the tool

Before adding any new tool, it's important to check what it can do, what it can't do, and how it might affect your project.

• Assess the tool's main function. Understand what the tool is meant to do and how it fits with your team's goals. If possible, give it a try.

• Research the tool's ecosystem. Look into the tool's community, documentation, and existing integrations to understand its maturity and the level of maintenance and support.

• Evaluate the tool's compatibility. Check if the tool works well with your project's current setup, including the infrastructure, programming languages, and libraries.

• Estimate the costs. Think about the cost of migration, possible pitfalls, and, eventually, sunsetting of the tool.

• Look into the license. Check the tool’s license and to what extent it can be used.

• Compare alternatives. See if there are other tools that can fully or partially solve the same problem. If there are, compare them and decide which one is the best fit for your situation.

• Consider integration options. Describe the different ways you could integrate the tool.

Step 2 — Start a discussion

Once you evaluate the tool yourself, it's time to see if the team is also interested and gather their feedback — this is the next step in evaluating the tool. You have a few options here—the choice depends on how simple or complex the tool is. As the complexity increases, you might choose a more formal approach.

Here are two example approaches you can take:

• Informal: Create an open Slack discussion channel to share ideas and get feedback.

• Formal: Create a Request For Change (RFC) document that explains the proposed tool change, its benefits, and possible risks.

No matter which option you choose, you should focus on a few key areas.

• Collect feedback. Encourage team members to review, comment on, and give their input. Tag the right people and set a deadline for collecting feedback (e.g., two weeks), to make sure you get input on time.

• Get approvals. Get the necessary approvals for the tool (architecture, security, etc.).

• Describe the integration path. Decide how you will integrate the tool and explain the method in detail.

• Communicate with the teams involved. Communicate and discuss what is needed from other delivery teams.

Step 3 — Integrate the tool into the repository

Once the tool change is approved, it's time to add it to your repositories.

• Install the tool. Install the tool, which may involve creating a new service or module in your repository to accommodate it.

• Add minimal configuration. Add the appropriate configuration and necessary scripts.

• Focus on local development experience. Ensure the tool is available locally for other engineers first, and save any automation for later. This allows engineers to start using the tool if they choose and provide feedback.

• Communicate the change. Communicate the change introduced to the team, along with the next steps, to keep everyone in the loop.

Step 4 — Run as a part of automation

Integrating the new tool with your Continuous Integration (CI) pipeline is the next crucial step to ensure the tool is effective.

• Integrate into a workflow. Add the tool to the appropriate part of the workflow. Make sure it runs on every pull request, unless that's not practical.

• Add a minimal low-severity ruleset. Start with a basic set of useful rules and add more later. Initially, it might be appropriate to make the workflow step non-blocking by using warnings instead of errors. This approach allows more people to notice the tool without interrupting ongoing development. For pull requests, consider running the tool only on changed files at first, and then expand later.

• Highlight results. For pull requests, make sure the results are highlighted, especially when they are non-blocking. You can add them as comments on pull requests because warnings in a successful pipeline will almost certainly be overlooked.

• Communicate the change. As always, communicate the change to the team.

Step 5 — Add documentation

Make sure to include all the important details in the documentation. You can do this during the earlier steps, but it's also fine to create it now, once the basic setup is complete. Any needed context can be understood from the initial discussion.

• Update the changelog. Add a changelog entry if your repository maintains one.

• Create documentation. Make sure to cover most of the following aspects.

  • Short description of the tool and its purpose.

  • The reason for introducing the tool.

  • Common CLI commands (if the tool supports them).

  • Guide to using the tool.

  • Description of the CI workflow integration.

  • Links to official documentation or other related resources.

• Communicate the change. At this point, you most likely know what to do.

Step 6 — Spread the word

After introducing the tool change with clear documentation, share your experience and get feedback from the wider team. It's usually a good idea to have a short meeting to discuss the tool with anyone whose work will be directly affected by it.

• Describe the “why”. Explain the tool's function and the reason for its use.

• Show it in action. Prepare a demo to show engineers how to use the tool. Use the documentation and other relevant resources as needed.

• Highlight automation. Explain how the workflow integration works and how it affects engineers.

• Keep a record for future reference. Record the meeting for future reference. Share the slides and the recorded meeting in the appropriate channels.

Step 7 — Involve other teams in actively adopting the tool

If introducing the tool requires action from other teams (to handle the results or integrate the solution into their areas), be sure to involve them. Depending on what you can realistically handle yourself and how you define code ownership, this step will need varying amounts of convincing and persuasion.

Here are two example strategies you might follow.

• Start and hand off. Consider starting the work for other teams and then passing it on to them.

• Do it yourself. Alternatively, if the change is simple, you can do all the work for other teams and then pass it on to them just for review and testing.

Step 8 — Refine the configuration and expand the rules

As the repository evolves and engineers start using the tool, we should continue to refine the configuration and consider expanding the rules.

• Expand the ruleset. Consider making the rules stricter or adding new rules.

• Run on all files. Think about changing the workflow to apply to all files, not just the ones that have been changed.

• Block CI. Consider blocking the workflow step by changing warnings to errors (only do this if it won't create too much friction in pull requests).

Note: This is the final, ongoing state.

Conclusion

That's it! Introducing large-scale tooling changes in software projects can be overwhelming. It involves not only doing the work but also getting everyone on the same page. No matter what tool you introduce, there are a few key areas and common themes to focus on.

• Evaluate and research. Before integrating any tool, carefully check its features, limits, and how it fits with your current systems. Doing this early work helps avoid problems later and makes sure the tool meets your team's goals.

• Take small steps. Make changes gradually, starting with local access and non-blocking automation. This helps engineers slowly get used to the changes and give feedback, reducing interruptions to ongoing development.

• Over-communicate. Consistent and clear communication is very important during the whole process. Keep everyone informed about changes, collect feedback, and explain why the new tool is being used.

• Get everyone involved. Encourage teamwork by including the team in talks and decisions from the start. Their feedback and support are crucial for successful adoption and lasting impact.

If you enjoyed the article or have a question, feel free to reach out to me on Bluesky or leave a comment here! 👋

Further reading and references

• Photo by AJ Robbie on Unsplash

I find that engineers often rush to create abstractions and reuse code, trying to avoid duplication at almost any cost. There's a major problem with this approach. Just because code looks similar or even identical doesn't mean it should be shared. It might represent fundamentally different information and, as a result, evolve in different directions.

This article is another attempt to explain this concept—from the perspective of types.

When types should be shared

You might have a situation where you have several different but related components. Maybe they operate at the same level or are used together. They share the same props.

Let’s imagine we have a feed showing chat messages. Each message has its own error handling and a preview for extra media content. We use a small set of components to build the feed. We need to pass the id of the message along with it’s content and the threadId to which the message belongs. All these components also use the current browser location inside their implementation.

Altogether, they all require the same props.

// Example #1 - Chat Messages

const ChatMessage = ({ id, threadId, location, data }) => {}
const ErrorFallback = ({ id, threadId, location, data }) => {}
const MessagePreview = ({ id, threadId, location, data }) => {}

Here’s the main question I’ll be exploring in this article.

When we have multiple components with the same props — should we create a common type definition for props or one for each component?

Technically, we don't need separate interfaces if all components have the same props. However, I recommend having separate interfaces for different components unless the intention is for them to share the same interface.

Here's what I mean by this.

Let’s start with a single prop

Let's consider a different and much simpler example. Imagine we have three components, all in one file.

// Example #2 - UI Components

const Button = ({ children }: ButtonProps) => {}
const Alert = ({ children }: AlertProps) => {}
const Dialog = ({ children }: DialogProps) => {}

How should we define the interfaces for these components? They all have the same props—should we create a single Props interface? They only accept children, so it seems like a good opportunity to reuse code. DRY, right?

You might feel that this approach is not quite right. Technically, it wouldn't be incorrect, since the code to write an interface for each component is exactly the same. However, it would be wrong semantically—a button is not an alert, and an alert is not a dialog. The interfaces are not truly the same, even if they appear to be identical.

Let’s add the second prop

Let's expand on our example. Ask yourself, how are these components most likely to change over time? As time goes on, we might want to add more props. I asked AI, and it suggested these changes as the next most likely to occur:

// Example #2 - UI Components

const Button = ({ children, onClick }: ButtonProps) => {}
const Alert = ({ children, status }: AlertProps) => {}
const Dialog = ({ children, isOpen }: DialogProps) => {}

Each component received a new prop, and each prop is unique to the component. As expected, they all evolved differently. If we had used a single Props interface, we would have needed to return to separate interfaces because, fundamentally, they were never a single interface. Each interface carried different information.

To sum it up in one rule: repeat the code, but not the information.

Returning to our initial chat message example—since these three components have different purposes, serve different functions, and carry different information, it's better to declare separate prop interfaces for each component. If they accept the same props, those individual props should share a type.

// Example #1 - Chat Messages

interface ChatMessageProps {
  id: string;
  threadId: string;
  location: string;
  data: Message;
}

const ChatMessage = ({ id, threadId, location, data }: ChatMessageProps) => {}

// We're creating an interface per component...
interface ErrorFallbackProps {
  id: string;
  threadId: string;
  location: string;
  // ...and sharing the type for individual props.
  data: Message;
}

const ErrorFallback = ({ id, threadId, location, data }: ErrorFallbackProps) => {}

interface MessagePreviewProps {
  // Same content as in ChatMessageProps and ErrorFallbackProps
}

const MessagePreview = ({ id, threadId, location, data }: MessagePreviewProps) => {}

Horizontal vs. vertical slicing

There's an important point to consider. Here, I'm looking at the repeated information from the perspective of the domain. The vertical separation of concerns. You might argue that if you view this information from a technical level (horizontal), such a reusable type could make sense. We can create a generic type to capture this idea.

type PropsWithChildren<Props extends object> = {
  children: React.ReactNode;
} & Props;

React even had this at the component type level—React.FC. This type still exists, but it no longer automatically includes children in the props.

It might be useful to have such a type just for utility, especially in lower-level code where there's no business domain, like in your framework. However, when you start incorporating business, design or user experience decisions, I think it's better in the long run to avoid splitting the information horizontally. This approach allows for a clear separation without too many layers of abstraction.

The implications of sharing interfaces

Let's look at a different example where creating a shared interface is sensible.

// Example #3 - Error Fallback Components

interface ErrorProps {
  title: string;
  message: string;
  error: Error;
}

const DefaultError = ({ title, message, error }: ErrorProps) => {}
const NetworkError = ({ title, message, error }: ErrorProps) => {}
const TypeError = ({ title, message, error }: ErrorProps) => {}

We also have components that accept the same props, but this time they are using a common interface. This approach communicates an important message: these components share the same requirements and are likely to evolve together in the future. Of course, this might not always happen, but at least there's a clear intention behind it.

Let’s consider the changes we might introduce to these components. If we want to control an illustration displayed for an error, we probably want to apply the change to all components. Similarly, if we want to add retry functionality, we likely want to apply the change to all components.

You see my point—sharing an interface actually means that these components have a common interface. They are the same now and likely will need to be the same in the future.

Conclusion

“Don’t repeat yourself” is a more nuanced concept than we might realize. It’s not just about repeated code; it’s about repeated information. The first is easy to notice, but the second is incredibly difficult to spot. My approach is to let patterns emerge, and when it becomes clear that something should be abstracted, then abstract it. Doing it the other way around can be quite painful.

Overall, here's the mental model I find useful when thinking about components that accept similar props.

• Components that are related and used interchangeably should share the same interface.

• Components that are unique and specialized should not share the same interface because they serve different purposes.

If you enjoyed the article or have a question, feel free to reach out to me on Bluesky or leave a comment here! 👋

Further reading and references:

• Recently, I wrote an article about component composition that also discusses this topic: Choosing the Right Path: Composable vs. Configurable Components in React.

• Photo by Willian Justen de Vasconcellos on Unsplash.

My old website was made in 2019 and hasn't been updated much since, except for career updates. I'm actually proud of that—I don't want to be someone who rebuilds their personal site every year.

But now, the site is over five years old in terms of both technology and content. It has become outdated—and it was obvious. It was built with Gatsby that relied on an old version of Node. I could still deploy it on Netlify, but getting it to work locally was a hassle. It also had a CMS, which was fun to add back then, but I hardly used it. Simply put, it was a mess.

I finally decided to redesign, rebuild from scratch, and make it much simpler. Here's what I did.

Go and see it for yourself: https://tomaszgil.me/.

Collecting inspiration

I've spent a lot of time searching for great examples of personal websites from both developers and designers, and also looking at product designs I really liked.

Using design inspiration galleries was really helpful at first. Here are the ones that were most useful to me.

• https://a-fresh.website/

• https://minimal.gallery/

• https://godly.website/

I found plenty of stunning sites. I’ve picked a handful that were the most interesting to me, each with something I wanted to include in my design.

• Mark Horn’s Portfolio. This site focuses on simplicity and balance, with a well-organized content structure. Most of this is achieved through typography. I really like the combination of sans-serif and serif fonts.

  

• Pedro Duarte’s Personal Website. It's simple, personal, and focused on storytelling. I really like how the story is divided on the homepage and the overall layout of the site's content.

  

• Max Yinger’s Website. This site combines ultimate simplicity—the homepage serves as the entire portfolio—with interactive design, featuring neat extras like a time clock.

  

• Alistair Shepherd’s Website. This website has one of the most creative theme switchers I've ever seen. Combined with a fantastic hero illustration that moves as you scroll, it looks truly impressive.

  

• Jacky Zhao’s Website. Sticking with the theme of theme switchers, Jacky's digital garden offers another great example—a pure CSS implementation that mimics sunlight streaming through a window, which looks absolutely great. The effect is open source, and you can find it here.

  

Alongside the individual portfolios, there were also products or services where the design resonated with me—I wanted my site to have similar characteristics or aesthetics.

• Raycast. My favorite productivity app for macOS. Executed perfectly, with a strong focus on full keyboard navigation. I also really like the homepage design, especially the combination of sans-serif and monospace fonts.

  

• Stripe. I'm not talking about the product or the main homepage here, but a part of the developer-facing documentation. I don't quite remember how I found it, but once I did, I fell in love right away. It's both modern and technical—thanks mainly to the use of a grayscale and sans-serif-monospace font combination (you might notice a theme here). I also like how the website can be fully navigated using a keyboard, with clear indicators showing how to access other pages.

  

The design

I started by defining the main high-level characteristics I wanted my design to follow.

1. Minimal and elegant. I wanted the website to be as clean as possible, so users can focus on the content. In practice, this meant using monochrome color palette, simple fonts, and minimal line icons. I reduced extra elements, mainly using white space for creating visual hierarchy. Once that was in place, I could add small details like animations and a theme-switching feature around the edges.

2. Modern and technical. Doubling down further on simplicity, I wanted the website to have a modern and technical look and feel. This influenced my choice of font families and the design of small components like buttons and links.

3. Theme-able and keyboard-accessible. The areas I wanted to explore were theming and full keyboard navigation. Normally, these are not the main focus of design, but I wanted to highlight them on my website. I believe they add value, not only for accessibility but also for user convenience and the overall look and feel.

These characteristics directly influenced the content structure I went with.

1. Homepage. I wanted the homepage to have a one-sentence description of what I do—nothing more, nothing less. The rest of the content can be accessed through navigation.

2. About. Separately, I wanted to share a bit more about my personal and professional background for those interested. This part highlights my main interests in engineering and beyond, along with a glimpse of my human side outside of tech.

3. Work. I decided to create a separate page to list the teams I've worked with recently, along with a brief description of what I did at each place. This serves as a concise version of my résumé.

4. Writing. Writing has become a core part of who I am as an engineer, both within the teams I've worked with and externally. I wanted to create a separate space to highlight a few of my most recent public articles, providing easy access to my blog.

5. Contact. I wanted people to have an easy way to reach out, so I included the contact information and links to social platforms in the navigation menu, making them just one click away.

With the content structure in place, I was ready to start designing. I chose two fonts—Geist as the primary sans-serif font and Geist Mono as the secondary monospace font. Both fonts look clean and modern, with the monospace font adding a more technical feel.

I made a few iterations in Figma and settled on the following design. I had a few other pages roughly sketched out, which was enough for me to start the implementation.

The implementation

I had a few goals in mind when starting the project.

1. Server-side generation. I knew the website would be simple, with some interactivity, but mostly focused on the content. Server-side generation was probably going to be the right rendering approach, so I wanted my setup to support it.

2. React and TypeScript. This is my bread and butter, the tools I use every day, and they have a great ecosystem built around them. Even though it would have been just as viable to implement this using plain HTML, CSS, and some JavaScript, I wanted to stick with my regular stack purely for ease of development.

3. Maintainability and support. I wanted to choose tools that are well-established, have good support and resources, and—as a result—are likely to remain in good condition five years from now.

The framework

After some research, I decided on Astro. My friend, Ray Gesualdo, recommended it to me and even wrote a short blog series about moving his own website and blog to Astro (you can read it here).

Even though Astro is a relatively new framework, it has excellent documentation and many integration options, including React. It allowed me to have a statically-built site with almost perfect Lighthouse scores—all by default, without any extra effort on my part.

Design system

Even though I didn’t need many components, I knew it was useful to choose a component library. I have implemented enough buttons and basic typography components in the past, so now I know better. I used to work with Stitches and Radix, and I really enjoyed both.

I noticed that the team behind Radix recently introduced Themes, a component library built on top of Radix's primitive components, offering theming options as the name suggests. This was a no-brainer.

It turned out to be a fantastic choice. Implementing the pages was easy, ensuring all basic design elements were consistent—from colors, typography, and spacing to the smallest components like buttons or links. It also supports a dark theme right out of the box, which I knew would be useful.

Theme switcher

This was an area I wanted to explore much deeper. I was impressed with Jacky’s website's animated background, and since it was open source, I decided to build on it. The effect transitions smoothly from day to night but is actually more granular under the hood, moving through 6 distinct phases altogether. I wanted to expose this to users, so I introduced six themes based on the six phases of the day: dawn, sunrise, day, sunset, dusk, and night, instead of just two (light and dark).

I needed to make some small adjustments to the colors so each state has enough contrast and connect it to my setup with theme-switching controls. The value of the currently selected theme is stored in local storage. I've experimented with it a lot, trying to refine how it’s done with Astro—it's still not perfect with the statically generated pages (even though the value loads before the page renders).

Update: I just found a version that works—read more about it here.

I decided to leave it as it is. The final touch was to add a subtle swoosh animation for the icon when the day changes to night.

Keyboard navigation

Inspired by Stripe’s developer site, I wanted to add hotkeys for interactive or navigation elements. I used the Kbd component from Radix to display the hotkey next to each interactive element.

I didn't want the hotkey hints to always be visible, so I added a separate layer where the keyboard shortcut hints appear when the user presses C. This is managed through a global context provider and is passed to all hotkey components.

Other tools

Finally, here are some additional tools, packages, or services I used during the process.

• Icons: Radix Icons

• Animations: Motion

• Hosting: Netlify

• Analytics: Umami

The final result

That's it! The process took about three months of light evening coding, which was much longer than I expected, but I'm really happy with the result. A big thanks to my friends who helped me make decisions along the way and provided feedback!

Again, you can see the result here: https://tomaszgil.me/.

If you enjoyed the article or have a question, feel free to reach out to me on Bluesky or leave a comment below!

Further reading and references

• Photo by Matt Hardy on Unsplash.

In this article, we explore the intricacies of pull request sizing, focusing on how to balance change size and scope to maintain momentum and reduce complexity.

You’re never done

In the world of software engineering, we’re never truly done. There’s always something to address. This applies at the system level, the feature level, and even to a single change introduced to a codebase. Here are a few scenarios that might sound familiar.

• Maybe I’ll just go and implement this next bit as well…

• Ugh, this looks ugly - this could use a little refactoring…

• This lacks tests - let me add some while I’m at it…

These are all good instincts—I even wrote a blog post about this—instincts that, when shared by engineers working on a project, can significantly help maintain that project long-term. However, these instincts can also lead to a loss of focus, causing engineers to become sidetracked by improvements that, while beneficial, may not be immediately necessary and negatively impact the overall delivery.

At some point, we have to call it a day, let others review the change, and merge it. But is a longer change always bad?

Change size and change scope

First off, it’s good to clarify ways in which we can describe how large a change is. I really like the terms that the book "Software Engineering at Google" uses for that. The terms introduced are size and scope.

• Change size is the quantifiable measure of code modifications, typically involving in metrics like lines of code changed or number of files modified.

• Change scope refers to the broader impact and implications of a modification. It considers factors like the number of dependent systems affected, potential performance implications, security considerations, and the extent of testing required.

What to focus on

Both size and scope are important, but they are not the end goal. What we are ultimately trying to assess is the change complexity - and potentials risks related to it. Change size is simple to measure through tooling, so it’s easy to assume that this is equal to change complexity. Even though it can serve as some indicator, it can be widely misleading. To give a few examples:

• A one-line change to a critical API could be small in size but have massive implications on the entire system.

• Refactoring of documentation might involve many lines but carry minimal risk.

• Running an automated change across dozens of files is large in size, but not complex or hard to review.

• A small change that covers a few unrelated concerns makes it harder to thoroughly review the code.

Change complexity isn’t equal to change size—it is a combination of size and scope. What we want to aim for is reducing change complexity. By doing that, we gain several benefits.

• Easier review - the review process is quicker and, because the change is more focused, it can be more accurate at the same time.

• Reduced risk - there is less impact if something goes wrong, making it easier to identify and roll back issues when they occur.

• Better testing - test coverage becomes more focused, making it clearer what needs manual testing and what might cause regression.

• Team collaboration - more frequent code integration leads to better knowledge sharing across the team and reduces the chances of blocking other team members.

Maintaining momentum

On a practical level, reducing change complexity is important, but so is maintaining momentum. This applies to both you and those who will review your code. There is a point of diminishing returns—splitting changes too much can slow you down as the operational costs, like creating separate branches, managing commits or introducing feature flags, may simply take too much time and, as a result, outweigh the benefits. The same goes for the reviewer—it's helpful to review small changes, but if there are multiple review requests every half hour or so, it leads to constant context switching.

Where this point lies depends on many factors, and there is no strict rule for it. Nevertheless, t's important not to spread yourself too thin.

Practical tips

We discussed the reasons for reducing change complexity; now let's talk about how to do it. There are several ways to simplify changes, and you can apply these steps at any stage—before starting, while working on the change, or even after it's ready. Here are some methods that have worked well for me. The approach you take should take, however, depends on different factors, so you can choose what works best for each situation.

1. Assess the complexity. As we've discussed, assessing complexity involves two dimensions: size and scope.

   1. How many lines of code have you or will you change? How many of these is effective code (not autogenerated or moved)? How many files were touched? These factors will contribute to your change size.

   2. How many different concerns have your covered? Does you change include feature implementation, introducing tests, generating translations and some related refactoring work? How many other services will depend on this change? These factors will drive up the change scope.

2. Decide how to run your change. Once we know the change size and scope, we should decide if the change actually needs to be split or not. Here are some guidelines that work for me.

   1. Small in size, small in scope. It's the best and probably the most common type of change, like addressing a single issue in one part of the code. It can be handled as a single change and will likely be easy to review and deploy.

   2. Large in size, small in scope. An example of this type of change might be addressing a specific concern throughout the entire codebase, like updating imports for a reusable package. These changes can often be automated, both in implementation and possibly in review. It's fine to run them as one change, and they are often easier to manage that way.

   3. Small in size, large in scope. These are focused changes that affect critical functions or handle multiple concerns—this type of change might be worth splitting into smaller parts. It all depends on the context and circumstances. Even if you decide to keep it as a single change, it's important to consider ways to make it easier to review.

   4. Large in size, large in scope. There are changes that affect multiple concerns across different parts of the codebase—they should always be divided into smaller parts. The approach will vary depending on the specific situation, but it's always helpful to break these into smaller pieces.

3. Document with comments. Even if you decide to keep it as a single change, it's helpful to document your change with comments. Comments in the code at the right places can be useful, but here I mainly mean comments for reviewing the change. There are two ways you can do this.

   1. Change description. It's important to include several elements. Did you provide context for the problem you're addressing and outline the high-level approach to the solution? Did you clearly describe the scope of the change, detailing what areas it covers? Did you make sure to link to any relevant resources that can offer additional insights or background information? Lastly, if you have a recommended way to review the change, have you included that as well? This can all help reviewers to evaluate your work effectively.

   2. Change comments. Adding context for reviewing in the change description is good, but adding comments is even better—the information is placed exactly where it's most needed. I often comment on my own pull requests before submitting them for review to highlight areas with significant changes, outline the type of change, or indicate that the code has been moved. When writing these comments, it's also helpful to consider if the comment will only be useful during the review or also afterward. If it's the latter, consider moving that information into a code comment.

4. Think about your commits. If the comments aren't enough to provide all the necessary context for reviewing a change, it might be worth splitting the change into individual commits. You can create commits based on the files or areas affected, or by concerns, such as separating a commit for implementation from a commit for tests. The individual commits still make up a single change but offer a clear separation.

5. Consider a follow-up pull request. Taking it a step further, you can open a follow-up pull request. This can be especially helpful for addressing optional code review feedback or making improvements. It's similar to splitting commits but provides even more separation and clarity.

6. Split the task. To give yourself even more flexibility, you can split the task entirely. This allows you to open separate pull requests, similar to the previous point, with the added benefit of getting back to the drawing board, reconsidering requirements, and planning individually.

Conclusion

That’s it! Deciding the right size for changes in software projects involves balancing change size and scope to reduce complexity and maintain momentum. While instincts to refine and improve code are valuable, they can distract from the main goals. Assessing change size and scope helps in managing change complexity, risks, and reviewing efficiency.

If you enjoyed the article or have a question, feel free to reach out to me on X or leave a comment below!

Let's explore the strengths and trade-offs of these approaches, and why you might prefer to actually only use one of these two types for most of your components.

🚨 Be warned, this post is highly opinionated.

Example: Alert Component

For the purpose of this article, we'll take a look at a small alert component with two example implementations. Let's say our application need alert components that meets the following requirements.

• It displays a title and a description.

• It has one of four statuses: success, error, warning, or info.

• Depending on the status, it shows a different icon and color.

Here's what this component might look like.

Let's compare how our component might be used in both its configurable and composable versions. I'll focus mostly on usage rather than implementation for a crucial reason: for any reusable components, the API is often more important than the underlying code.

You can view the example implementation here.

Configurable components

Configurable React components have the following characteristics:

• DRY (Don't Repeat Yourself): These components often reduce code duplication by encapsulating common patterns and behaviors.

• Complex implementation: As they need to handle various use cases through configuration, their internal logic can become intricate.

• Strict output control: They provide more predictable results, allowing developers to tightly control the component's output. This can be advantageous for consistency but may limit flexibility.

Using such a component might look like so.

<Alert
  status="success"
  title="Success"
  description="Your action was completed successfully."
/>

Composable components

The attributes of composable React components are:

• Simplified implementation: Composable components tend to be smaller, have a simpler implementation, making them easier to both read and write.

• Leveraging React composition mechanism: These components take advantage of React's built-in composition features, aligning well with React's core design principles.

• Less control over the outcome: It allows for more flexibility in how the component is used, but may also lead to less predictable results in some cases.

Using such a component might look like so.

<Alert status="success">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Success</AlertTitle>
    <AlertDescription>
      Your action was completed successfully.
    </AlertDescription>
  </AlertContent>
</Alert>

How components change over time

We've successfully implemented the alerts and are happily using them in our application. It turns out, however, that we will need to show more alerts in new parts of the application, but they need to be slightly different.

Let's revisit our example. Suppose we need to implement new alerts with additional requirements on top of the existing ones:

• Dismissible alerts: Alerts display an additional button to dismiss

• Optional icons: Not all alerts require an icon

• Action buttons: Alerts can display an additional action button with a label and an action

Here’s how it might look like.

Now, let's see how the APIs of our example components need to evolve to accommodate these new requirements.

Configurable component

Configurable components grow by expanding their configuration—introducing more props. Here's how our API might evolve:

<AlertConfigurable
  status="success"
  title="Success"
  description="This alert has all features enabled."
  showIcon={true}
  dismissible={true}
  onDismiss={() => console.log("Alert dismissed")}
  actionLabel="Take Action"
  onAction={() => console.log("Action clicked")}
/>

We've added several new props: two for the dismiss button (one to indicate if the alert is dismissible and another for the dismiss click handler), one to control the icon's visibility, and two for the action button (label and click handler).

Composable component

In contrast, the way composable components evolve is, most often, by having more components added into the mix - either by splitting existing ones or creating new ones. Here’s how it might look like.

<Alert status="success">
  <AlertIcon />
  <AlertContent>
    <AlertTitle>Success</AlertTitle>
    <AlertDescription>This alert has all features enabled.</AlertDescription>
    <AlertAction onClick={() => console.log("Action clicked")}>
      Learn More
    </AlertAction>
  </AlertContent>
  <AlertDismissButton onDismiss={() => console.log("Alert dismissed")} />
</Alert>

We need to create two more components - one for alert dismiss button and one for alert action button. Their APIs will cover requirements relevant to these elements. Optional icon we get for free - if you don’t want this element, just don’t render it.

So, which one should we choose?

Your component implementation doesn't matter as long as existing alerts remain unchanged and new ones follow the initial requirements. However, in large-scale applications, the odds of this happening are, in my estimation, lower than winning the lottery.

I've worked on numerous projects of various sizes. In my experience, regardless of the project's size, scope, or initial assumptions, there's always one more case to handle. There's always that one page that needs to be different, that one component instance we want to tweak, or that one user flow that escapes the initial requirements.

We already went through one round of changes—now imagine we go through a few more iterations. What happens to the configurable component?

Apropcalypse

There is a funny term called apropcalypse, coined by Jenn Creighton, to describe components with dozens of props. This happens when there are too many props to cover all possible configurations and ensure reusability, but instead, it makes the component inflexible and leads to a cluttered API.

This is what configurable components often turn into, as you can see in our example—we made only a few changes, the number of props increased to 8.. We tend to have a just one more prop mindset when making changes—it's often easier to add to an existing abstraction rather than rethink the original design and potentially break it up into smaller pieces.

Speaking of abstractions...

Patterns, patterns everywhere

Configurable components can provide more immediate value due to their opinionated nature. They're often quicker to develop with, at least initially. You can create a single component that encapsulates an observed pattern, use it wherever needed, and adjust props to achieve the desired behavior. It's fast and effective.

However, the question remains: Is the pattern you've observed truly a pattern? How do you know? With composable components, you don't need to answer these questions at all. The trade-off is more code—often repeated code—but that's by design. You're allowing each piece of UI using this component to evolve independently in the future. There's value in this flexibility, though it's not immediate. It's the value of adaptability to change.

A word on DRY

This concept directly relates to DRY—Don't Repeat Yourself. Having two pieces of code look similar isn't sufficient reason to abstract them. You need one more crucial piece of information.

The key question is: Will these code segments change together in the future? If you have strong evidence for that, then by all means, create an abstraction that expresses this relationship. This is where more opinionated, configurable components truly shine.

The challenge lies in answering that second question—it's difficult, if not impossible, to predict the future with certainty.

I highly recommend reading Swizec's insightful post on this topic.

Optimize for change

Composition is at the heart of building applications with React. It's one of the main reasons why React has become so popular.

Design systems and component libraries are a good example of this. Since the exact use cases for the components are fundamentally unknown to the library providers, they need to optimize for extensibility and composability. There is very little certainty about how these components will end up being used and arranged together. As a result, design system libraries tend to be built heavily relying on composable components.

But your application code is in a components library. The number of use cases you need to support is not infinite—it's probably just a few. So, you might wonder, why bother creating smaller, composable components?

To start, these components are fundamentally optimized for change, which is one of the signs of a good API. They utilize React's composition mechanism, aligning with the framework's nature, and demonstrate that JSX is simply the right abstraction for most cases. If it works for most of the industry, it's likely a good fit for the UI you're trying to implement. I would say make sure you have strong reasons if you decide to do something different.

When you build your components to be composable, changes usually require less work (or sometimes come for free, like in our example)—both in implementation and regression testing. Implementation is simpler because you’re changing smaller pieces at a time and don’t have to deal with many dependencies. Regression testing is also simpler because instances of the components are more isolated.

It's perhaps easier to justify composable components for low-level UI elements like buttons, form elements, menus, or—as in our example—alerts. These need to be flexible because they're used frequently. However, change isn't limited to low-level UI elements—it happens across all levels.

With that in mind, I believe composable components are your best bet.

What about using both?

There’s a case for having both composable components and configurable versions of components and use the right one depending on the use case. Here’s how you could approach this.

• Create composable components.

• Create opinionated configurable components that use foundational composable components.

• Use configurable components for the most common scenarios.

• For more complex scenarios, create custom implementations using composable components instead of extending configurable ones.

Where this approach gets tricky is avoiding the just one more prop tendency and not extending the configurable components' API over time. Additionally, it requires everyone to stick to this approach and have a shared understanding of when to use a configurable component and when to switch to a custom, composable implementation.

When done correctly, we get the best of both worlds: composable components provide flexibility, while configurable components offer quick implementation. However, in my experience it's not easy to achieve this with real projects that have many engineers working in parallel.

Conclusion

That’s it! We discussed how to structure components in React using two approaches: composable and configurable components. We also explored how these components might change over time.

Configurable components provide immediate value and strict control, but they can become cluttered and inflexible as requirements change. Composable components are more flexible and easier to adapt in the long run, especially in large-scale applications.

This flexibility is worth optimizing for, so I recommend choosing composable components for better adaptability, using configurable components only when there's a strong need. Understanding these concepts will help you make better decisions when designing your components.

Further reading and references

• Full code available in this CodeSandbox.

• Avoid soul-crushing components by Kent C. Dodds.

• DRY – the common source of bad abstractions by Swizec Teller.

• Optimized for Change by Dan Abramov.

• Photo by Karsten Würth on Unsplash.

Like many others, I was directly impacted by this situation - I found myself without a job, facing the challenge head-on. This situation pushed me into the job market again, looking for new opportunities. Throughout the journey, I've had some interesting observations and thoughts that I plan to share with you in this article. ✍

What this article is not about

Before we jump to that, I want to outline a bit more what this article is about. I'll do it slightly differently, by first inverting the question - I'll start with what this article is not about.

This is not a definitive guide to landing a job. There are plenty of articles covering that topic broadly and a plethora of write-ups diving deep into various aspects of interviewing, both technical and non-technical. I'll be linking to some of the resources I used at the end of the article. What you need to successfully go through an interview process varies a lot based on the role you're applying for, the size and maturity of the company, as well as your experience and skills.

This isn't a recipe for dealing with being laid off either. Even though this event was unexpected and stressful, fortunately, it was manageable. I can only imagine how hard it might be for other people, with a different background, sets of circumstances, or overall life situation.

To give you a complete picture, I'll be sharing some basic stats like the number of positions I applied for or the number of offers I received. This isn't a way for me to brag - instead, I want to give you an honest picture of what was needed to increase my chances of success.

Ok, so what this article is about?

What this article is about

It is merely a recap of what occupied my time in the last months, alongside some thoughts and observations of the entire process. It is a list of those things that have worked in my favor and those that have worked against me. Even though this is specific to my situation and professional experience, I suspect that some elements might prove to be generally applicable and you'll find some useful insights - whether you're currently looking for new opportunities or not. 🙌

Timeline and numbers

To give you a broad picture, I'll start with the timeline and some numbers, which should illustrate the interview processes I took part in.

• The sad news. I got the sad news in the second week of September. We all knew the situation in the industry, but it nevertheless came as a surprise. I gave myself a couple of days to rest and then got to work.

• Research and interview preparation. I listed about 60 companies that roughly fit my criteria of places I would want to join. Some of these companies had open positions that matched my experience and skill set, and some only had their talent pools open. I prioritized the list, selecting half a dozen of the positions that I had the most interest in, and decided to apply for first. As the weeks went by, I went down the list and ultimately applied for a total of 30 positions.

• Reaching out to the network. Outside of cold applications, seeing how responsive companies are in general (or rather unresponsive, more on that later), I decided to tap into my network to increase my luck surface area. Apart from publishing a typical update on LinkedIn and Twitter, a few weeks into the process I decided to send out a message directly to every recruiter who had messaged me within the two years prior. I always reply to recruiters on LinkedIn, kindly declining new offers, so sending this kind of message wasn't completely out of the blue. I was already in contact with them, technically. I felt justified. Altogether, I sent out messages to 500+ recruiters and got responses from about 100 of them - I found 10 open positions that looked interesting to me, but I dropped out of most of these processes after the initial call with the recruiter. Even though most of that didn't have any material results, it contributed a lot to my sense of security. At the end of the day, I saw there were still plenty of opportunities out there.

• Interviews. I ultimately participated in 5 interview processes start to finish. I had the first interview at the very end of September, and the last one in the second week of November - a total of 34 meetings (some were just short calls, some a couple-hour-long interview sessions). Most of these processes had 3-4 steps, some included an extensive async coding exercise, and most had technical interviews with live coding and experience and background interviews.

• Offers and decision: These 5 interview processes resulted in 4 offers I could choose from. I would be fairly happy signing any of them, which had made the decision-making process quite comfortable. I made the final decision in the middle of November, making the entire job hunt last about 2 months.

All of that translated to the following numbers.

• number of recruiters that I spoke to: 500+

• number of applications filed: 40

• number of companies that rejected my application: 16

• number of companies I haven't heard back from: 14

• number of processes I dropped out of: 5

• number of processes I participated in: 5

• number of offers received: 4

• duration of the entire interviewing process: ~2 months

Looking back, it was a lot within a fairly compressed timeframe. That said, the number of processes I took part in was about right - not enough to wear me down too much, but enough to give me great options to choose from. 🤝

Thoughts on the market

I'll start with general market considerations. The tech market has changed. We all know it. We hear about it left, right, and center. Whether or not this change is persistent, only the future will tell.

Could I feel this during the interview process? Definitely. It's no longer truly an employees' market, as it mostly has been for the last decade or so. We have to take into account, however, that we're stepping down from a really high horse. As I mentioned in the beginning, the massive rounds of layoffs and the corresponding change in the hiring market, are in substantial part related to the excessive hiring that took place in the last few years, or to the outpour of money flowing into higher-risk ventures. 💸

Most companies at some point in the interview process referred to the apparent change in the market. Often that's normal - some of the people I talked with were completely honest and transparent about how they simply don't have as many resources available or are constrained by the uncertainty of their profits going into the future. Some people however used the change in the market as a negotiating tactic to subtly nudge me into making a decision - as at this moment I should really consider accepting less, but in a safer place. Yes, that was fun. If you're interviewing, be prepared for that.

Ultimately, your interviewing experience will vary based on what you bring to the table, but there are plenty of good opportunities out there, and it seems to slowly be getting better and better with each month. 📈

Know what you're looking for

Even though it might seem that nowadays the market conditions overshadow any internal factors when interviewing, I believe what you control is still far more important than what's going on on the outside.

Speaking about things that are in one's control, you have to know what you're looking for. Picking the next company to join should never be a unidimensional choice. There are many factors at play. Here are some of the things I paid attention to, in no particular order.

• Challenges you can help solve.

• Level of ownership and impact of your role.

• Company's mission and values.

• Mix of process and flexibility.

• Approach to software engineering (code quality, testing, best practices).

• Learning opportunities and knowledge sharing.

• Technologies used.

• Team size and organization structure.

• Clear career path and feedback culture.

• Company's business model and financial stability.

• Compensation (both cash and equity sharing).

Compensation is important, but so are what you'll be working on and who you'll be working with. No one factor inherently trumps the others. Figure out what's the right mix for you at this moment and let this be your north start not only at the very end of the process when you make the final decision, but at every step of the way. 🌃

Brutal honesty

The type of position one is looking for together with one's skill set and experience will define the breadth of opportunities available. It is important to be aware of that and be honest about it. It might sound obvious, but it's worth checking if our expectations can be reflected in reality.

In my case, there were a few overarching themes that have largely defined my opportunity set, as they were mostly non-negotiables.

• I was looking for a Frontend Engineer position, working with React and TypeScript.

• I wanted to work for a company that creates and maintains its own product - not a software house or consulting agency.

• I was looking for a senior role or above, with a high degree of ownership, in a place with a culture of continuous learning.

• I was looking for a remote-only position.

All of that combined inevitably meant that my target market was quite broad. React nowadays is the most frequently used frontend framework. There is a plethora of companies building their software systems in-house, and it appears to me that companies prefer hiring more experienced engineers, especially in recent years with the prevalence of remote work. Speaking about working remotely, looking for such positions exposed me to a global market, which is a major leap in quantity compared to the opportunity set available in my local market in Poland.

Even though I consider myself a valuable candidate, with substantial experience and depth of knowledge, there are many other fantastic engineers with similar skills. There's not much that makes me truly unique within the entire market, at least at face value. 🤷

To better illustrate what I mean, I'll bring up a family member of mine, who works as a Design Engineer. If you're like me, you'd ask what the heck does that mean. He works across design and engineering, solving user experience challenges across the entire stack. If your company has a deeply technical product, where you need engineering experience to figure out the best user experience, and then design it and implement it, he’s probably one of a few candidates available to you around the world. Now, that’s unique. His opportunity set is much more limited than mine, but once he finds a company with problems in his circle of competence - it's instantly a match.

All of that led me to another conclusion, that the wider your target area is, the larger role luck plays in the mix. As I mentioned before, I vastly overestimated the responsiveness of companies to my applications. In the first two weeks, I applied for only 10 positions and waited for their responses. As you might guess based on the number of positions I ultimately applied for, that was a mistake. Most companies have so many candidates knocking on their door, that the most you can expect is a generic confirmation, letting you know that they will contact you again only if they want to continue the process. Some companies will let you know that they declined your application, but a lot of them will outright ghost you. 👻

An advice that I got pretty early on was very simple - find and apply to more companies. Many more than you might initially assume. It turned out to be effective, especially when interviewing globally, which the next part is all about.

Global recruitment considerations

I was looking for a remote-only position, which opened me to a market beyond the companies in my local area or even my home country of Poland. It expanded the opportunities available massively, at the same time making the interviewing dynamic quite unique in subtle, but important ways.

I’m based in Poland. Many companies with a global presence won’t even consider me for all sorts of reasons. Sometimes it’s the timezone - for teams located on another continent, this could be an issue. Sometimes it's an internal policy - hiring outside of the company's home country is not straightforward, so they might prefer to hire locally and keep their existing HR process. Sometimes it's regulation - companies creating projects in certain industries or for government entities are often legally limited to only hiring within their home country. Finally, some companies are not even aware that hiring people as contractors is easier and cheaper for them than having full-time employees.

I said that there's not much that's unique in my experience on a global scale, but there's always something you can focus on that differentiates you from other candidates applying for a particular role. For me, in most cases, it was a combination of engineering and design background and deep front-end knowledge and experience. Figure out and clearly define what your edge is and structure your interviews around that. 🏗

Get used to rejection

Only 20% of recruiters responded to my messages, and 2% had open positions that seemed interesting to me. Only 25% of my applications resulted in interview processes and only 10% resulted in an offer being extended.

There's no other way around it - for most applications and interview processes the default response is rejection. You just have to make the math work in your favor - for me, it meant that to have an offer on the table, I had to apply for roughly 10 positions. And I think it's critical to have a few offers to choose from, so the best thing you can give yourself during that process is patience. 🧘‍♂️

The bar is sometimes surprisingly low

Once I was over the initial hurdle, things started falling into place. Given how tough it is sometimes to get your foot in the door, it's almost surprising, in contrast, what companies highlight as the factors that positively differentiate you from other candidates.

Some interviewers pointed to the fact that I wrote a thoughtful cover letter. Some interviewers pointed to the fact that they can clearly tell I've read the job description. Some interviewers pointed to the fact that I came prepared, and had familiarised myself with what the company does, its mission, and values before the interview.

None of this is too hard to do. It does require a bit of time but increases your chances of success. Don't skip these steps during your interview preparation. I always thought of them as obvious preconditions but turns out they can sometimes work as a differentiating factor. 🎯

Choosing your perspective

Another idea I had in mind when interviewing was the perspective one has on what they're trying to achieve. I believe there are two, distinct perspectives there.

The first perspective is that interviewing is a way to get a job. This implies that the company has a resource you want to secure. Resources are often scarce, hard to come by and obtain - the fact that something is scarce has a significant influence over humans' psychology. This perspective might not benefit you during the process.

The second perspective is that you want to provide a service for a company. This is the exact opposite perspective, as this implies you possess the resource the company is after. The scarcity principle becomes a tailwind, as you're there to provide value to whichever company ends up being the most interesting. This perspective will likely benefit you during the process.

Having that said, neither perspective alone reflects reality. Of course, you're after the job, and the company is after your expertise. The level of scarcity will depend on how high the bar the company has to meet is, and on the other side, what you offer as an engineer and how broad is your competition. But I still strongly believe it's worth primarily adopting the perspective that works in your favour. 🌄

Negotiation starts the minute you enter the door (or perhaps even sooner)

Much has been written about negotiation, especially job negotiations and even job negotiations in the tech industry. I highly recommend reading these particular articles I linked to, they have been a fantastic guide through offer negotiations.

One surprising aspect of the interview process, however, was how fast some companies initiated the negotiations.

There are arguably very few aspects that can give you an edge in negotiations as the interviewee. It's the company that controls the structure of the interview, they control whether they are going to extend an offer to you and what it ends up looking like - in most cases - almost entirely. They are in the driver seat, but they don't control everything. Information is your negotiating power. You can decide what information to share with the company about your preferences and when. I tend to retain as much of it as possible mostly because it gives me time to get more information about each company I'm interviewing at. ⏰

I don't typically share my desired compensation during the initial stages of the interview process. I don't think that makes sense - I know little about the company and the position. I don't know whether I'm the right fit for the company or how much I would want to work there. I also don't know what the company values and how they structure their compensation. And on the other hand, the company has no way of knowing how valuable of a candidate I am. Throwing numbers around at this point seems pointless to me.

To that, some might say - it's a waste of time, it's best to get alignment on compensation as soon as possible. Perhaps. You have to be aware though that once you share any numbers, you immediately narrow the negotiation space, likely to your disadvantage. The company would never share the actual compensation targets, especially during the first steps, and I believe neither need you. 🤷‍♂️

You should be able to get an idea of what the compensation for any particular position might be online. This won't be precise information, of course, but in most cases, it is good enough - the actual compensation the company can offer is always a range, likely changing throughout the process. You only need to have some directionally correct information.

I got asked the infamous "So, tell me, Tomasz, what are your salary expectations" multiple times. Often right after the first interview with the recruiter. The reality is that this is a normal practice. To that I often respond, competely honestly, that the opportunity sounds exciting, and once both parties determine that this is the right fit, I will be willing to explore any package, as long as it's competitive. Some recruiters will push beyond that, but it's infrequent.

However, during this series of interviews, I received hard pushback on this. In one process the recruiter insisted that I had to give a number, so we could move forward after the initial call. In response, I referred to general statistics, like the average total compensation of a senior software engineer in Europe, indicating at the same time, that I'm very much interested in moving forward. That wasn't enough - they said the company wouldn't be able to meet that expectation (even though I was merely pointing to statistics, not expressing my expectations) and asked how much I would be actually willing to accept.

It is straight-up attempt to make me commit to specific numbers and close negotiations before the process even started. It was especially striking to me, as this was a lead engineer role. I can understand that a company might have a good idea of what junior or regular engineers' compensation would be before any individual process, but for senior engineers and above the bands are typically wider and depend much more heavily on what the candidate brings to the table. This is impossible to estimate at the first step in the interview. I replied that I do agree that it's important that we're on "the same page", but I'm simply unable to provide precise numbers at this point, beyond what I already mentioned. The recruiter finally accepted my response and we moved on.

This situation would probably look different from my side, or I wouldn't be comfortable evgaging in negotiations in general, had I not had other processes lined up. But I had other options. This was extremely important during negotiations, mostly for my own psychological safety. Also, you might be surprised how widely the offers differ in their numbers. In base compensation alone, the distance between the lowest and the highest offer I received was nearly 2 times. The stronger your other options are, the more you can afford to risk in any one process. You're likely not the only candidate the company is interviewing, so the company shouldn't be the only one at which you're interviewing either. That's an easy way to force yourself into a terrible negotiating position.

Finally, it's worth remembering that even though negotiating might make it seem as if you and the company are at odds with each other, you ultimately have the same goal - to reach an agreement that benefits both parties. You want to find the best place for yourself to thrive and the company seeks quality service from the best engineer they can find. I found this thought helpful when moving through the negotiations.

Relationship with your recruiter is paramount

Last but not least, I wanted to touch upon the relationship with probably the most important person in the interview process. That person, I believe, is your recruiter.

Picture your recruiter as your backstage pass to any one opportunity - a person who not only opens doors but also has your back when it comes to sealing the deal. This is a person who will be the proxy to you getting all of the information and any offer negotiation you might have most often will be handled with them. As much as they want you in their corner, you want them in yours. Ultimately, this collaboration will directly impact how well you know what you're about to step into and the degree to which your efforts will be rewarded.

This series of interview processes was a stark example of how important this particular relationship is. In three out of the four successful processes, I had close contact with the recruiters. We've had a few video calls throughout the journey. I kept them updated on what was going on on my side and they periodically checked in to see how everything was going and how I felt. Contrary to that, during the last process, my interactions with recruiters were limited to emails only. Additionally, one recruiter was handling the first part of the process, and another one the second part. There was no time or space to build any form of relationship. 🍂

The outcome speaks for itself. When the relationship with the recruiter was good - which was the case in the first three processes - I got all of the information I asked for and then some. The recruiters often went the extra mile to provide me with additional details, reaching out to other teams in the company to get some more context for me. I was also able to improve each of these offers - often meaningfully and virtually without any tension. In the last interview process, I almost literally hit a wall - I received pretty vague strands of information throughout the process, and my attempt to negotiate was turned down in a single email, in a fairly impolite way.

Looking back at the situation I can share a few simple suggestions I found to be helpful to get you on the right path with your recruiter. 🛤️

• Show them that you mean business. They should be able to tell that you are serious about the opportunity and ready to engage in negotiations.

• Express enthusiasm. Show that you're excited about the opportunity, while moving towards reaching the final decision.

• Be cooperative. If you want a good spouse, deserve one. This rule applies in any relationship, not only in marriage. You want to be as collaborative and helpful to your recruiter as possible - they will most likely return the favor.

• Be likable. No one wants to advocate for someone they don't like, so simply be kind. Positivity and simple kindness towards others are seldom overrated.

I'll mention for the record, that all of the above should come from a place of genuine interest and honesty. If you're not interested in joining a particular company, don't waste anyone's time - drop out of the process early and look for something that is a better fit.

Making sure your relationship with the recruiter is good is extremely important. It might seem like it's just wasting time on meetings, but it's absolutely not - and it goes both ways. There's as much in it for them as there is for you. 🤝

The outcome

This was a long journey, which required a lot of preparation, attention, and effort. I can say now, however, already a couple of months into my new position, that it all ended exceptionally well. I'm super happy to report that I joined Salesloft as a Senior User Interface Engineer. I'm excited about the challenges that lie ahead and to be a part of a terrific team. 🥳

All of this would have been much more difficult, if not impossible, if it wasn't for the support I received. I'm especially thankful to my wife, for being there for me during the whole process. And to my engineering friends, for their help and multiple pieces of often invaluable advice. Thank you!

If you liked the article or you have a question, feel free to reach out to me on Twitter‚ or add a comment below!

Further reading and resources

Here are some of the resources I found useful during the entire process.

• What to look for in a company:

  • https://blog.pragmaticengineer.com/pragmatic-engineer-test/

• Interview preparation:

  • https://github.com/learn-co-curriculum/bootcamp-prep-answering-non-technical-interview-questions

  • https://gist.github.com/nonsie/d07ebc343e23e5b5cd544609d1767f93

  • https://github.com/viraptor/reverse-interview

• Salary negotiations:

  • https://haseebq.com/my-ten-rules-for-negotiating-a-job-offer/

  • https://haseebq.com/how-not-to-bomb-your-offer-negotiation/

• How to value equity:

  • https://blog.pragmaticengineer.com/equity-for-software-engineers/

• Notes from other engineers' job hunts:

  • https://szymonkaliski.com/newsletter/2023-04-03-q1-2023/

• General career advice:

  • https://kentcdodds.com/blog/business-and-engineering-alignment

  • https://swizec.com/collections/seniormindset/

Other resources:

• Photo by Sergei A on Unsplash

Today we cover continuous integration and delivery. These are systems and processes that define how members of engineering teams bring their work together, how the software is built, tested, and finally, delivered to your users. Let's dive in!

Shift left

The fundamental goal of continuous integration systems is to catch problematic changes as early as possible. As with most of the things we've discussed in this series, this becomes virtually impossible to do manually as projects grow. CI systems become progressively more necessary as your codebase ages and grows in scale. 📈

Furthermore, finding problems earlier in the developer workflow usually reduces costs. Bugs caught by static analysis and code review before they are committed are much cheaper than bugs that make it to production. Here's where the general rule related to CI systems comes into play - Shift Left. ⏪

Shift left: enable faster, more data-driven decision-making earlier on all changes through CI and continuous deployment.

The purpose of testing is to gather information. Information about problems in your systems. Having this information earlier in the workflow allows having shorter iteration cycles, which means fewer bugs introduced and better quality features.

Minimise human decisions

There are certain things humans excel at and there are things humans are inherently bad at. Consistently enforcing rules at scale arguably falls into the latter category. 🙃

One decision you need to make with every new change is which tests should be run against the changes being introduced. These decisions should be made consistently and repeatedly. Because of that, the book makes the case that this should never be up to individual engineers. A CI system decides which tests to use, and when. That way we always follow explicit rules, and we can reach the desired balance between deployment confidence and speed of development.

The book also suggests that CI should optimize for quicker, more reliable tests on presubmit and slower, less deterministic tests on post-submit. That way we can keep a reasonable pace of development while making sure we don't break things when releasing. 🧘‍♂️

Ship often, ship fast

The book makes an interesting observation about how the speed of delivery impacts the safety and confidence in changes being released.

Faster is safer: ship early and often, and in small batches to reduce the risk of each release and to minimize time to market.

There are a few important steps you might want to take to ensure fast and effective releases. 👇

• Optimise for team velocity. Velocity is a team sport. The optimal workflow for a large team that develops code collaboratively requires modularity of architecture and near-continuous integration.

• Evaluate changes in isolation. The only way to be sure what broke is to isolate changes. A typical way to achieve that is to flag guard any features to be able to isolate problems early.

• Make reality your benchmark. Use a staged rollout to address device diversity and the breadth of the user base. Release qualification in a synthetic environment that isn't similar to the production environment can lead to late surprises.

• Ship only what gets used. Monitor the cost and value of any feature in the wild to know whether it's still relevant and delivering sufficient user value.

Conclusion

That's it for today. CI systems become necessary for growing teams and codebases, making it possible to efficiently and safely integrate work and deliver your applications. Here's a short summary of things we went through:

• CI systems become more necessary as your codebase grows in scale

• Shift left: enable faster and data-driven decision-making earlier on all changes

• A CI system decides what tests to use, and when

• Faster is safer: ship early, often, and in small batches

• Optimise for team velocity, evaluate changes in isolation, make reality your benchmark, ship only what gets used

Congratulations! 🥳 We've just reached the end of the series where we covered lessons learned from the book Software Engineering at Google. We've touched on a lot of aspects of software engineering as a process, but the book still covers a much wider array of topics. I hope you found this series useful and that you learned something that you will use in your work in the future. 🚀

If you liked the article or you have a question, feel free to reach out to me on Twitter‚ or add a comment below!

Further reading and references

• The original Twitter thread with notes from the book.

• Link to purchasing the book.

• Photo by CHUTTERSNAP on Unsplash.

Today we cover dependency management. The management of networks of libraries, packages, and dependencies that we don’t control is one of the most challenging problems in software engineering. We will discuss how we update between versions of external dependencies and how to decide whether to depend on someone else's code. Let's dive in!

Hidden costs of dependencies

One of the best features of the software engineering industry is the availability of open source solutions. For virtually any problem that might creep up in various software applications, there's most likely an open-source solution. You need to format or manipulate dates? There's a library for that. You need to keep track of the state of a form in a web application? There are open solutions for that too. This allows you to focus for the most part on the unique business problems that your software is solving. 🎯

However, as the book mentions, adding a dependency isn't free for a software engineering project, and the complexity of establishing an "ongoing" trust relationship is challenging. Importing dependencies into your organization needs to be done carefully, with an understanding of the ongoing support costs.

A dependency is a contract: there is a give and take, and both providers and consumers have some rights and responsibilities in that contract. Providers should be clear about what they are trying to promise over time - but that might not always be enough. The book brings up an interesting observation, that goes under the name of Hyrum's Law. 👇

With a sufficient number of users of an API, it does not matter what you promised in the contract: all observable behaviors of your system will be depended on by somebody.

By using external dependencies, your application relies on code you don't control, code that is released on an independent schedule, and can be updated in ways that you don't expect. It doesn't mean you shouldn't depend on it. It does mean, however, that you have to be careful how you use the dependency (and what you promise on the other side) and how you manage the relationship.

Reducing the problem complexity

In a large organization dependency management doesn't only refer to external dependencies. You might have different teams working on distinct parts of your system in separate repositories, which are then used in other parts of your organization. Synchronizing package versions of these solutions across separate repositories is also a dependency management problem.

According to the book, one way to reduce the complexity is by having all the teams working in a single mono repository, effectively replacing dependency management problems with source control problems. If you can get more code from your organization to have better transparency and coordination, those are important simplifications. 📉

The Holy Grail

The overarching goal of dependency management is to be able to use the newest versions of packages and perform upgrades easily. Getting to the point at which you can reliably stay current when it comes to project dependencies going forward, is the essence of long-term sustainability for your software. 🏆

The book mentions that the only way to achieve this at scale is, as with many other things, through automation. You need to build the processes around your software in a way that infrastructure upgrades over time can be performed by the same number of engineers, even as the codebase grows. That's key. Otherwise, the cost to your dependencies increases not only increasing number of dependencies themselves but also the overall codebase growth. 😬

There are a few elements that are essential to automate dependency management process.

• Keep track of dependency versions. The first step of external dependency management is keeping track of the versions in use. Most programming languages and their respective ecosystems have a common way of defining these versions, often using Semantic Versioning.

• Use notifications when new versions are released. Make sure engineers know about new releases of packages their systems depend on. Ideally, when a new version of a library gets released, it should trigger the opening of a merge request in all relevant repositories. That gives engineers the easiest way to act.

• Auto-generate changes. The best and biggest open-source libraries often feature scripts that allow for automatic code modifications (commonly referred to as Codemods) with major version releases. They can speed up the upgrade process drastically and decrease the number of omissions.

• Test and release. In large projects with dozens of dependencies, it's not possible to manually test every upgrade. Instead, your infrastructure should decide, for the most part, if a change is ready to release. Write your tests in a way that allows them to be leveraged in such situations.

Conclusion

That's it for today! Dependency management is often an underappreciated aspect of software engineering, however being able to upgrade to the newest versions is a cornerstone of long-term sustainability for your software. Here's a short summary of things we went through:

• adding a dependency isn't free for a software engineering project

• dependency is a contract: there is a give and take, and both providers and consumers have some rights and responsibilities in that contract

• Hyrum's Law: all observable behaviors of your system will be depended on by somebody with a sufficient number of users

• replacing dependency management problems with source control problems often reduces the complexity

• for long-term sustainability, project dependencies need to reliably stay current

• infrastructure upgrades over time should be performed by the same number of engineers

In the last part, we will cover continuous integration. We will touch on the inevitable nature of such solutions in growing systems and highlight what's most important for having a successful integration and release process. See you! 👋

If you liked the article or you have a question, feel free to reach out to me on Twitter‚ or add a comment below!

Further reading and references

• The original Twitter thread with notes from the book.

• Link to purchasing the book.

• Photo by Christopher Burns on Unsplash.

Today we cover software maintenance. Any successful system will face, sooner than later, some form of a maintenance burden. Unattended, it might turn into technical debt, which, as any other type of debt, is a double-edged sword. It can be an effective tool as long as it is treated with carefulness. Let's dive in!

Assets and liabilities

In the financial realm, the most prevalent categorization of financial resources are assets and liabilities. Assets are things that you own and that have economic value. Liabilities can be contrasted with assets, they refer to things that you owe and are a drag on economic value.

This distinction is pretty clear. Financial resources are either assets or liabilities. It's also an interesting lens through which we can look at code. However, code escapes this categorization. It's as if it had aspects of both assets and liabilities - almost always directly contributing to creating the former, but eventually highly likely to turn into the latter. 🤷‍♂️

As the book says, code itself doesn't bring value: it is the functionality that it provides that brings value. That functionality is an asset if it meets a user need: the code that implements this functionality is simply a means to that end. We use it to create assets.

Once our code no longer provides the functionality users need, it causes significant maintenance problems or we're migrating to a newer solution, it instead starts creating liabilities. We have to maintain it, paying the costs overtakes reaping the rewards, as it no longer provides the value it was there to create for us. 💸

Scalably maintaining complex software systems over time is more than just building and running software: we must also be able to recognize and remove systems that are obsolete or otherwise unused.

System migration

Let's consider a scenario where you observe the first signs of deterioration. Your internal library all of a sudden has many more responsibilities than initially designed for. A key service behind your application is no longer supported. You have a feature on your roadmap that you know will be impossible to implement given the current architecture of your system. 🏗️

One potential answer to these problems might be to migrate the part of the system that causes issues. The book mentions however that migrating to entirely new systems is extremely expensive and the costs are frequently underestimated. It is largely the opposite of the iterative approach to software engineering.

Instead, they suggest a more incremental approach to system migration, relying heavily on deprecation. Incremental deprecation efforts accomplished by in-place refactoring can keep existing systems running while making it easier to deliver value to users. 💎

This won't be easy, as a complete deprecation process involves managing social and technical challenges through policy and tooling. You've got to make sure people are moving away from what they are used to, and such change is never easy. However, deprecating in an organized and well-managed fashion is often overlooked as a source of benefit to an organization, but is essential for its long-term sustainability.

Cost-benefit analysis

Going back to our assets and liabilities analogy, software systems have continuing maintenance costs that should be weighed against the cost of removing them. We should be contrasting the value of the assets that our code produces and the liabilities that it creates for us as often as possible. ⚖️

Some of the best modifications to a codebase are deletions. Getting rid of dead or obsolete code is one of the best ways to improve the overall health of the codebase. You probably know it deep down - it just feels great to remove code. 😌

But as with deprecation, removing things is often more difficult than building them to begin with. Your job here is to ensure the code you're about to remove is not used. That's hard. Finding out that a piece of code isn't used is always more expensive than finding that it is used, as you have to search the entire problem space. On top of that, existing users are often using the system beyond its original design. Discovering all of these implicit dependencies makes your job even trickier, so you've got to pay extra attention before hitting the delete button.

Conclusion

That's it for today. Maintaining complex software systems at scale requires effort but it is critical for keeping them running. Here's a short summary of things we went through:

• code itself doesn't bring value: it is the functionality that it provides that brings value

• migrating to entirely new systems is extremely expensive

• incremental deprecation with in-place refactoring can keep existing systems running while making it easier to deliver value to users

• some of the best modifications to a codebase are deletions, it is one of the best ways to improve the overall health of the codebase

• removing things is often more difficult than building them

Next, we will cover dependency management - the costs, and benefits associated with introducing dependencies, how to manage them the right way, and avoid the most common pitfalls. See you! 👋

If you liked the article or you have a question, feel free to reach out to me on Twitter‚ or add a comment below!

Further reading and references

• The original Twitter thread with notes from the book.

• Link to purchasing the book.

• Photo by NEOM on Unsplash.