DEV Community: Gavin Cettolo

You Don’t Need Microservices (Yet): A Reality Check for Devs

Gavin Cettolo — Tue, 26 May 2026 07:30:00 +0000

You Don't Need Microservices (Yet): A Reality Check for Devs

How Premature Architecture Decisions Slow Down Teams and Burn Engineering Budget

Every few months, I see the same conversation play out in engineering teams.

A new project kicks off. The team is excited. Someone opens the architecture discussion and says: "We should probably do microservices".

Nobody disagrees. Microservices are what serious companies do. Netflix does it. Amazon does it. Surely we should too.

Six months later, the team is spending more time debugging distributed systems, writing boilerplate for inter-service communication, and managing deployment pipelines than they are building features. Velocity is down. Morale is shaky. The MVP is late.

The architecture is impressive. The product is not shipped.

This article isn't anti-microservices. Microservices are the right answer, for some teams, at some stage, solving some problems. The goal here is to give you an honest framework for knowing whether you're at that stage, and what to do if you're not.

TL;DR

Microservices solve real problems, but only problems that come with scale. If you don't have those problems yet, you're paying the cost without getting the benefit.
A well-structured monolith is not a compromise. It's often the fastest, most maintainable architecture for teams under a certain size and complexity threshold.
There are concrete signals that tell you when it's time to split. Before those signals appear, premature decomposition is one of the most expensive architectural mistakes a team can make.

What Microservices Actually Solve
What a Well-Structured Monolith Looks Like
The Real Cost of Premature Decomposition
Monolith vs Microservices: A Concrete Comparison
Rules of Thumb: When to Actually Consider Splitting
The Decision Framework
When Microservices Are the Right Call
Final Thoughts

What Microservices Actually Solve

Before deciding whether you need microservices, it's worth being precise about what problem they were invented to solve.

Microservices emerged as an answer to a very specific set of pressures that appear at scale:

Independent deployability. When hundreds of developers are working on the same codebase, deploying a change to the checkout flow shouldn't require coordinating with the team working on the recommendation engine. Microservices let teams deploy independently.

Fault isolation. In a monolith, an unhandled exception in one part of the system can take down the entire application. In a microservices architecture, a failure in the notifications service doesn't affect the payment service.

Independent scalability. If your image processing service needs ten times the compute of your user auth service, a microservices architecture lets you scale them independently. In a monolith, you scale everything or nothing.

Technology heterogeneity. Different services can use different languages, runtimes, or databases if the problem demands it.

These are genuine, valuable properties.

The question is: do you have the problems these properties solve?

If you have five developers, one product, and a user base that hasn't hit its first scaling wall, the answer is almost certainly no.

What a Well-Structured Monolith Looks Like

"Monolith" has become a dirty word in engineering culture. It shouldn't be.

The alternative to microservices isn't a chaotic mess of spaghetti code. It's a modular monolith: a single deployable unit, internally organized around clearly separated domains.

Here's what that looks like for a simple e-commerce application:

src/
├── modules/
│   ├── orders/
│   │   ├── orders.controller.ts
│   │   ├── orders.service.ts
│   │   ├── orders.repository.ts
│   │   └── orders.types.ts
│   │
│   ├── products/
│   │   ├── products.controller.ts
│   │   ├── products.service.ts
│   │   ├── products.repository.ts
│   │   └── products.types.ts
│   │
│   ├── users/
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   ├── users.repository.ts
│   │   └── users.types.ts
│   │
│   └── payments/
│       ├── payments.controller.ts
│       ├── payments.service.ts
│       ├── payments.repository.ts
│       └── payments.types.ts
│
├── shared/
│   ├── database/
│   ├── middleware/
│   └── utils/
│
└── app.ts

Each module owns its domain. The orders module doesn't reach into the products database directly, it calls productService through a defined interface. The boundaries are logical, not physical.

// src/modules/orders/orders.service.ts

import { productService } from '@/modules/products/products.service'
import { paymentService } from '@/modules/payments/payments.service'
import { Order, CreateOrderPayload } from './orders.types'
import { ordersRepository } from './orders.repository'

export const ordersService = {
  async create(payload: CreateOrderPayload): Promise<Order> {
    // Validate product exists and has stock
    const product = await productService.getById(payload.productId)

    if (product.stock < payload.quantity) {
      throw new Error('Insufficient stock')
    }

    // Process payment
    const payment = await paymentService.charge({
      amount: product.price * payload.quantity,
      currency: 'EUR',
      customerId: payload.customerId,
    })

    // Create the order
    const order = await ordersRepository.create({
      ...payload,
      paymentId: payment.id,
      status: 'confirmed',
    })

    // Decrement stock
    await productService.decrementStock(payload.productId, payload.quantity)

    return order
  },
}

This is a direct function call. It's fast, it's simple, it's easy to trace in a debugger, and it's testable by mocking productService and paymentService.

No HTTP overhead. No serialization. No network failures to handle. No service discovery.

The same logic, across a microservices boundary, looks very different.

The Real Cost of Premature Decomposition

Before we look at the microservices version, let's be explicit about what you're taking on when you split prematurely.

Distributed systems complexity. Once your services communicate over a network, you have an entirely new class of problems: latency, partial failures, network timeouts, retry logic, idempotency. These aren't theoretical, they show up constantly in production, and they're significantly harder to debug than in-process errors.

Operational overhead. Each service needs its own CI/CD pipeline, its own deployment configuration, its own monitoring and alerting setup. For a two-person team, this is not a few hours of work, it's weeks, and it never really ends.

Development friction. Running the entire application locally now means running five (or fifteen) services simultaneously. Developer experience degrades. Onboarding new teammates takes longer.

Data consistency challenges. In a monolith, a database transaction either succeeds or fails atomically. Across services, you have to implement distributed transactions or accept eventual consistency, both of which add significant complexity to every operation that touches multiple domains.

The "wrong seams" problem. Domain boundaries that seem obvious on day one are often wrong by month six. In a monolith, reorganizing a module is a refactoring task. In a microservices architecture, it's a cross-service migration, which means coordination between teams, versioned APIs, and backward compatibility concerns.

Martin Fowler, one of the most authoritative voices on this topic, coined the term "distributed monolith" for what often happens when teams split prematurely: you get all the operational complexity of microservices, with none of the benefits, because the services are still tightly coupled through synchronous calls and shared data.

Monolith vs Microservices: A Concrete Comparison

Let's make this tangible. Same feature, creating an order in our e-commerce app, implemented both ways.

In the modular monolith

We already saw this above. The ordersService calls productService and paymentService directly. The entire operation is one function call, one database transaction, and one stack trace if something goes wrong.

// Creating an order, one direct call
const order = await ordersService.create({
  productId: 'prod-123',
  quantity: 2,
  customerId: 'user-456',
})

If this fails, the error propagates synchronously. The stack trace tells you exactly where it failed. The database transaction ensures nothing is partially committed.

In a microservices architecture

The same operation now crosses three network boundaries:

// src/services/orders-service/src/orders.service.ts

import { ApiError } from '@/lib/errors'

export const ordersService = {
  async create(payload: CreateOrderPayload): Promise<Order> {
    // HTTP call to products-service
    const productRes = await fetch(
      `${PRODUCTS_SERVICE_URL}/products/${payload.productId}`
    )
    if (!productRes.ok) throw new ApiError(productRes.status, 'Product fetch failed')
    const product = await productRes.json()

    if (product.stock < payload.quantity) {
      throw new Error('Insufficient stock')
    }

    // HTTP call to payments-service
    const paymentRes = await fetch(`${PAYMENTS_SERVICE_URL}/payments`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        amount: product.price * payload.quantity,
        currency: 'EUR',
        customerId: payload.customerId,
      }),
    })
    if (!paymentRes.ok) throw new ApiError(paymentRes.status, 'Payment failed')
    const payment = await paymentRes.json()

    // Create the order locally
    const order = await ordersRepository.create({
      ...payload,
      paymentId: payment.id,
      status: 'confirmed',
    })

    // HTTP call back to products-service to update stock
    const stockRes = await fetch(
      `${PRODUCTS_SERVICE_URL}/products/${payload.productId}/stock`,
      {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ decrement: payload.quantity }),
      }
    )
    if (!stockRes.ok) throw new ApiError(stockRes.status, 'Stock update failed')

    return order
  },
}

Now ask yourself what happens if the payment succeeds but the stock update call fails.

The payment has been charged. The order has been created. But the stock hasn't been decremented. You now have an inconsistency in your data, and no database transaction to roll it back for you.

Solving this correctly requires implementing a saga pattern or distributed transaction, which is a substantial engineering investment, and a source of bugs that are notoriously difficult to reproduce and fix.

This is the complexity you're signing up for when you split before you need to.

Rules of Thumb: When to Actually Consider Splitting

There are real signals that indicate a team is approaching the point where microservices start making sense. Here are the ones that consistently hold up in practice.

The Conway's Law signal.
Your team is growing, and different groups of developers are consistently working on different parts of the system with little overlap. Conway's Law tells us that system architecture tends to mirror team communication structure, so if your team has naturally split into a "payments team" and a "catalog team", the architecture probably should too, eventually.

Rule of thumb: consider splitting when you have two or more teams that consistently own distinct domains and need to deploy independently.

The scaling bottleneck signal.
A specific part of your system needs to scale independently from the rest, and that difference is significant enough to justify the operational overhead. Your image processing pipeline needs fifty instances; your user auth service needs two.

Rule of thumb: consider splitting when you've identified a specific performance bottleneck that can't be solved by vertical scaling or database optimization.

The deployment coupling signal.
Deploying a change to one domain consistently requires coordinating with other teams or causes unrelated failures. The deploy process has become a source of organizational friction, not just technical friction.

Rule of thumb: consider splitting when deployment coupling is measurably slowing down multiple teams on a recurring basis, not as a one-off event.

The failure isolation signal.
A non-critical part of your system (notifications, recommendations, reporting) is causing outages in critical paths (checkout, auth). The blast radius of failures is unacceptably large.

Rule of thumb: consider splitting when a failure in a low-priority domain is regularly impacting high-priority ones, and the fix isn't a code change but an architecture change.

The team size signal.
A widely cited heuristic, often attributed to Werner Vogels at Amazon, is the two-pizza rule: if you can't feed the team working on a service with two pizzas, the service is too big. The inverse is also true: if your entire engineering org fits at one table, microservices are probably not your problem yet.

Rule of thumb: teams under ~8–10 engineers rarely have the operational capacity to manage a microservices architecture well. The overhead consumes the productivity gains.

The Decision Framework

Before making any architectural decision toward microservices, run through these questions honestly:

1. What specific problem are you solving?

Write it down in one sentence. If the answer is "we want to be like Netflix" or "microservices are best practice", that's not a problem, it's a preference. Come back when you have a concrete problem.

2. Have you felt the pain of the alternative?

The best time to split a monolith is when it's actively hurting you. Slow deploys, scaling bottlenecks, team coupling, these are real pain. Splitting to avoid hypothetical future pain usually creates real present pain.

3. Do you have the operational maturity?

Microservices require investment in infrastructure: container orchestration (Kubernetes), service discovery, distributed tracing, centralized logging, health checks, circuit breakers. If your team doesn't have experience running these, plan for months of setup before you see the first benefit.

4. Are your domain boundaries stable?

If you're still figuring out what your product is, your domain model is still changing. Splitting along boundaries that will shift in three months is worse than not splitting at all.

5. Can you start with a modular monolith first?

A modular monolith with clean internal boundaries is a microservices architecture waiting to be extracted. If you've built the modules correctly, the split is a deployment change, not a rewrite. Start there.

Monolith vs Microservices Decision Matrix

Signal	Not ready	Ready
Team size	< 8 engineers	Multiple teams, distinct domains
Deployment pain	Occasional friction	Consistent blocker across teams
Scaling needs	Not yet hit limits	Specific bottleneck identified
Operational maturity	No container orchestration	k8s/ECS, tracing, logging in place
Domain stability	Product still pivoting	Stable, well-understood boundaries

When Microservices Are the Right Call

To be completely clear: there are scenarios where microservices are the right architecture from early on.

When compliance requires hard data isolation. If regulations require that payment data is physically isolated from user data with separate access controls and audit logs, separate services may be a compliance requirement, not an architectural preference.

When parts of the system have radically different SLAs. If your real-time trading engine needs 99.999% uptime and your reporting dashboard can tolerate downtime, running them in the same process is a liability.

When you're integrating genuinely independent third-party systems. An event-driven architecture where a service wraps a third-party provider (a payment gateway, a shipping API) and exposes a clean internal interface is a legitimate use of service decomposition from day one.

When you're building a platform with external integrations. If your architecture will expose APIs to external developers and those APIs need to evolve independently, service boundaries help.

The pattern in all of these is the same: there's a concrete, specific constraint that the architecture is responding to. Not a preference. Not a pattern borrowed from a company with different problems at a different scale.

Final Thoughts

Architecture decisions have a compounding effect on team velocity, in both directions.

The right architecture at the right time makes everything else faster: onboarding, debugging, deploying, iterating. The wrong architecture at the wrong time turns every feature into an infrastructure problem.

Microservices are powerful. They're also expensive. The teams that get the most out of them are the ones who waited until they had the problems microservices solve, and who built clean internal boundaries in their monolith in the meantime.

If you're in the early stages of a product, the most valuable architectural investment you can make is usually not splitting your system apart. It's understanding your domain well enough that, when the time comes to split, you know exactly where to cut.

Start simple. Feel the pain. Split deliberately.

Where is your team on this spectrum right now?

Are you running a monolith that's starting to show its limits, or did you go microservices early and live to regret it, or not? Drop your experience in the comments. The architecture conversations in the comments section are always the most useful part of these articles.

If this was useful, a ❤️ or a 🦄 helps it reach more developers who are about to make this decision.
And if you want the next article in the series when it drops, hit follow.

API Calls Done Right: From Messy Fetch to Clean Data Layer

Gavin Cettolo — Tue, 19 May 2026 07:30:00 +0000

I've seen this file in almost every frontend project I've ever touched.

It's usually called api.js or utils.js or sometimes just helpers.ts.

It starts small. One function. Two functions.

Then, six months later, it's 800 lines long, nobody fully understands it, and everyone is afraid to change it.

It looks something like this:

// Somewhere in a React component, at 3pm on a sprint deadline
const res = await fetch(`/api/users/${id}`, {
  headers: { Authorization: `Bearer ${localStorage.getItem('token')}` }
})
const data = await res.json()
setUser(data)

No error handling. No type safety. Auth logic scattered across components. The token read inline from localStorage every single time.

It works, until it doesn't.

This article is about building something better. We'll start from that messy fetch call and work our way up to a clean, typed, maintainable data layer, step by step.

TL;DR

A raw fetch call inside a component is the beginning of a maintenance problem, not a solution.
A clean data layer separates concerns: one apiClient handles transport and auth, individual service modules handle domain logic.
TypeScript + structured error handling + automatic token refresh gives you a production-grade setup that scales without becoming a second job to maintain.

What We're Building (and Why)
Step 1: The apiClient - One Place for Transport Logic
Step 2: Typed Responses and Structured Error Handling
Step 3: Service Modules - Organizing by Domain
Step 4: Authentication - Bearer Tokens Done Right
Step 5: Automatic Token Refresh
Step 6: Connecting the Data Layer to React with TanStack Query
The Final Folder Structure
Final Thoughts

What We're Building (and Why)

Before writing any code, let's define what "clean data layer" actually means.

It's not a framework. It's not a library. It's a set of responsibilities, each living in the right place:

Responsibility	Where it lives
HTTP transport (headers, base URL, timeouts)	`apiClient`
Auth token management	`apiClient` + `tokenService`
Domain-specific calls (fetch user, update product)	Service modules
Server state, caching, loading/error UI state	TanStack Query
Business logic and rendering	React components

A React component that directly calls fetch is doing two jobs at once: fetching data and rendering UI. That coupling is the root cause of most of the problems we're trying to solve.

The goal is simple: each layer does one thing, and only one thing.

Step 1: The apiClient - One Place for Transport Logic

The first thing we need is a single, shared HTTP client. Every API call in the application goes through it. No exceptions.

This gives us one place to configure:

the base URL
default headers
timeout behavior
future interceptors

// src/lib/apiClient.ts

const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? 'https://api.example.com'
const DEFAULT_TIMEOUT_MS = 10_000

interface RequestOptions extends RequestInit {
  timeout?: number
}

async function request<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), timeout)

  const url = `${BASE_URL}${endpoint}`

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
      headers: {
        'Content-Type': 'application/json',
        ...fetchOptions.headers,
      },
    })

    if (!response.ok) {
      throw new ApiError(response.status, await response.text())
    }

    // Handle 204 No Content
    if (response.status === 204) {
      return undefined as T
    }

    return response.json() as Promise<T>
  } finally {
    clearTimeout(timeoutId)
  }
}

export const apiClient = {
  get: <T>(endpoint: string, options?: RequestOptions) =>
    request<T>(endpoint, { ...options, method: 'GET' }),

  post: <T>(endpoint: string, body: unknown, options?: RequestOptions) =>
    request<T>(endpoint, {
      ...options,
      method: 'POST',
      body: JSON.stringify(body),
    }),

  put: <T>(endpoint: string, body: unknown, options?: RequestOptions) =>
    request<T>(endpoint, {
      ...options,
      method: 'PUT',
      body: JSON.stringify(body),
    }),

  patch: <T>(endpoint: string, body: unknown, options?: RequestOptions) =>
    request<T>(endpoint, {
      ...options,
      method: 'PATCH',
      body: JSON.stringify(body),
    }),

  delete: <T>(endpoint: string, options?: RequestOptions) =>
    request<T>(endpoint, { ...options, method: 'DELETE' }),
}

A few things worth noting here:

The AbortController + timeout pattern ensures that hanging requests don't freeze the UI indefinitely. After DEFAULT_TIMEOUT_MS, the request is automatically cancelled.

The if (!response.ok) check is something the native fetch API does not do for you. A fetch call to an endpoint that returns 404 or 500 will not throw, it resolves successfully, with response.ok set to false. If you don't check this, you'll silently pass error responses to your state as if they were valid data.

The 204 No Content guard prevents response.json() from throwing on empty responses, which is a surprisingly common gotcha with DELETE endpoints.

Step 2: Typed Responses and Structured Error Handling

The apiClient above throws an ApiError. Let's define it.

// src/lib/errors.ts

export class ApiError extends Error {
  constructor(
    public readonly status: number,
    public readonly body: string,
    message?: string
  ) {
    super(message ?? `API error: ${status}`)
    this.name = 'ApiError'
  }

  get isUnauthorized(): boolean {
    return this.status === 401
  }

  get isForbidden(): boolean {
    return this.status === 403
  }

  get isNotFound(): boolean {
    return this.status === 404
  }

  get isServerError(): boolean {
    return this.status >= 500
  }
}

export class NetworkError extends Error {
  constructor(message = 'Network request failed') {
    super(message)
    this.name = 'NetworkError'
  }
}

Having a typed error class instead of a generic Error is what makes downstream error handling clean. In your components or TanStack Query callbacks, you can now write:

if (error instanceof ApiError && error.isUnauthorized) {
  // redirect to login
}

Instead of:

// ❌ What most codebases end up with
if (error.message.includes('401') || error.message.includes('Unauthorized')) {
  // fragile, brittle, and a maintenance nightmare
}

Step 3: Service Modules - Organizing by Domain

Now that we have a shared client and typed errors, we can build service modules on top of it.

A service module groups all API calls related to a single domain. One file per domain. No mixing.

// src/services/userService.ts

import { apiClient } from '@/lib/apiClient'

export interface User {
  id: string
  email: string
  firstName: string
  lastName: string
  role: 'admin' | 'user'
  createdAt: string
}

export interface UpdateUserPayload {
  firstName?: string
  lastName?: string
  email?: string
}

export interface PaginatedResponse<T> {
  data: T[]
  total: number
  page: number
  pageSize: number
}

export const userService = {
  getById: (id: string) =>
    apiClient.get<User>(`/users/${id}`),

  getAll: (page = 1, pageSize = 20) =>
    apiClient.get<PaginatedResponse<User>>(
      `/users?page=${page}&pageSize=${pageSize}`
    ),

  update: (id: string, payload: UpdateUserPayload) =>
    apiClient.patch<User>(`/users/${id}`, payload),

  delete: (id: string) =>
    apiClient.delete<void>(`/users/${id}`),
}

// src/services/productService.ts

import { apiClient } from '@/lib/apiClient'

export interface Product {
  id: string
  name: string
  price: number
  stock: number
  categoryId: string
}

export interface CreateProductPayload {
  name: string
  price: number
  stock: number
  categoryId: string
}

export const productService = {
  getById: (id: string) =>
    apiClient.get<Product>(`/products/${id}`),

  create: (payload: CreateProductPayload) =>
    apiClient.post<Product>('/products', payload),

  updateStock: (id: string, stock: number) =>
    apiClient.patch<Product>(`/products/${id}`, { stock }),
}

This pattern scales cleanly. When a new developer joins and needs to find where user-related API calls live, the answer is always the same: src/services/userService.ts.

No archaeology. No searching for fetch('/api/users' across twelve components.

Step 4: Authentication - Bearer Tokens Done Right

Right now, the apiClient doesn't know anything about authentication. Let's fix that.

The wrong way to handle this is what we saw at the start: reading localStorage.getItem('token') inline inside every component. The token management logic is scattered, untestable, and fragile.

The right way is a dedicated tokenService that the apiClient calls when it needs to attach credentials.

// src/lib/tokenService.ts

const ACCESS_TOKEN_KEY = 'access_token'
const REFRESH_TOKEN_KEY = 'refresh_token'

export const tokenService = {
  getAccessToken: (): string | null =>
    localStorage.getItem(ACCESS_TOKEN_KEY),

  getRefreshToken: (): string | null =>
    localStorage.getItem(REFRESH_TOKEN_KEY),

  setTokens: (accessToken: string, refreshToken: string): void => {
    localStorage.setItem(ACCESS_TOKEN_KEY, accessToken)
    localStorage.setItem(REFRESH_TOKEN_KEY, refreshToken)
  },

  clearTokens: (): void => {
    localStorage.removeItem(ACCESS_TOKEN_KEY)
    localStorage.removeItem(REFRESH_TOKEN_KEY)
  },

  hasValidToken: (): boolean =>
    tokenService.getAccessToken() !== null,
}

Now we update apiClient to attach the token automatically:

// src/lib/apiClient.ts - updated request function

async function request<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), timeout)

  // Attach auth header automatically if token exists
  const accessToken = tokenService.getAccessToken()
  const authHeader = accessToken
    ? { Authorization: `Bearer ${accessToken}` }
    : {}

  const url = `${BASE_URL}${endpoint}`

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
      headers: {
        'Content-Type': 'application/json',
        ...authHeader,           // injected here - not in components
        ...fetchOptions.headers, // allow per-request overrides
      },
    })

    if (!response.ok) {
      throw new ApiError(response.status, await response.text())
    }

    if (response.status === 204) {
      return undefined as T
    }

    return response.json() as Promise<T>
  } finally {
    clearTimeout(timeoutId)
  }
}

Now every call made through apiClient automatically includes the auth header. Components don't know that auth exists. They just call userService.getById(id) and get back a typed User.

Step 5: Automatic Token Refresh

The Bearer token setup works - but in production, access tokens expire. Usually after 15–60 minutes.

Without automatic refresh, the user gets a 401 error and is silently logged out, even though their session is still valid. That's a frustrating experience and it's entirely avoidable.

The pattern is:

Request fails with 401.
Intercept the error before it reaches the component.
Use the refresh token to get a new access token.
Retry the original request with the new token.
If the refresh also fails, clear tokens and redirect to login.

// src/lib/apiClient.ts - with refresh logic

let isRefreshing = false
let pendingRequests: Array<(token: string) => void> = []

async function refreshAccessToken(): Promise<string> {
  const refreshToken = tokenService.getRefreshToken()

  if (!refreshToken) {
    throw new Error('No refresh token available')
  }

  // Note: this call bypasses the main request() to avoid infinite loops
  const response = await fetch(`${BASE_URL}/auth/refresh`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refreshToken }),
  })

  if (!response.ok) {
    throw new ApiError(response.status, await response.text())
  }

  const { accessToken, refreshToken: newRefreshToken } = await response.json()
  tokenService.setTokens(accessToken, newRefreshToken)

  return accessToken
}

async function request<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), timeout)

  const accessToken = tokenService.getAccessToken()
  const authHeader = accessToken
    ? { Authorization: `Bearer ${accessToken}` }
    : {}

  const url = `${BASE_URL}${endpoint}`

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
      headers: {
        'Content-Type': 'application/json',
        ...authHeader,
        ...fetchOptions.headers,
      },
    })

    // Token expired - attempt refresh
    if (response.status === 401 && tokenService.getRefreshToken()) {
      // If a refresh is already in flight, queue this request
      if (isRefreshing) {
        return new Promise<T>((resolve, reject) => {
          pendingRequests.push((newToken: string) => {
            fetchOptions.headers = {
              ...fetchOptions.headers,
              Authorization: `Bearer ${newToken}`,
            }
            request<T>(endpoint, options).then(resolve).catch(reject)
          })
        })
      }

      isRefreshing = true

      try {
        const newToken = await refreshAccessToken()

        // Flush queued requests with the new token
        pendingRequests.forEach(callback => callback(newToken))
        pendingRequests = []

        // Retry the original request
        return request<T>(endpoint, options)
      } catch {
        // Refresh failed - session is truly expired
        tokenService.clearTokens()
        pendingRequests = []
        window.location.href = '/login'
        throw new Error('Session expired')
      } finally {
        isRefreshing = false
      }
    }

    if (!response.ok) {
      throw new ApiError(response.status, await response.text())
    }

    if (response.status === 204) {
      return undefined as T
    }

    return response.json() as Promise<T>
  } finally {
    clearTimeout(timeoutId)
  }
}

The isRefreshing flag and pendingRequests queue are important. Without them, if five requests fire simultaneously and all get a 401, you'd fire five parallel refresh calls - a race condition that corrupts your token storage. With the queue, only one refresh happens, and all pending requests retry with the new token once it's available.

Step 6: Connecting the Data Layer to React with TanStack Query

The data layer we've built is framework-agnostic. It's just TypeScript functions. You can use it anywhere.

But in a React app, you'll want to connect it to your component state in a structured way. That's where TanStack Query comes in - and it pairs with this data layer perfectly.

// src/hooks/useUser.ts

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { userService, UpdateUserPayload } from '@/services/userService'

export function useUser(userId: string) {
  return useQuery({
    queryKey: ['users', userId],
    queryFn: () => userService.getById(userId),
    staleTime: 1000 * 60 * 5, // 5 minutes
  })
}

export function useUsers(page: number, pageSize: number) {
  return useQuery({
    queryKey: ['users', { page, pageSize }],
    queryFn: () => userService.getAll(page, pageSize),
    placeholderData: previousData => previousData, // smooth pagination
  })
}

export function useUpdateUser(userId: string) {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (payload: UpdateUserPayload) =>
      userService.update(userId, payload),
    onSuccess: updatedUser => {
      // Update the cached user immediately - no refetch needed
      queryClient.setQueryData(['users', userId], updatedUser)
    },
  })
}

And in the component, it's now completely clean:

// src/components/UserProfile.tsx

import { useUser, useUpdateUser } from '@/hooks/useUser'
import { ApiError } from '@/lib/errors'

interface Props {
  userId: string
}

export function UserProfile({ userId }: Props) {
  const { data: user, isLoading, error } = useUser(userId)
  const { mutate: updateUser, isPending } = useUpdateUser(userId)

  if (isLoading) return <Spinner />

  if (error) {
    if (error instanceof ApiError && error.isNotFound) {
      return <p>User not found.</p>
    }
    return <p>Something went wrong. Please try again.</p>
  }

  if (!user) return null

  const fullName = `${user.firstName} ${user.lastName}`

  return (
    <div>
      <h1>{fullName}</h1>
      <p>{user.email}</p>
      <button
        onClick={() => updateUser({ firstName: 'Updated' })}
        disabled={isPending}
      >
        Update
      </button>
    </div>
  )
}

The component knows nothing about:

how HTTP requests are made
where tokens come from
how errors are structured at the network level
what happens on a 401

It just asks for data and renders it. That's the goal.

If you want to go deeper on TanStack Query and why the queryKey matters, I covered it in detail in Stop Using useEffect Like This.

TanStack Query

Powerful asynchronous state management, server-state utilities and data fetching. Fetch, cache, update, and wrangle all forms of async data in your TS/JS, React, Vue, Solid, Svelte, Angular & Lit applications all without touching any "global state"

tanstack.com

The Final Folder Structure

After all six steps, here's what the data layer looks like on disk:

src/
├── lib/
│   ├── apiClient.ts       # HTTP transport, auth headers, token refresh
│   ├── tokenService.ts    # Token read/write/clear
│   └── errors.ts          # ApiError, NetworkError
│
├── services/
│   ├── userService.ts     # All user-related API calls + types
│   ├── productService.ts  # All product-related API calls + types
│   └── authService.ts     # Login, logout, register
│
└── hooks/
    ├── useUser.ts         # TanStack Query hooks for user data
    └── useProducts.ts     # TanStack Query hooks for product data

Three layers, three responsibilities:

lib/ - infrastructure. Doesn't know about your business domain.
services/ - domain. Knows about users, products, orders. Doesn't know about React.
hooks/ - React integration. Bridges the service layer with component state.

A component that needs user data goes through hooks/. A non-React module (a utility, a test) can call services/ directly. Nothing ever touches lib/ directly except services/.

Final Thoughts

We started with a fetch call inside a component, reading a token from localStorage inline.

We ended with a layered system where:

HTTP logic lives in one place
Auth is automatic and transparent
Every API call is typed
Token refresh happens without the user noticing
React components have no idea how any of this works

None of these steps are complicated individually. The value comes from doing all of them, and doing them in order.

You don't have to build this in one day. Start with the apiClient and the service modules. Add auth when you need it. Add token refresh when access tokens start expiring. Add TanStack Query when you need caching.

Each step is independently useful. The full stack is production-grade.

This article is part of the **Modern Frontend* series.*
If you missed the first article: Stop Using useEffect Like This - 5 Patterns That Break Your React App.

What does your current API layer look like?

Are you still writing fetch calls directly in components, or have you already built something like this? Drop your setup in the comments - I'm curious how different teams solve this problem.

If this was useful, a ❤️ or a 🦄 means a lot.
And if you want the next article in the series when it drops, hit follow.

The Hidden Cost of "It Works": Why Quick Fixes Kill Long-Term Speed

Gavin Cettolo — Tue, 12 May 2026 07:30:00 +0000

It was a Thursday afternoon when the Teams message came in.

A bug in production. A date formatting issue causing checkout to fail for users in certain timezones. Small bug, real impact: the payment flow was broken for roughly 8% of users.

The fix took twelve minutes. A single condition, a timezone offset, a hotfix deploy.

Everyone was relieved. The PM sent a thumbs up emoji. The on-call engineer closed the ticket.

Six months later, that same timezone logic had been copy-pasted into four other places across the codebase. Each with its own slight variation. Each slightly wrong in a different way.

The bug that took twelve minutes to "fix" ended up costing the team three days of a proper refactor, plus two additional incidents in the meantime.

That's the hidden cost of "it works."

TL;DR

Quick fixes feel like speed. They are actually deferred cost and the interest rate is brutal.
The damage is dual: it hits the codebase (fragility, duplication, entropy) and the team (decision fatigue, false confidence, loss of standards).
The solution isn't to never move fast. It's to develop a decision framework that tells you when a quick fix is acceptable and when it will cost you ten times its weight.

The Anatomy of a Quick Fix
The Two Places Quick Fixes Do Damage
The Broken Windows Effect in Codebases
Why "It Works" Is the Most Dangerous Phrase in Engineering
The Hidden Cost, Quantified
The Quick Fix Decision Framework
When Quick Fixes Are Actually the Right Call
Building a Culture That Pays Debt on Schedule
Final Thoughts

The Anatomy of a Quick Fix

Not all quick fixes are created equal.

Some are intentional trade-offs: "we know this isn't the right solution, we're doing it to ship, and we'll revisit it next sprint."

Others are accidental: "this solves the immediate problem, let's move on", with no intention of revisiting.

And then there's the most dangerous kind: the ones that start as intentional and silently become permanent.

Ward Cunningham, the person who coined the term "technical debt" in 1992, described debt as something you take on deliberately, with a plan to pay it back. The problem isn't the debt itself. The problem is when the plan to repay it disappears.

// "Temporary" quick fix. Added: March 2023.
// TODO: replace with proper timezone utility
const offset = user.country === 'IT' ? 2 : 0
const adjustedDate = new Date(date.getTime() + offset * 3600000)

If you've worked in any codebase for more than a year, you've seen comments like this. The TODO is still there. The "temporary" fix shipped two years ago.

The Two Places Quick Fixes Do Damage

Quick fixes are often discussed as a purely technical problem.

But the damage happens in two places, and only one of them shows up in your code.

In the codebase

This is the visible damage. Over time, quick fixes create:

Duplication without intention: logic that should live in one place spreads across multiple files, each with slight variations.
Fragile dependencies: workarounds that assume things about the system that aren't guaranteed to stay true.
Entropy: the codebase slowly drifts from its original architecture. Modules that were designed to do one thing start doing three.

You've already seen this pattern described in Bad Code Is a High-Interest Loan: each shortcut adds interest that compounds over time.

Quick fixes are where most of that interest originates.

In the team

This is the invisible damage and it's often more costly.

Decision fatigue. Every quick fix that goes unaddressed adds a micro-decision to every future change: "should I work around this, or fix it properly?" Over time, this is exhausting.

False confidence. "It works" becomes the team's de facto quality standard. The bar for "acceptable" slowly lowers. Nobody notices because the shift is gradual.

Loss of standards. When quick fixes stop being exceptions and start being the norm, new team members learn that the norm is acceptable. Standards don't erode from the top down, they erode from repeated practice.

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."

Martin Fowler, Refactoring

The hidden cost of quick fixes isn't just the code they leave behind. It's the culture they quietly teach.

The Broken Windows Effect in Codebases

In 1982, criminologists James Q. Wilson and George Kelling proposed the Broken Windows Theory: a broken window left unrepaired signals that no one cares, which invites more disorder. One broken window becomes ten.

The same dynamic plays out in codebases.

One unaddressed quick fix signals to everyone else that this kind of code is acceptable here.

Another quick fix lands nearby. Then another.

Nobody makes a deliberate choice to lower standards. But collectively, the team's behavior changes in response to what they see around them.

Robert C. Martin and colleagues described it in The Pragmatic Programmer:

"Don't leave broken windows (bad designs, wrong decisions, or poor code) unrepaired. Fix each one as soon as it is discovered."

This doesn't mean stop everything and refactor whenever you spot a problem. It means that leaving problems unaddressed always has a cost, even if that cost is invisible today.

Why "It Works" Is the Most Dangerous Phrase in Engineering

"It works" is a binary measurement.

It either works or it doesn't.

But software quality isn't binary. It exists on a spectrum, and "it works" tells you almost nothing about where on that spectrum your code actually lives.

A function can "work" and still be:

impossible to understand without context
brittle in edge cases nobody has hit yet
completely untestable in isolation
a ticking clock for the next developer who needs to modify it

The problem with "it works" as a standard is that it optimizes for the present and ignores the future. Every codebase "works", right up until it doesn't.

// This "works"
function getPrice(p: any, d: any, t: any) {
  return p - (p * d) + (p * t)
}

// This also works and tells you what it actually does
function calculateCheckoutPrice(
  basePrice: number,
  discountRate: number,
  taxRate: number
): number {
  const discountedPrice = basePrice * (1 - discountRate)
  const finalPrice = discountedPrice * (1 + taxRate)
  return finalPrice
}

Both functions return the same number. Only one communicates intent. Only one is safe to modify six months from now by someone who wasn't there when it was written.

"It works" describes behavior. What you actually need is behavior plus clarity plus maintainability.

The Hidden Cost, Quantified

Let's make this concrete, because abstract arguments about code quality are easy to dismiss in a sprint planning meeting.

Here's a rough model of what quick fixes actually cost over time:

The 1-3-10 rule (based on the well-documented cost-of-change curve in software engineering):

When the fix is made	Relative cost
During development (before merge)	1x
After merge, in the same sprint	3x
Weeks/months later, in production	10x or more

Every quick fix that lands in production without a remediation plan starts at 10x cost, minimum.

Now add compounding.

If that quick fix becomes the foundation for a new feature, the new feature inherits all of its fragility. Every subsequent change that depends on it pays interest too.

The timezone example from the opening of this article illustrates this precisely:

12 minutes to apply the quick fix.
2 incidents caused by copy-pasted variations of the same logic.
3 days to trace, consolidate, and properly fix all four instances.

That's roughly a 36x multiplier on the original time investment, not counting the user impact and the on-call stress.

The Quick Fix Decision Framework

Here's the tool I wish I'd had earlier: a simple framework for deciding whether a quick fix is acceptable, or whether you're about to create a future problem.

Before merging any quick fix, run through these four questions:

1. Is it documented?

A quick fix without a paper trail becomes permanent by default.

At minimum, leave a comment with:

the date
why this was chosen over a proper solution
a link to the ticket for the future refactor

// QUICK FIX - 2025-06-12
// Using a hardcoded offset to unblock the checkout bug (INC-4421).
// Proper fix: centralize timezone handling in a utility module.
// Tracked in: https://linear.app/yourteam/issue/ENG-889
const offset = user.country === 'IT' ? 2 : 0

This comment costs you thirty seconds. It saves the next developer thirty minutes of archaeology.

2. Is it isolated?

A quick fix that touches a core abstraction is fundamentally different from one that lives in a leaf node of your architecture.

Ask yourself: "if this assumption turns out to be wrong, how many places break?"

If the answer is more than one: it's not a quick fix, it's a risk.

3. Does it have a scheduled remediation?

A quick fix without a ticket is just a bug you haven't found yet.

Create the ticket. Assign it. Don't let the sprint end without it existing in your backlog.

The fix doesn't have to be immediate. It has to be visible.

4. Does the team know about it?

Quick fixes made in isolation, under deadline pressure, on a Friday, without review, are the ones that become permanent.

A fifteen-second mention in standup ("I shipped a workaround for X, ticket ENG-889 tracks the proper fix") changes the dynamic completely. It creates shared accountability.

The decision matrix

Use this as a quick gut-check:

Condition	Acceptable quick fix?
Documented + ticket exists	Yes, if isolated
Undocumented, no ticket	No
Touches a core abstraction	No
Isolated + low blast radius	Yes, with documentation
"We'll fix it eventually" (no date)	No
Team is aware + remediation is scheduled	Yes

When Quick Fixes Are Actually the Right Call

This wouldn't be an honest article without acknowledging that quick fixes are sometimes the right decision.

There are moments where speed genuinely matters more than perfection:

Production incidents. When a bug is actively impacting users and revenue, stopping to architect the perfect solution is the wrong call. Ship the fix. Create the ticket. Come back.

Validated uncertainty. If you're building a feature you're not sure the product will keep, over-engineering it is waste. A deliberate quick fix on an experimental feature is good product thinking.

Clear blast radius. If the workaround is contained, isolated, and fully documented, the risk is manageable. Not every quick fix becomes a monster. Some stay small.

The difference between these and the dangerous kind isn't the code itself. It's whether you're making a conscious trade-off with a plan or an unconscious shortcut with denial.

As Kent Beck put it:

"Make it work, make it right, make it fast."

The problem isn't "make it work", that's always step one. The problem is treating step one as the finish line.

Building a Culture That Pays Debt on Schedule

Individual decisions matter. But so does the environment in which they're made.

If your team is consistently reaching for quick fixes, the problem usually isn't the developers. It's the system they operate in.

A few structural changes that make a measurable difference:

Allocate explicit time for debt reduction.
The teams that manage technical debt best treat it like any other work: they schedule it. A common approach is dedicating 15–20% of every sprint to debt reduction. Not "if we have time." Scheduled.

Make quick fixes visible in your backlog.
Every quick fix should produce a ticket. The backlog is the team's shared memory. If a workaround isn't in the backlog, it doesn't exist as far as future planning is concerned and it will never get fixed.

Normalize "good enough for now, better by [date]".
The goal isn't to eliminate quick fixes. It's to make them explicit. When a developer says "this is a quick fix, the proper solution is tracked in ENG-889, and we've agreed to address it in the next sprint", that's a healthy team.

Review quick fixes in retros.
Not to blame anyone. To learn. Which quick fixes turned into real problems? Which ones stayed contained? What made the difference? Patterns will emerge.

This connects directly to what we explored in Corporate Amnesia: teams don't lose knowledge in dramatic moments. They lose it in accumulation, one undocumented workaround at a time.

Final Thoughts

"It works" will always be a seductive phrase.

Especially at 5 PM on a Friday with a deadline looming.

But after years of working in codebases shaped by the accumulated weight of "it works," I've come to think of it differently.

"It works" isn't a finish line. It's a starting point.

The real question that comes after it is: "and will it still be safe to touch in six months, by someone who wasn't here when we wrote it?"

Every quick fix that answers "I don't know" to that question is a bet. Sometimes the bet pays off. Often it doesn't. And when it doesn't, you don't lose the twelve minutes it took to write, you lose the three days it takes to untangle.

Speed and quality are not opposites. The teams that move fastest over time are not the ones that cut the most corners. They're the ones that cut corners deliberately, visibly, and with a plan to fix them.

That's not perfectionism. That's how you protect your velocity.

What's the most expensive "it works" you've ever shipped?

Drop it in the comments, the more specific, the better. I'll start: mine was a hardcoded locale string that somehow ended up in twelve files before anyone noticed.

If this resonated, a ❤️ or a 🦄 helps more people find it.

And if you want to follow the series, hit follow, the next article is already in the works.

Stop Using useEffect Like This: 5 Patterns That Are Silently Breaking Your React App

Gavin Cettolo — Tue, 05 May 2026 07:30:00 +0000

I was doing a code review for a colleague when I found it.

The component had five useEffect hooks.

No errors. No warnings in the console. The PM had signed off on it. It had been in production for three months.

But there was a subtle bug that only showed up when the user navigated quickly between pages.

Data would flash. State would reset. Sometimes the old user's name would appear for a split second before updating to the new one.

Three hours later, we traced it back to a single misused useEffect.

That's the thing about this hook: it fails silently, in slow motion, and always at the worst moment.

TL;DR

useEffect is the most misused hook in React and most bugs that seem "mysterious" trace back to it.
Five specific patterns are responsible for 90% of the problems: derived state, overloaded effects, stale closures, unstructured fetches, and unnecessary usage.
React 18's Strict Mode adds a layer of complexity that catches many of these bugs in development, if you know what to look for.

Why useEffect Is Deceptively Hard
Pattern 1: Deriving State Inside useEffect
Pattern 2: Overloading a Single useEffect
Pattern 3: Missing or Suppressed Dependencies
Pattern 4: Fetching Data Without Structure
Pattern 5: Using useEffect When You Simply Don't Need It
Bonus: React 18, Strict Mode, and the Double-Mount Trap
Before vs After: A Real Refactoring
A Better Mental Model
Final Thoughts

Why useEffect Is Deceptively Hard

At first glance, useEffect looks simple:

useEffect(() => {
  // do something
}, [])

It feels like: "run this code when something happens."

But the React docs describe it very differently:

useEffect is a hook that lets you synchronize a component with an external system.

That word, synchronize, changes everything.

It's not a lifecycle replacement. It's not an event handler. It's a way to keep your UI in sync with something outside of React.

The moment you treat it as a general-purpose utility, you open the door to every problem we're about to look at.

Pattern 1: Deriving State Inside useEffect

This is the most common mistake, and the one I see even in senior developers' code.

// ❌ Don't do this
const [fullName, setFullName] = useState<string>('')

useEffect(() => {
  setFullName(`${firstName} ${lastName}`)
}, [firstName, lastName])

This looks harmless. It even feels clean.

But here's what actually happens under the hood:

Component renders with firstName and lastName.
React runs the effect after the render.
setFullName triggers another render.
The user briefly sees an empty or stale fullName. You've just added an extra render cycle for no reason.

The fix

// ✅ Compute it during render
const fullName = `${firstName} ${lastName}`

That's it. No state. No effect. No extra render. No stale flash.

Rule of thumb: If you can compute a value from existing props or state, never put it in useState. Compute it inline.

The React docs even have a whole section on this called "You might not need an effect", worth bookmarking.

Pattern 2: Overloading a Single useEffect

This one grows gradually. It starts innocent:

// ❌ Three completely unrelated things in one effect
useEffect(() => {
  fetchUser(userId)
  setupWebSocketSubscription()
  document.title = `Dashboard - ${appName}`
}, [userId, appName])

Now imagine this in two months, after three more developers have touched it.

The problem isn't just readability. It's coupling.

If fetchUser starts causing issues, you need to reason about the subscription and the document title at the same time.

If appName changes, your effect re-runs, which means you're also re-fetching the user and re-subscribing unnecessarily.

The fix

One effect, one responsibility:

// ✅ Each effect has a single, clear purpose
useEffect(() => {
  fetchUser(userId)
}, [userId])

useEffect(() => {
  const unsubscribe = setupWebSocketSubscription()
  return () => unsubscribe()
}, [])

useEffect(() => {
  document.title = `Dashboard - ${appName}`
}, [appName])

Notice the cleanup function in the second effect, that's the bonus you get when you split effects: cleanups become obvious and natural.

Pattern 3: Missing or Suppressed Dependencies

We've all done this at least once.

// ❌ The eslint-disable comment is a red flag, not a solution
useEffect(() => {
  processOrder(orderId, userPreferences)
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, [])

The eslint-disable comment is almost always a sign that something in the design needs to change, not that the linter is wrong.

Here's the subtle bug this creates:

// What the developer thinks:
// "This runs once on mount, using the current orderId."

// What actually happens:
// "This captures orderId at mount time and never updates,
//  even if orderId changes while the component is still mounted."

This is called a stale closure. The effect "remembers" the old value of orderId forever.

The fix

// ✅ Be explicit about what the effect depends on
useEffect(() => {
  processOrder(orderId, userPreferences)
}, [orderId, userPreferences])

If adding the dependency causes unwanted re-runs, the real fix is usually one of these:

Move the value outside the component (if it's static).
Use useCallback or useMemo to stabilize the reference.
Reconsider whether the effect is the right tool for the job. Never silence the linter. Fix the design.

Pattern 4: Fetching Data Without Structure

This is the one everyone starts with:

// ❌ Simple, but missing critical pieces
useEffect(() => {
  fetch(`/api/users/${userId}`)
    .then(res => res.json())
    .then(setUser)
}, [userId])

What's wrong with it? Let me count:

No loading state: the UI hangs silently.
No error handling: if the request fails, nothing happens.
No cancellation: if userId changes before the request completes, you get a race condition.
Not reusable: you'll copy-paste this into ten components. The race condition is the nastiest one. Here's what it looks like:

// ❌ Race condition scenario
// 1. userId changes to "user-2"
// 2. Effect runs, starts fetching "user-2"
// 3. userId changes again to "user-3"
// 4. Effect runs, starts fetching "user-3"
// 5. "user-3" response arrives first
// 6. "user-2" response arrives and overwrites "user-3" data
// 7. You're now showing the wrong user's data

The fix: a custom hook

At minimum, extract the logic and handle cancellation:

// ✅ Custom hook with loading, error, and cleanup
function useUser(userId: string) {
  const [user, setUser] = useState<User | null>(null)
  const [isLoading, setIsLoading] = useState(true)
  const [error, setError] = useState<Error | null>(null)

  useEffect(() => {
    let cancelled = false
    setIsLoading(true)

    fetch(`/api/users/${userId}`)
      .then(res => {
        if (!res.ok) throw new Error('Failed to fetch user')
        return res.json()
      })
      .then(data => {
        if (!cancelled) setUser(data)
      })
      .catch(err => {
        if (!cancelled) setError(err)
      })
      .finally(() => {
        if (!cancelled) setIsLoading(false)
      })

    return () => {
      cancelled = true
    }
  }, [userId])

  return { user, isLoading, error }
}

The cancelled flag is the key: it prevents state updates after the component has moved on.

The fix: use a library (recommended)

For production apps, don't reinvent the wheel. Libraries like TanStack Query (formerly React Query) handle all of this for you, caching, deduplication, background refetching, race conditions, and more.

// ✅ TanStack Query: this replaces ~30 lines of manual code
import { useQuery } from '@tanstack/react-query'

function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
  })

  if (isLoading) return <Spinner />
  if (error) return <ErrorMessage error={error} />

  return <div>{user.fullName}</div>
}

If you're not using TanStack Query yet, it's one of the highest-value libraries you can add to a React project.

TanStack Query

Powerful asynchronous state management, server-state utilities and data fetching. Fetch, cache, update, and wrangle all forms of async data in your TS/JS, React, Vue, Solid, Svelte & Angular applications all without touching any "global state"

tanstack.com

Pattern 5: Using useEffect When You Simply Don't Need It

Sometimes useEffect gets used just because it's the only tool that feels right:

// ❌ This isn't a side effect, it's just logic
useEffect(() => {
  if (items.length === 0) {
    setIsEmpty(true)
  } else {
    setIsEmpty(false)
  }
}, [items])

Or even:

// ❌ This belongs in an event handler, not an effect
useEffect(() => {
  if (formSubmitted) {
    validateAndSave()
  }
}, [formSubmitted])

The second one is a particularly sneaky antipattern. If you're reacting to a user action (a button click, a form submit), use an event handler. Effects are for syncing with external systems, not for responding to user interactions.

The fix

// ✅ Derived value, not state
const isEmpty = items.length === 0

// ✅ Event handler for user interactions
function handleSubmit() {
  setFormSubmitted(true)
  validateAndSave()
}

Ask yourself before writing any useEffect:
"What external system am I syncing with?"

If the answer is "nothing, I'm just reacting to some state", you don't need an effect.

Bonus: React 18, Strict Mode, and the Double-Mount Trap

This section trips up a lot of developers upgrading to React 18.

In development mode, React 18's Strict Mode intentionally mounts your components twice.

This is new. And it's by design.

React is preparing for a future feature (concurrent rendering and resumable state) where components may be mounted, unmounted, and remounted without losing state. To catch bugs early, Strict Mode simulates this in development.

Here's what happens:

Component mounts   → Effect runs
Component unmounts → Cleanup runs
Component mounts   → Effect runs again  ← This is new in React 18

If your effects are written correctly (with proper cleanup), you'll never notice this. If they're not, you'll see strange behaviors:

// ❌ This effect causes a double API call in Strict Mode
useEffect(() => {
  fetch('/api/init')
    .then(res => res.json())
    .then(setData)
}, [])

In development with React 18 Strict Mode, this runs twice. In production, it runs once.

This confuses developers into thinking their code is broken. It's not broken, it's exposing that the code wasn't safe to run twice.

The fix

// ✅ With cleanup, the double-mount is harmless
useEffect(() => {
  let cancelled = false

  fetch('/api/init')
    .then(res => res.json())
    .then(data => {
      if (!cancelled) setData(data)
    })

  return () => {
    cancelled = true
  }
}, [])

Now the second mount runs the effect again, but the cleanup from the first run has already set cancelled = true, so the first fetch's result is ignored.

Key insight: If your effect breaks when it runs twice, it was always broken. Strict Mode is just making it visible.

Before vs After: A Real Refactoring

Let me show you how these patterns compound in a real component.

This is similar to what I found during that code review I mentioned at the start:

// ❌ Before: a component that "works" but has 4 different issues
interface Props {
  userId: string
}

function UserDashboard({ userId }: Props) {
  const [user, setUser] = useState<any>(null)
  const [fullName, setFullName] = useState<string>('')
  const [isAdmin, setIsAdmin] = useState<boolean>(false)

  // Issue 1: Derives state that could be computed inline
  // Issue 2: Mixes fetch logic with transformation
  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(data => {
        setUser(data)
        setFullName(`${data.firstName} ${data.lastName}`)
        setIsAdmin(data.role === 'admin')
      })
    // Issue 3: Missing userId dependency
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [])

  // Issue 4: Effect for something that isn't a side effect
  useEffect(() => {
    if (user) {
      console.log('User loaded:', user.id)
    }
  }, [user])

  return (
    <div>
      <h1>{fullName}</h1>
      {isAdmin && <AdminBadge />}
    </div>
  )
}

Problems:

fullName and isAdmin are derived state, extra renders for nothing.
The eslint-disable is hiding a stale closure bug.
The logging effect is just noise.

- No loading state, no error handling, no cleanup.

// ✅ After: clean, predictable, and reusable

interface User {
  id: string
  firstName: string
  lastName: string
  role: 'admin' | 'user'
}

// Data fetching logic extracted into a custom hook
function useUser(userId: string) {
  const [user, setUser] = useState<User | null>(null)
  const [isLoading, setIsLoading] = useState<boolean>(true)
  const [error, setError] = useState<Error | null>(null)

  useEffect(() => {
    let cancelled = false
    setIsLoading(true)

    fetch(`/api/users/${userId}`)
      .then(res => {
        if (!res.ok) throw new Error('Failed to fetch')
        return res.json() as Promise<User>
      })
      .then(data => {
        if (!cancelled) {
          setUser(data)
          setIsLoading(false)
        }
      })
      .catch(err => {
        if (!cancelled) {
          setError(err)
          setIsLoading(false)
        }
      })

    return () => { cancelled = true }
  }, [userId])

  return { user, isLoading, error }
}

// Component is now clean and purely presentational
function UserDashboard({ userId }: { userId: string }) {
  const { user, isLoading, error } = useUser(userId)

  if (isLoading) return <Spinner />
  if (error) return <p>Something went wrong.</p>
  if (!user) return null

  // Derived values computed inline, no state, no effects
  const fullName = `${user.firstName} ${user.lastName}`
  const isAdmin = user.role === 'admin'

  return (
    <div>
      <h1>{fullName}</h1>
      {isAdmin && <AdminBadge />}
    </div>
  )
}

What changed:

Zero derived state, fullName and isAdmin are computed inline.
One effect, one responsibility, and it's properly cleaned up.
No suppressed linter warnings.
Loading and error states handled explicitly.
The component is now easy to test, easy to read, and easy to modify. Same functionality. Dramatically different maintainability.

A Better Mental Model

Here's the shift that changes how you write React:

Old mental model: "When should this code run?"

New mental model: "What external system am I keeping in sync?"

External systems that useEffect is appropriate for:

APIs and data sources: fetching data from a server.
Browser APIs: document.title, localStorage, IntersectionObserver.
Third-party libraries: charts, maps, analytics SDKs that live outside React's tree.
Subscriptions: WebSockets, event listeners, timers. If none of these describe what you're doing, you probably don't need useEffect.

Before writing one, run through this quick checklist:

[ ] Can I compute this value during render instead?
[ ] Is this reacting to a user action? (Use an event handler.)
[ ] Is this effect doing more than one thing? (Split it.)
[ ] Do I have a cleanup function? (If not, why not?)
[ ] Would this break if it ran twice? (If yes, it was already broken.)

Final Thoughts

useEffect isn't bad.

It's one of the most powerful primitives React gives you.

But power without understanding leads to exactly the kind of silent, slow-burn bugs that show up three months after launch, on a Friday afternoon, right before a demo.

The goal isn't to use useEffect correctly.

The goal is to need it less.

Every unnecessary effect you remove is:

One fewer render cycle.
One fewer stale closure waiting to happen.
One fewer thing to explain to the next developer who reads your code. Write less. Compute more. Clean up always.

Which of these five patterns have you fallen into this week? Drop your story in the comments, the more specific, the better. I've shared mine. Now it's your turn.

If this was useful, a ❤️ or a 🦄 unicorn helps more people find it.

And if you want more of this kind of deep-dive into everyday React patterns, follow me here on DEV! I publish weekly.

The AI-Augmented Developer: How AI Is Changing the Way We Write Code

Gavin Cettolo — Tue, 28 Apr 2026 12:00:00 +0000

A few months ago, I found myself doing something I hadn’t done before.

Not Googling.
Not digging through old Stack Overflow threads.

I just… asked.

And got an answer in seconds.

Not always perfect.
Not always correct.

But good enough to move forward.

That’s when it clicked:

AI isn’t replacing how we write code.
It’s changing how we think while writing it.

TL;DR

AI works best as a copilot, not an autopilot.
It can speed up development, but also introduce subtle risks if used blindly.
The real advantage comes from integrating AI into a thoughtful workflow, not just using it occasionally.

From Searching to Asking
AI as a Copilot, Not an Autopilot
A Real Workflow: How Developers Actually Use AI
Where AI Shines
Where AI Struggles
The Hidden Risk: False Confidence
How to Use AI Without Losing Your Edge
Final Thoughts

From Searching to Asking

For years, our workflow looked like this:

write some code
hit a problem
search for answers
stitch together a solution Now, it’s different.

We:

describe the problem
get a tailored response
iterate faster

It’s a shift from searching to asking and that changes more than just speed: It changes how we explore problems.

AI as a Copilot, Not an Autopilot

There’s a temptation to treat AI as something that “just writes code for you”, but that’s not how it works well.

AI is strongest when:

you guide it
you question it
you refine its output

Think of it like a junior developer that:

is incredibly fast
knows a bit of everything
but doesn’t fully understand your context

You wouldn’t blindly trust that and you shouldn’t blindly trust AI either.

A Real Workflow: How Developers Actually Use AI

The real value of AI doesn’t come from one big prompt, it comes from how it fits into your daily workflow.

Here’s a realistic loop:

1. Start with your own idea

You sketch the solution.

Even if it’s incomplete.

This matters, because it keeps you in control.

2. Use AI to explore options

You ask:

“Is there a better way to structure this?”
“How can I simplify this logic?”

Now AI becomes a brainstorming partner.

3. Generate or refine code

You let AI:

draft functions
suggest refactors
fill repetitive gaps

But you don’t stop there.

4. Review like it wasn’t yours

This is the critical step:

You read the code as if someone else wrote it, because in a way, they did.

5. Integrate carefully

You adapt the output:

to your conventions
to your architecture
to your actual constraints

Only then it becomes part of your system.

Where AI Shines

Used correctly, AI can dramatically speed things up, especially for:

Repetitive tasks

Boilerplate.
Transformations.
Small utilities.

Things you already know how to do, but don’t want to rewrite.

Learning and exploration

You can quickly:

understand unfamiliar APIs
see example implementations
compare approaches

It reduces friction when learning something new.

Refactoring support

AI is surprisingly good at:

suggesting cleaner structures
identifying duplication
proposing improvements

It won’t always be perfect, but it often gives you a strong starting point.

Where AI Struggles

AI has limits and knowing them is what keeps you effective.

Context awareness

AI doesn’t fully understand:

your codebase
your domain
your business logic

It works with what you give it, nothing more.

Long-term design

Architecture decisions require:

trade-offs
constraints
experience

AI can suggest patterns, but it doesn’t own the consequences.

Subtle bugs

AI-generated code often looks correct, but small issues can hide inside:

edge cases
performance problems
incorrect assumptions

This is where experience matters.

The Hidden Risk: False Confidence

This is the part most people underestimate.
AI makes things look easy, and that creates a dangerous illusion:

“This looks right, so it must be right.”

But readable code is not necessarily correct code.
And fast progress is not necessarily real progress.

If you skip the thinking part, you’re not moving faster, you’re just deferring problems.

How to Use AI Without Losing Your Edge

AI should amplify your skills, not replace them.

A few simple rules help:

Stay the decision-maker

AI suggests.
You decide.
Always.

Ask the AI to ask you questions to clarify any unclear points.

Understand before you accept

If you can’t explain the code, don’t ship it.

Use it to learn, not just to produce

Ask “why” as often as you ask “how”.

Keep your fundamentals sharp

AI changes the workflow.

It doesn’t replace the need for:

problem solving
system thinking
debugging skills

Final Thoughts

AI is not the end of programming, it’s an evolution of it.
The best developers won’t be the ones who use AI the most, they’ll be the ones who use it well, because the real shift isn’t about writing less code.

It’s about thinking differently while writing it.

If this resonated with you:

Leave a ❤️ reaction
Drop a 🦄 unicorn
Share how AI has changed your workflow

And if you enjoy this kind of content, follow me here on DEV for more.

Corporate Amnesia: What Happens When Your Team Forgets How Its Own Code Works

Gavin Cettolo — Tue, 21 Apr 2026 07:30:00 +0000

A few months ago, we had to change a small piece of logic.

It sounded simple.
A minor tweak.
“Shouldn’t take more than a couple of hours.”

Then someone asked:

“Do we know how this actually works?”

Silence.

No one on the team had written that part.
The last person who touched it had left.
There was no documentation.
Tests were… optimistic.

What should have been a small change turned into a half-day investigation.

Not because the problem was hard.

Because the knowledge was gone.

TL;DR

Teams don’t just lose code quality over time, they lose understanding.
Documentation alone doesn’t solve it, readable and maintainable code does.
Preventing knowledge loss is a business problem, not just a technical one.

What Is Corporate Amnesia
How Knowledge Actually Gets Lost
The Real Cost (It’s Not Just Time)
Why Documentation Alone Doesn’t Save You
Code as the Single Source of Truth
A Real Example: “It Works, Don’t Touch It”
How to Build a Memory-Resilient Codebase
Knowledge Handover Checklist
Final Thoughts

What Is Corporate Amnesia

Corporate amnesia happens when a team loses the knowledge needed to confidently work on its own system.

It doesn’t happen all at once.

It’s gradual.

A developer leaves.
Another switches teams.
A feature is built quickly and never revisited.

Over time, fewer and fewer people understand how things actually work.

Eventually, you end up with a codebase that:

technically works
but no one fully understands

And that’s where things start slowing down.

How Knowledge Actually Gets Lost

It’s easy to blame turnover.

But that’s only part of the story.

Knowledge gets lost when:

decisions are not documented
code is hard to read or follow
logic is duplicated instead of centralized
context lives in people’s heads, not in the system

And most importantly:

👉 when teams optimize for delivery, but not for clarity

Shipping fast is important.

But if clarity doesn’t follow, knowledge decays.

The Real Cost (It’s Not Just Time)

At first, the cost looks like time.

tasks take longer
debugging becomes slower
onboarding is harder

But the real cost is deeper.

You start seeing:

hesitation to change existing code
over-engineering “just to be safe”
duplicated features instead of modifying existing ones

And eventually:

👉 the team stops trusting the codebase

That’s when velocity drops.

Not because developers are slower.

But because the system is harder to work with.

Why Documentation Alone Doesn’t Save You

The instinctive solution is:

“We need better documentation.”

And yes, documentation helps.

But it has a problem.

It gets outdated.

Fast.

Code evolves.
Docs don’t always keep up.

And after a while, you’re not sure which one to trust.

Code as the Single Source of Truth

Good teams treat code as documentation.

Not by writing comments everywhere.

But by writing code that explains itself.

For example:

function calculateFinalPrice(price, discount, tax) {
  return price - discount + tax
}

function calculateFinalPrice(price, discount, tax) {
  const discountedPrice = applyDiscount(price, discount)
  const finalPrice = applyTax(discountedPrice, tax)

  return finalPrice
}

Both work.

Only one communicates intent.

Readable code does a few important things:

reduces the need for external documentation
makes onboarding faster
preserves knowledge inside the system

Because the goal isn’t to explain the code somewhere else.

It’s to make the code explain itself.

A Real Example: “It Works, Don’t Touch It”

Every codebase has one.

A file or module that everyone avoids.

You open it and see something like this:

if (type === "A") {
  // complex logic
} else if (type === "B") {
  // slightly different logic
} else if (type === "C") {
  // copied and modified logic
}

No clear structure.
No clear intent.
No clear ownership.

And someone eventually says:

“It works. Let’s not touch it.”

That’s not stability.

That’s fear.

And fear is one of the clearest signals of lost knowledge.

How to Build a Memory-Resilient Codebase

You can’t prevent people from leaving.

But you can prevent knowledge from leaving with them.

A few practices make a big difference:

Make decisions visible

Not everything belongs in code.

But key decisions should be easy to find.

why something was built a certain way
trade-offs that were made
known limitations

Even lightweight notes help.

Optimize for readability

Readable code is not a luxury.

It’s a form of knowledge preservation.

clear naming
small functions
explicit logic

These are not style choices.

They’re long-term investments.

Prefer structure over cleverness

Clever code is hard to remember.

Simple, structured code is easier to rebuild mentally.

And that’s what you want.

Share ownership

If only one person understands a part of the system, that’s a risk.

Code reviews, pair programming, and rotations help distribute knowledge.

Refactor before it’s too late

The longer you wait, the more knowledge you lose.

Refactoring is not just about code quality.

It’s about keeping understanding alive.

Knowledge Handover Checklist

Most teams don’t lose knowledge suddenly.

They lose it during transitions.

Someone leaves.
Someone changes role.
Someone moves to another project.

And the handover?

Often rushed.
Sometimes skipped.

If you want to avoid that, you don’t need a long process.

You need a simple, repeatable checklist.

Before someone leaves (or switches context)

Make sure these things are covered:

1. Critical areas are identified

What parts of the system does this person know best?
Which components would be risky without them?

👉 If you don’t know this, that’s already a signal.

2. Key flows are explained, not just code

How does the system behave end-to-end?
What are the important business rules?

Code shows how.
You also need why.

3. Known pitfalls are documented

edge cases
fragile areas
“this breaks if you change X”

These are things you rarely find in code, but always matter.

4. Decisions and trade-offs are captured

why this approach was chosen
what alternatives were considered
what constraints existed

Without this, future changes become guesswork.

5. Ownership is reassigned clearly

who is responsible for this part now?
who reviews changes?

Ambiguity here leads to neglect.

6. A real walkthrough happens

Not just docs.
Not just links.

👉 A real session:

open the code
walk through real scenarios
answer questions live

This is where most knowledge transfer actually happens.

Small rule that makes a big difference

Don’t treat handover as a one-time event.

Treat it as a continuous habit:

share context during development
explain decisions in PRs
avoid knowledge silos early

Because the best handover is the one you barely need.

Final Thoughts

Corporate amnesia doesn’t happen because teams are careless.

It happens because knowledge isn’t treated as something that needs to be preserved.

Codebases don’t just store logic.

They store decisions, context, and understanding.

And when that disappears, everything becomes harder.

The goal isn’t to remember everything.

It’s to make sure the system remembers for you.

If this resonated with you:

Leave a ❤️ reaction
Drop a 🦄 unicorn
Share a part of your codebase that nobody wants to touch

And if you enjoy this kind of content, follow me here on DEV for more.

The Strategy Pattern in JavaScript: Replace Messy If-Else Logic With Clean Code

Gavin Cettolo — Tue, 14 Apr 2026 07:30:00 +0000

A while ago, I opened a file and immediately knew something was off.

Not because it was broken.
Not because it was complex.

But because it had that shape.

You know the one:

if (...) {
  // something
} else if (...) {
  // something else
} else if (...) {
  // another thing
} else {
  // fallback
}

It worked.

But every time we needed to add a new case, we had to go back into that block and make it just a bit worse.

And that’s when I realized:

This isn’t just messy code. This is a scaling problem.

Let’s fix it.

TL;DR

Long if-else chains are a signal that your logic doesn’t scale well.
The Strategy Pattern helps you encapsulate behaviors and swap them easily.
In JavaScript, you don’t need heavy OOP: functions are often enough.

The Problem: The If-Else Monster
A Real Example: Payment Methods
Why This Doesn’t Scale
Introducing the Strategy Pattern
Step-by-Step Refactoring
Final Result: Clean and Extensible
Using TypeScript for Safer Strategies
Optional: Class-Based Strategy
When to Use (and Not Use) Strategy
Final Thoughts

The Problem: The If-Else Monster

At first, if-else feels fine.

It’s simple.
It’s readable.
It gets the job done.

Until it doesn’t.

The moment your logic starts growing based on types, modes, or variants, things start getting messy.

And more importantly:

every new feature requires modifying existing logic

That’s the real problem.

A Real Example: Payment Methods

Let’s say you’re building a checkout system.

You need to handle multiple payment methods:

credit card
PayPal
bank transfer

A typical implementation might look like this:

function processPayment(method, amount) {
  if (method === "credit-card") {
    console.log("Processing credit card payment:", amount)
    // card logic
  } else if (method === "paypal") {
    console.log("Processing PayPal payment:", amount)
    // paypal logic
  } else if (method === "bank-transfer") {
    console.log("Processing bank transfer:", amount)
    // bank logic
  } else {
    throw new Error("Unsupported payment method")
  }
}

It works, but you can already feel the tension.

Why This Doesn’t Scale

The issue isn’t the code itself.

It’s how it evolves.

Every time you add a new payment method:

you modify this function
you increase its complexity
you risk breaking existing logic

After a few iterations, you end up with:

long functions
duplicated patterns
fragile logic

This is exactly where the Strategy Pattern shines.

Introducing the Strategy Pattern

The idea is simple:

Instead of having one function decide how to do everything,
delegate each behavior to a separate “strategy”.

Each strategy handles one case.

The main function just selects which one to use.

In practice:

replace conditionals with a lookup-based approach

Step-by-Step Refactoring

Let’s improve the previous example step by step.

Step 1: Extract behaviors

function payWithCreditCard(amount) {
  console.log("Processing credit card payment:", amount)
}

function payWithPaypal(amount) {
  console.log("Processing PayPal payment:", amount)
}

function payWithBankTransfer(amount) {
  console.log("Processing bank transfer:", amount)
}

Each function now has a clear responsibility.

Step 2: Create a strategy map

const paymentStrategies = {
  "credit-card": payWithCreditCard,
  "paypal": payWithPaypal,
  "bank-transfer": payWithBankTransfer,
}

This replaces the if-else chain with a simple lookup.

Step 3: Simplify the main function

function processPayment(method, amount) {
  const strategy = paymentStrategies[method]

  if (!strategy) {
    throw new Error("Unsupported payment method")
  }

  strategy(amount)
}

No branching logic.

Just delegation.

Final Result: Clean and Extensible

Now adding a new payment method is straightforward:

function payWithCrypto(amount) {
  console.log("Processing crypto payment:", amount)
}

paymentStrategies["crypto"] = payWithCrypto

No need to modify existing logic.

No risk of breaking unrelated behavior.

👉 This is the real benefit: open for extension, closed for modification

Using TypeScript for Safer Strategies

So far, everything works perfectly in JavaScript.

And thanks to this guard:

if (!strategy) {
  throw new Error("Unsupported payment method")
}

invalid inputs are handled safely.

However, the error is still detected at runtime.

With TypeScript, we can catch the same issue earlier, before the code even runs.

Step 1: Define allowed methods

type PaymentMethod = "credit-card" | "paypal" | "bank-transfer"

Now only valid methods are allowed.

Step 2: Type the strategies

type PaymentStrategy = (amount: number) => void

const paymentStrategies: Record<PaymentMethod, PaymentStrategy> = {
  "credit-card": payWithCreditCard,
  "paypal": payWithPaypal,
  "bank-transfer": payWithBankTransfer,
}

Now TypeScript guarantees:

every method has a strategy
every strategy has the correct signature

Step 3: Type the main function

function processPayment(method: PaymentMethod, amount: number) {
  const strategy = paymentStrategies[method]
  strategy(amount)
}

No need for runtime checks anymore.

Errors are caught at compile time.

Why this matters

With JavaScript, you make your code flexible.
With TypeScript, you make it reliable.

You’re not just cleaning your code.

You’re making invalid states impossible.

Optional: Class-Based Strategy

If you prefer a more OOP-style approach with JavaScript, you can model strategies as classes:

class CreditCardStrategy {
  execute(amount) {
    console.log("Processing credit card payment:", amount)
  }
}

class PayPalStrategy {
  execute(amount) {
    console.log("Processing PayPal payment:", amount)
  }
}

Then use them like this:

const strategies = {
  "credit-card": new CreditCardStrategy(),
  "paypal": new PayPalStrategy(),
}

function processPayment(method, amount) {
  const strategy = strategies[method]

  if (!strategy) {
    throw new Error("Unsupported payment method")
  }

  strategy.execute(amount)
}

It’s more structured, but also more verbose.

In JavaScript, the functional approach is usually enough.

When to Use (and Not Use) Strategy

Use it when:

you have multiple variants of the same behavior
new cases are added frequently
conditionals are growing

Avoid it when:

you only have a couple of simple cases
the logic is unlikely to change
it adds unnecessary complexity

The goal is not to apply patterns, but to solve real problems.

Final Thoughts

The Strategy Pattern isn’t about being clever, it’s about writing code that can grow without becoming fragile.

Most messy if-else chains don’t start messy, they become messy over time and by the time you notice, changing them feels risky.

The good news is:

You don’t need a rewrite, just a better way to organize behavior.

If this helped you:

Leave a ❤️ reaction
Drop a 🦄 unicorn
Share the worst if-else monster you’ve seen

And if you enjoy this kind of content, follow me here on DEV for more.

Code Reviews Without Drama: How Great Teams Give Feedback That Actually Helps

Gavin Cettolo — Tue, 07 Apr 2026 07:30:00 +0000

A few years ago, I left a code review feeling… weird.

The code worked.

Tests were passing.

But the comments?

“This is wrong”

“Bad approach”

“Rewrite this”

No explanation.

No context.

Just judgment.

Nothing was technically incorrect.

But something was off.

That’s when it clicked:

Code reviews aren’t just about code, they’re about communication.

And done poorly, they don’t improve the codebase, they just slowly damage the team.

TL;DR

Great code reviews focus on improving the code, not judging the developer.
The difference is in how feedback is framed, not just what is said.
Healthy teams optimize for clarity, context, and collaboration, not ego.

Why Code Reviews Go Wrong
What Great Code Reviews Actually Do
1. Focus on the Code, Not the Person
2. Explain the Why, Not Just the What
3. Turn Judgments Into Questions
4. Avoid Bike-Shedding
5. Balance Speed and Depth
Real Example: From Harsh to Helpful
How to Handle Receiving Feedback
Practical Team Agreements
Final Thoughts

Why Code Reviews Go Wrong

Most developers don’t want to give bad feedback, but code reviews often become tense anyway.

Why?

Because they sit at the intersection of:

ownership (“this is my code”)
identity (“this reflects my skills”)
time pressure (“we need to ship”)

Add a bit of unclear communication, and things escalate quickly.

What starts as feedback becomes criticism.
What should be collaboration becomes friction.

What Great Code Reviews Actually Do

A good code review doesn’t just catch bugs.

It does three things:

improves the code
shares knowledge
strengthens the team

If one of these is missing, something is off, especially the last one, because a team that avoids reviews or fears them will never move fast in the long run.

1. Focus on the Code, Not the Person

This sounds obvious, but small wording differences matter a lot.

Compare:

This is wrong

This logic might lead to edge cases when the input is empty

The first feels like judgment.
The second feels like collaboration.

A simple shift helps:

👉 describe the problem, not the person

Instead of:

“you did this wrong”

Try:

“this approach could cause issues because…”

It’s a small change, but it completely changes how feedback is received.

2. Explain the Why, Not Just the What

One of the most frustrating things in code reviews is vague feedback.

Refactor this

Why?

What’s the problem?

What’s the goal?

Without context, the comment becomes noise.

Good feedback always answers one question:

Why does this matter?

For example:

This works, but extracting this into a function could make it easier to test and reuse

Now the author understands:

the intent
the benefit
the trade-off

And can make a better decision.

3. Turn Judgments Into Questions

When in doubt, ask.

Questions are powerful because they:

invite discussion
reduce defensiveness
uncover context you might be missing

Instead of:

This is over-engineered

Try:

Do we need this level of abstraction here, or could a simpler approach work?

Same concern.

Completely different outcome.

Sometimes, you’ll even realize the original author had a valid reason.

4. Avoid Bike-Shedding

Not all feedback has the same weight, but many reviews treat everything equally.

You end up with long threads about:

variable names
formatting
personal preferences

While more important issues get less attention.

This is called bike-shedding and it kills productivity.

A simple rule helps:

👉 focus on what impacts:

correctness
readability
maintainability

Leave the rest to:

linters
formatters
team conventions

Your energy is limited, so use it where it matters.

5. Balance Speed and Depth

There’s a tension in every code review:

go deep → better quality
go fast → better velocity

Great teams don’t pick one, they balance both.

Some practical ways:

keep PRs small
review early, not just at the end
avoid “mega reviews” with 1000+ lines

Because the larger the change, the harder it is to review well.

And the easier it is for issues to slip through.

Real Example: From Harsh to Helpful

Let’s take a real-style example.

❌ Harsh

This is messy. Refactor it.

This creates:

confusion
frustration
back-and-forth

✅ Helpful

This works, but it’s a bit hard to follow due to the nested conditions.

What do you think about extracting this part into a separate function? It might make the flow easier to read and test.

Now we have:

context
suggestion
collaboration

Same intent, much better outcome.

How to Handle Receiving Feedback

Giving feedback is only half of the equation.

Receiving it matters just as much.

A few things that help:

assume positive intent
ask for clarification if something is unclear
don’t take comments personally
push back when needed, but with context

A good code review is not about agreeing on everything.

It’s about reaching a better solution together.

Practical Team Agreements

The best teams don’t leave this to chance.

They define how reviews should work.

A few simple agreements can make a big difference:

“Explain the why” is mandatory
Prefer questions over judgments
Focus on high-impact issues first
Keep PRs small and focused
No ego in discussions

These are small rules, but they create a much healthier environment.

Final Thoughts

Code reviews are one of the most powerful tools a team has, but only if they’re done right because bad reviews don’t just slow down development, they create friction, frustration, and eventually silence.

Great reviews do the opposite:

They improve the code.
They spread knowledge.
They build trust.

And in the long run, that’s what makes a team truly fast.

If this resonated with you:

Leave a ❤️ reaction
Drop a 🦄 unicorn
Share the best (or worst) code review you’ve experienced

And if you enjoy this kind of content, follow me here on DEV for more.

Bad Code Is a High-Interest Loan: How Technical Debt Slowly Kills Team Velocity

Gavin Cettolo — Tue, 31 Mar 2026 07:30:00 +0000

We were moving fast.

Features shipped every week.

Stakeholders were happy.

The backlog was finally under control.

Then, almost without noticing, everything slowed down. A feature that should have taken a day took three abd a small change broke something unrelated. Fixing bugs started taking longer than building new features.
And at some point, someone said:

“But this used to be faster, right?”

They weren’t wrong. At some point in the past, things were faster, but that speed came at a cost.

A cost that wasn’t visible at the time.
A cost that quietly accumulated.

This is something I’ve often wanted to explain to non-technical stakeholders:

we didn’t suddenly become slower, we’re just paying back what we borrowed.

TL;DR

Technical debt behaves like a high-interest loan: it feels cheap at first, but becomes expensive over time.
The real problem isn’t having technical debt, it’s letting it compound unmanaged.
Refactoring isn’t a cost, it’s an investment with measurable ROI in team velocity.

The Illusion of Speed
Technical Debt as a Financial Model
Where the Interest Shows Up
The Compounding Effect
When Teams Hit Default
The ROI of Refactoring
When NOT to Refactor
Practical Ways to Manage Technical Debt
Final Thoughts

The Illusion of Speed

Technical debt often starts as a conscious trade-off:

You skip a refactor.
You duplicate a bit of logic.
You hardcode something “just for now”.

And in the moment, it feels like the right decision because:

You move faster.
You deliver sooner.
You hit the deadline.

That’s why it’s so hard to avoid, because it works, but what you’re really doing is borrowing time from your future self and like any loan, that time comes back.

Technical Debt as a Financial Model

One of the most useful ways to think about technical debt is to treat it like an actual financial system.
Not just a metaphor, but a model.

Principal: the shortcut

The principal is the initial shortcut you take:

skipping a proper abstraction
duplicating logic instead of extracting it
shipping a workaround instead of fixing the root cause

Individually, these decisions are often reasonable.

Sometimes even necessary.

Interest: the friction

The interest is what you pay every time you touch that code again. It shows up as:

extra time to understand what’s happening
unexpected side effects
more effort to implement even simple changes

You don’t notice it immediately.

But it’s there, every time.

Compounding: the multiplier

And then comes the real problem: compounding.

Each new feature built on top of messy code increases the cost of the next one.

Not linearly.

Exponentially.

Where the Interest Shows Up

Interest doesn’t arrive as a big, visible cost, it shows up as friction.

Small things that make your work just a bit slower, every single day.

A feature takes longer than expected
A bug fix introduces another bug
You spend more time reading code than writing it
Onboarding a new developer becomes difficult

Or even something like this:

// "temporary" workaround from 6 months ago
if (user.role === "admin" && featureFlagX) {
  // special case inside special case
}

Nothing here breaks the system, but everything here slows you down.

That’s the interest you’re paying.

The Compounding Effect

This is where things become dangerous.

Technical debt doesn’t just add cost, it multiplies it. Every new feature built on top of unclear or fragile code becomes:

harder to implement
harder to test
harder to change

So the next feature takes longer.

And the next one.

At some point, the system isn’t just complex.

It’s actively resisting change.

And that’s when velocity starts dropping, even if your team hasn’t changed at all.

When Teams Hit Default

In finance, default happens when you can’t repay your debt anymore.

In software, it looks different, but the signal is clear.

You see it when:

refactoring is always postponed
certain parts of the codebase are avoided
every release feels risky
progress slows down despite increasing effort

At this stage, teams often react the wrong way.

They try to push harder.

More hours.

More pressure.

More “just ship it”.

But the problem isn’t effort.

It’s accumulated complexity.

And no amount of speed can compensate for that.

The ROI of Refactoring

Refactoring is often perceived as a cost, something that slows down delivery, something you “don’t have time for”, but that perspective ignores the return.

Refactoring is an investment.

And like any investment, it pays off over time.

Let’s make it concrete, imagine:

A feature currently takes 3 days to implement
After refactoring, similar features take 1.5 days

That’s a 50% improvement.
Over 10 features, you’ve saved 15 days.
That’s not just cleaner code, that’s recovered velocity.

And just like debt compounds negatively, good code compounds positively:

faster development
fewer bugs
easier onboarding
more confidence in changes

This is where engineering meets business, because velocity is not just a technical metric, it’s a business advantage.

When NOT to Refactor

Not all debt needs to be repaid immediately, and not all code needs to be perfect.

Refactoring everything blindly can be just as harmful.

Avoid refactoring when:

the code is rarely touched
the feature is about to be replaced
you’re still validating a product idea
the cost clearly outweighs the benefit

The goal is not to eliminate technical debt, but it’s to manage it intentionally.

Practical Ways to Manage Technical Debt

You don’t need a full rewrite to stay in control, you need consistency.

A few habits make a huge difference over time:

Refactor as you go: improve code while you’re already working on it
Make debt visible: track it instead of hiding it
Set a refactoring budget: even 10–20% of time is enough
Review for maintainability, not just correctness
Call out complexity early, before it spreads

These are small actions, but they prevent large problems.

Final Thoughts

Technical debt isn’t the enemy, it’s a tool.

Sometimes you take on debt to move faster and that’s a valid decision, but if you ignore it, it becomes a liability and, eventually, it starts slowing everything down.

The real problem isn’t having technical debt.

It’s pretending you don’t.

If this resonated with you:

Leave a ❤️ reaction
Drop a 🦄 unicorn
Share the most “expensive” piece of bad code you’ve seen

And if you enjoy this kind of content, follow me here on DEV for more.

React Components vs Spaghetti: 5 Signs Your UI Is Becoming Unmaintainable

Gavin Cettolo — Tue, 24 Mar 2026 08:30:00 +0000

Last week I opened a React component… and immediately closed it.

Not because it was complex.

But because it felt hostile.

You know that feeling: the file keeps scrolling, props are flying around, and every small change feels like it might break something completely unrelated.

That’s not complexity.

That’s entropy.

And if you’ve been building UIs for a while, you’ve probably seen it happen slowly, almost invisibly.

Let’s talk about the signals before things get out of hand.

TL;DR

If your React components start feeling hard to read, fragile, or unpredictable, your UI is likely becoming unmaintainable.

The most common signals are oversized components, props drilling, unclear responsibilities, duplication, and messy conditionals.

You don’t need a rewrite, just small, consistent refactoring habits.

The Problem with “It Still Works”
1. The God Component (Too Big to Understand)
2. Props Drilling Everywhere
3. Confusing Responsibilities
4. UI Logic Duplication
5. Conditional Rendering Hell
Bonus Signs You Shouldn’t Ignore
Mini Refactoring: From Spaghetti to Clean
Practical Refactoring Rituals
Final Thoughts

The Problem with “It Still Works”

Most messy UIs don’t start messy.

They start small, clear, even elegant.

Then a feature gets added.

Then another one.

Then a quick fix before a deadline.

Nothing dramatic, just small decisions that make sense in the moment.

Until one day you open a file and realize you don’t really understand it anymore.

That’s the moment where “it still works” becomes dangerous.

Because now every change carries risk.

And the cost of touching the code becomes higher than leaving it alone.

1. The God Component (Too Big to Understand)

There’s usually one file in every project that everyone avoids.

It’s big. Really big.

It handles data, UI, state, events, and probably a few side effects too.

Something like this:

export default function Dashboard({ user, posts }: Props) {
  // fetching logic
  // filtering logic
  // UI rendering
  // event handlers
  // conditionals everywhere

  return (
    <div>
      <h1>{user.name}</h1>
      {/* hundreds of lines */}
    </div>
  )
}

The issue isn’t just the size.

It’s the lack of boundaries.

When everything lives in the same place, nothing is clearly defined.

You don’t know what’s safe to change and what might break something else.

A useful rule I rely on is simple:

If you can’t describe a component in one sentence, it’s doing too much.

Breaking it down doesn’t mean over-engineering.

It means restoring clarity.

export function Dashboard() {
  return (
    <div>
      <UserHeader/>
      <PostList/>
    </div>
  )
}

Now each piece has a purpose.

And more importantly, a limit.

2. Props Drilling Everywhere

Props drilling usually starts innocently.

You pass user from a parent to a child, then to another child, then another.

Until you end up here:

<Dashboard user={user}>
  <Sidebar user={user}>
    <UserAvatar user={user}/>
  </Sidebar>
</Dashboard>

At this point, some components are just acting as pipelines.

They don’t use the data, they just pass it along.

That creates a subtle kind of friction.

Every layer becomes aware of something it doesn’t actually care about.

And any change to that data ripples through the entire tree.

The obvious solution is often:

“Let’s use Context.”

And that’s valid… but only to a point.

Context is not a silver bullet.

Overusing it can make your app harder to reason about:

data becomes less explicit
re-renders become harder to control
tracing where values come from gets tricky

A better approach is to use it intentionally, when it actually solves a real problem:

truly global data (auth, theme, user)
deeply shared state
repeated props drilling across many levels

Combined with a custom hook, it stays clean:

function useUser() {
  return useContext(UserContext)
}

function UserAvatar() {
  const user = useUser()
  return <img src={user.avatar} />
}

Now the dependency lives exactly where it’s needed.

3. Confusing Responsibilities

Sometimes the problem isn’t visible at a glance.

It’s not about how much code there is, but about what kind of work is happening in the same place.

A single component handling:

data fetching
state management
transformation
rendering

…is doing too many different jobs.

The result is cognitive overload.

You open the file and constantly switch context:

“Am I reading UI? Or logic? Or data?”

That friction slows everything down.

Separating responsibilities makes the code easier to navigate and easier to trust.

A simple split already helps a lot:

function usePosts() {
  // fetch + transform
}

function PostList() {
  const posts = usePosts()
  return (...)
}

Now the component reads like a story again, not a puzzle.

4. UI Logic Duplication

Duplication doesn’t always look like copy-paste.

Sometimes it shows up as repeated patterns:

if (isLoading) return <Spinner />
if (error) return <Error />

You write it once.

Then again.

At some point, changing that behavior means updating multiple places.

That’s when it becomes expensive.

Extracting shared logic is less about abstraction and more about centralizing decisions.

function DataState({ loading, error, children }: Props) {
  if (loading) return <Spinner />
  if (error) return <Error />
  return children
}

Now the behavior lives in one place.

And your UI becomes more consistent by default.

5. Conditional Rendering Hell

Conditional rendering is fine.

Until it isn’t.

We’ve all written something like this:

return isAdmin
  ? isActive
    ? <AdminPanel />
    : <InactiveAdmin />
  : <UserPanel />

It works.

But it’s not easy to read.

The problem isn’t React.

It’s that too much logic is living inside JSX.

A first step is to move that logic out:

function renderContent() {
  if (isAdmin && isActive) return <AdminPanel />
  if (isAdmin) return <InactiveAdmin />
  return <UserPanel />
}

return renderContent()

Already much better.

Using Guard Clauses

Guard clauses can make this even clearer, when used carefully.

if (!isAdmin) {
  return <UserPanel />
}

if (!isActive) {
  return <InactiveAdmin />
}

return <AdminPanel />

This removes nesting and keeps the flow linear.

The key is balance.

use guard clauses when they simplify the flow
avoid stacking too many negative conditions
keep the logic readable from top to bottom

The goal isn’t fewer lines.

It’s clarity.

Bonus Signs You Shouldn’t Ignore

Sometimes the signals are less technical and more instinctive.

You hesitate before opening a file
You’re afraid to change something
Fixing a bug feels risky
You’ve said “let’s not touch this” more than once

These are all valid warnings.

And they usually show up before bigger problems.

Mini Refactoring: From Spaghetti to Clean

A while ago I ran into a component like this.

It wasn’t broken.

It wasn’t even that complex.

But it had that feeling:

“There’s just a bit too much going on here.”

❌ Before

export default function Dashboard({ user, posts }: Props) {
  const [filter, setFilter] = useState("all")

  const filteredPosts = posts.filter(p =>
    filter === "all" ? true : p.type === filter
  )

  return (
    <div>
      <h1>{user.name}</h1>

      <select onChange={e => setFilter(e.target.value)}>
        <option value="all">All</option>
        <option value="tech">Tech</option>
      </select>

      {filteredPosts.length === 0 ? (
        <p>No posts</p>
      ) : (
        filteredPosts.map(p => <div key={p.id}>{p.title}</div>)
      )}
    </div>
  )
}

Nothing wrong, technically.

But everything is mixed together:

state
logic
UI

So I started small.

Step 1: isolate the logic

function useFilteredPosts(posts: Post[]) {
  const [filter, setFilter] = useState("all")

  const filtered = posts.filter(post =>
    filter === "all" ? true : post.type === filter
  )

  return { filter, setFilter, filtered }
}

Now the component doesn’t care how filtering works.

Step 2: extract reusable UI

function PostFilter({ value, onChange }: Props) {
  return (
    <select value={value} onChange={e => onChange(e.target.value)}>
      <option value="all">All</option>
      <option value="tech">Tech</option>
    </select>
  )
}

Step 3: compose everything

export default function Dashboard({ user, posts }: Props) {
  const { filter, setFilter, filtered } = useFilteredPosts(posts)

  return (
    <div>
      <h1>{user.name}</h1>

      <PostFilter value={filter} onChange={setFilter} />

      {filtered.length === 0 ? (
        <p>No posts</p>
      ) : (
        filtered.map(p => <div key={p.id}>{p.title}</div>)
      )}
    </div>
  )
}

Same feature.

Completely different feeling.

That’s the real goal of refactoring.

Practical Refactoring Rituals

You don’t need a full rewrite to fix spaghetti code.

You need habits.

Refactoring works best when it’s part of your workflow, not something you postpone.

A few simple ones:

extract things early, when they start feeling “off”
keep components focused on one responsibility
move growing logic into hooks
spend time naming things clearly

None of these are revolutionary.

But together, they make your codebase easier to work with.

Final Thoughts

Spaghetti UI isn’t a failure.

It’s what happens when real features meet real constraints.

But if you ignore it, it slowly turns your codebase into something you avoid instead of something you trust.

The good news is, you don’t need perfection.

Just small improvements, applied consistently.

If this article resonated with you:

Leave a ❤️ reaction
Drop a 🦄 unicorn
Share the worst component you’ve ever written (or seen) in the comments

And if you enjoy this kind of content, follow me here on DEV for more.

Next.js Folder Zen: Padroneggiare la Directory app/

Gavin Cettolo — Wed, 18 Mar 2026 08:30:00 +0000

Se hai iniziato da poco a usare Next.js 13+, probabilmente hai aperto un progetto e hai pensato:

“Perché questa struttura di cartelle sembra così... diversa?”

Con l’App Router, la directory app/ è diventata il cuore di ogni progetto Next.js moderno. Ma per molti sviluppatori—soprattutto quelli che arrivano dal vecchio pages/ router—la struttura delle cartelle può risultare inizialmente confusa.

Sistemiamo le cose.

TL;DR

La directory app/ di Next.js introduce un’architettura basata su file che controlla routing, layout e comportamento del rendering.

File speciali come page.tsx, layout.tsx, loading.tsx, error.tsx e not-found.tsx definiscono come si comportano le route.

Una struttura pulita con route groups e dynamic routes rende le app Next.js scalabili e manutenibili.

Perché la directory app/ è importante
Il concetto base: File-Based Routing
I file essenziali dentro app/
Layouts: l’arma segreta
Loading ed Error States
Error Boundaries: una limitazione importante
Gestire le 404 con not-found.tsx
Dynamic Routes
Route Groups
Una struttura reale
Errori comuni
Considerazioni finali

Perché la directory `app/` è importante

Quando Next.js ha introdotto l’App Router, non era solo una nuova cartella.

Era un cambio di paradigma.

Invece di spargere la logica in più livelli, la directory app/ organizza l’app attorno a route e segmenti UI.

Pensala così:

URL → Cartella → UI

Questo approccio rende le applicazioni grandi molto più facili da capire.

Invece di chiederti:

“Dov’è il componente per questa pagina?”

Vai direttamente nella cartella che corrisponde alla route.

Il concetto base: File-Based Routing

Nel app/ directory il routing è semplice.

Le cartelle definiscono le route.

Esempio:

app/
  page.tsx
  about/
    page.tsx
  dashboard/
    page.tsx

Questo genera:

/           → page.tsx
/about      → about/page.tsx
/dashboard  → dashboard/page.tsx

Una pagina base:

export default function Page() {
  return <h1>Hello Next.js</h1>
}

Zero configurazione di routing.

I file essenziali dentro `app/`

Next.js usa nomi di file speciali per definire il comportamento.

`page.tsx`

Definisce la UI della route.

export default function Page() {
  return <div>Dashboard</div>
}

Ogni route accessibile deve avere un page.tsx.

`layout.tsx`

I layout wrappano più pagine e persistono durante la navigazione.

app/
  layout.tsx
  dashboard/
    layout.tsx
    page.tsx

Esempio:

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <main>
      <nav>Navigation</nav>
      {children}
    </main>
  )
}

I layout non vengono ri-renderizzati durante la navigazione, il che li rende perfetti per:

navbar
sidebar
UI condivisa

Layouts: l’arma segreta

Uno dei punti più forti dell’App Router sono i layout annidati.

app/
  layout.tsx
  dashboard/
    layout.tsx
    analytics/
      page.tsx

Rendering:

Root Layout
   ↓
Dashboard Layout
   ↓
Analytics Page

Questo permette UI complesse senza duplicare codice.

Loading ed Error States

Next.js supporta stati UI a livello di route.

`loading.tsx`

Mostrato durante il caricamento.

export default function Loading() {
  return <p>Loading...</p>
}

`error.tsx`

Gestisce errori nel segmento.

"use client" // Gli error boundaries devono essere componenti client

export default function Error({ error }: { error:Error }) {
  return <p>Something went wrong</p>
}

Error Boundaries: una limitazione importante

Il file error.tsx funziona come un gestore di errori React per un segmento di percorso.

Tuttavia, esiste un limite importante che molti sviluppatori trascurano.

I gestori di errori non intercettano gli errori all'interno dei gestori di eventi.

Cattura solo errori durante:

rendering
server components
data fetching

Esempio:

"use client"

export default function Error({
  error,
  reset,
}: {
  error:Error
  reset: () => void
}) {
  return (
    <div>
      <h2>C'è stato un errore.</h2>
      <button onClick={() => reset()}>
        Riprova
      </button>
    </div>
  )
}

Gli errori generati all'interno dei gestori di eventi devono comunque essere gestiti manualmente. Ad esempio:

"use client"

export default function Button() {
  const handleClick = () => {
    try {
      throw new Error("Boom");
    } catch (err) {
      console.error(err);
    }
  }
  return <button onClick={handleClick}>Click</button>
}

Considera error.tsx come una rete di sicurezza per l'interfaccia utente, non come un sistema completo di gestione degli errori.

Gestire le 404 con `not-found.tsx`

Next.js semplifica le 404.

export default function NotFound() {
  return (
    <h2>Pagina non trovata</h2>
  )
}

Trigger:

import {notFound} from "next/navigation"

if (!post) {
  notFound()
}

Supporta livelli multipli:

app/
  not-found.tsx
  dashboard/
    not-found.tsx

Viene usato quello più vicino.

Dynamic Routes

I dynamic routes usano le parentesi quadre.

Ad esempio:

app/
  blog/
    [slug]/
      page.tsx

URL generati:

/blog/my-first-post
/blog/nextjs-routing
/blog/react-performance

Esempio di implementazione:

export default function BlogPost({
  params
}: {
  params: { slug: string }
}) {
  return <h1>{params.slug}</h1>
}

È possibile combinarlo anche con la generazione statica.

Segmenti multipli

Esempio:

app/
  shop/
    [category]/
      [product]/
        page.tsx

Esempi di route generate:

/shop/laptops/macbook-pro
/shop/phones/iphone-15

Esempio di codice:

export default function ProductPage({
  params
}: {
  params: {
    category:string
    product:string
  }
}) {
  return (
    <div>
      <h1>{params.product}</h1>
      <p>Category: {params.category}</p>
    </div>
  )
}

Route Catch-all

A volte servono percorsi flessibili.

Next.js supporta i segmenti catch-all.

[...slug]

Esempio:

app/
  docs/
    [...slug]/
      page.tsx

URL supportati:

/docs
/docs/getting-started
/docs/guides/routing
/docs/api/config

Implementazione:

export default function DocsPage({
  params
}: {
  params: { slug: string[] }
}) {
  return <div>{params.slug?.join("/")}</div>
}

Optional route catch-all

È la versione opzionale:

[[...slug]]

Questo supporta entrambi:

/docs
/docs/routing
/docs/config/api

Tutto gestito dalla stessa pagina.

Comprendere i Route Groups

I Route Groups aiutano a organizzare il codice senza influire sugli URL.

Usano le parentesi tonde:

app/
  (marketing)/
    page.tsx
    about/
      page.tsx

  (dashboard)/
    dashboard/
      page.tsx

URL generati:

/
/about
/dashboard

Non appaiono nelle URL e sono perfetti per separare diverse sezioni dell'app così da avere:

layout differenti
provider differenti
strutture UI differenti

Un esempio pratico

app/
  layout.tsx
  page.tsx

  (marketing)/
    page.tsx
    about/
      page.tsx

  (dashboard)/
    dashboard/
      layout.tsx
      page.tsx
      analytics/
        page.tsx
      settings/
        page.tsx

  blog/
    page.tsx
    [slug]/
      page.tsx

In questo modo, le pagine di marketing, l'interfaccia utente dell'applicazione e i percorsi dei contenuti rimangono chiaramente separati.

Errori comuni

Quando affianco sviluppatori che utilizzano Next.js, questi sono i problemi che riscontro più frequentemente.

1. Mischiare `pages/` e `app/`

Sebbene tecnicamente possibile, crea confusione.

Se inizi con app/, mantieni solo app.

2. Cartelle annidate

Mantieni la struttura semplice.

Preferisci:

dashboard/analytics

Piuttosto che:

dashboard/features/analytics/pages

3. Ignorare i layout

I layout sono una delle funzionalità più potenti di App Router.

Usateli.

Semplificano notevolmente l'architettura.

Considerazioni finali

La directory app/ potrebbe inizialmente sembrare insolita.

Ma una volta che ci si prende la mano, diventa uno dei modi più puliti per strutturare le applicazioni React.

Invece di dover lottare con la configurazione del routing, i wrapper globali e la duplicazione dei layout, si ottiene un'architettura chiara e prevedibile.

Le cartelle rappresentano i percorsi
File speciali controllano il comportamento
I layout gestiscono l'interfaccia utente condivisa

E improvvisamente il tuo progetto sembra molto più... zen.

Se questo articolo ti è stato utile:

lascia un ❤️
aggiungi un 🦄
raccontami nei commenti come organizzi i tuoi progetti

E se apprezzate contenuti di questo tipo, non esitate a seguirmi qui su DEV per altri post su Next.js, architettura e produttività degli sviluppatori.

EDIT: Questa è una versione riadattata in italiano di questo mio precedente articolo: Next.js Folder Zen: Mastering the app/ Directory

Next.js Folder Zen: Mastering the app/ Directory

Gavin Cettolo — Tue, 17 Mar 2026 08:30:00 +0000

If you’ve recently started using Next.js 13+, you’ve probably opened a project and thought:

“Why does this folder structure feel so… different?”

With the App Router, the app/ directory became the heart of every modern Next.js project. But for many developers, especially those coming from the old pages/ router, the folder structure can feel confusing at first.

Let’s fix that.

TL;DR

The app/ directory in Next.js introduces a file-system-based architecture that controls routing, layouts, and rendering behavior.

Special files like page.tsx, layout.tsx, loading.tsx, error.tsx, and not-found.tsx define how routes behave.

A clean folder strategy with route groups and dynamic routes makes large Next.js apps scalable and maintainable.

Why the app/ Directory Matters
The Core Concept: File-Based Routing
The Essential Files Inside app/
Layouts: The Secret Weapon
Loading and Error States
Error Boundaries: One Important Limitation
Handling 404 Pages with not-found.tsx
Dynamic Routes
Understanding Route Groups
A Real-World Folder Structure
Common Mistakes Developers Make
Final Thoughts

Why the `app/` Directory Matters

When Next.js introduced the App Router, it wasn’t just a new folder.

It was a shift in how we design React applications.

Instead of scattering logic across multiple layers, the app/ directory organizes your app around routes and UI segments.

Think of it like this:

URL → Folder → UI

This approach makes large applications easier to reason about.

Instead of asking:

"Where is the component for this page?"

You simply look at the folder that matches the route.

The Core Concept: File-Based Routing

Routing in the app/ directory is simple.

Folders define routes.

Example:

app/
  page.tsx
  about/
    page.tsx
  dashboard/
    page.tsx

This produces:

/           → page.tsx
/about      → about/page.tsx
/dashboard  → dashboard/page.tsx

A basic page file looks like this:

export default function Page() {
  return <h1>Hello Next.js</h1>
}

That’s it.

No router configuration required.

The Essential Files Inside `app/`

Next.js uses special filenames to control behavior.

Here are the ones you'll use most.

`page.tsx`

Defines a route UI.

export default function Page() {
  return <div>Dashboard</div>
}

Every accessible route must contain a page.tsx.

`layout.tsx`

Layouts wrap multiple pages and persist during navigation.
Example:

app/
  layout.tsx
  dashboard/
    layout.tsx
    page.tsx

Example layout:

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <main>
      <nav>Navigation</nav>
      {children}
    </main>
  )
}

Layouts do not re-render during navigation, making them perfect for:

Navigation bars
Sidebars
Shared UI

Layouts: The Secret Weapon

One of the biggest advantages of the App Router is nested layouts.

Example structure:

app/
  layout.tsx
  dashboard/
    layout.tsx
    analytics/
      page.tsx

Rendering flow:

Root Layout
   ↓
Dashboard Layout
   ↓
Analytics Page

This allows you to build complex UI structures without prop-drilling or layout duplication.

Loading and Error States

Next.js lets you define route-level UI states.

`loading.tsx`

Displayed while a route loads.

export default function Loading() {
  return <p>Loading...</p>
}

Useful for:

skeleton screens
streaming UI

`error.tsx`

Handles errors inside a route segment.

"use client" // Error boundaries must be Client Components

export default function Error({ error }: { error:Error }) {
  return <p>Something went wrong</p>
}

This prevents the entire app from crashing.

Error Boundaries: One Important Limitation

The error.tsx file works as a React Error Boundary for a route segment.

But there's an important limitation many developers miss.

Error boundaries do not catch errors inside event handlers.

They only catch errors that happen during:

rendering
server component execution
data fetching

Example error boundary:

"use client"

export default function Error({
  error,
  reset,
}: {
  error:Error
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong.</h2>
      <button onClick={() => reset()}>
        Try again
      </button>
    </div>
  )
}

Errors thrown inside event handlers must still be handled manually.

Example:

"use client"

export default function Button() {
  const handleClick = () => {
    try {
      throw new Error("Boom");
    } catch (err) {
      console.error(err);
    }
  }
  return <button onClick={handleClick}>Click me</button>
}

Think of error.tsx as a UI safety net, not a full error handling system.

Handling 404 Pages with `not-found.tsx`

Every production app needs a good 404 experience.

Next.js handles this with not-found.tsx.

Example:

export default function NotFound() {
  return (
    <div>
      <h2>Page not found</h2>
      <p>The content you're looking for doesn't exist.</p>
    </div>
  )
}

To trigger it, use the notFound() function.

import {notFound} from "next/navigation"

if (!post) {
  notFound()
}

You can define multiple not-found.tsx files at different levels.

Example:

app/
  not-found.tsx
  dashboard/
    not-found.tsx

The closest one in the route tree wins.

Dynamic Routes

Dynamic routes use square brackets.

Example:

app/
  blog/
    [slug]/
      page.tsx

URLs generated:

/blog/my-first-post
/blog/nextjs-routing
/blog/react-performance

Example implementation:

export default function BlogPost({
  params
}: {
  params: { slug: string }
}) {
  return <h1>{params.slug}</h1>
}

You can also combine it with static generation.

Multiple Dynamic Segments

Example:

app/
  shop/
    [category]/
      [product]/
        page.tsx

Routes:

/shop/laptops/macbook-pro
/shop/phones/iphone-15

Example code:

export default function ProductPage({
  params
}: {
  params: {
    category:string
    product:string
  }
}) {
  return (
    <div>
      <h1>{params.product}</h1>
      <p>Category: {params.category}</p>
    </div>
  )
}

Catch-All Routes

Sometimes you need flexible routes.

Next.js supports catch-all segments.

[...slug]

Example:

app/
  docs/
    [...slug]/
      page.tsx

Supported URLs:

/docs
/docs/getting-started
/docs/guides/routing
/docs/api/config

Implementation:

export default function DocsPage({
  params
}: {
  params: { slug: string[] }
}) {
  return <div>{params.slug?.join("/")}</div>
}

Optional Catch-All Routes

Optional version:

[[...slug]]

This supports both:

/docs
/docs/routing
/docs/config/api

All handled by the same page.

Understanding Route Groups

Route Groups help organize code without affecting URLs.

They use parentheses.

Example:

app/
  (marketing)/
    page.tsx
    about/
      page.tsx

  (dashboard)/
    dashboard/
      page.tsx

Generated URLs:

/
/about
/dashboard

The group names never appear in the URL.

Why use them?

Because real applications often have multiple app sections.

Example:

app/
  (marketing)/
    layout.tsx
    page.tsx
    pricing/
      page.tsx

  (app)/
    layout.tsx
    dashboard/
      page.tsx
    settings/
      page.tsx

This allows:

different layouts
different providers
different UI structures

without polluting URLs.

A Real-World Folder Structure

Here’s a scalable structure used in production projects.

app/
  layout.tsx
  page.tsx

  (marketing)/
    page.tsx
    about/
      page.tsx

  (dashboard)/
    dashboard/
      layout.tsx
      page.tsx
      analytics/
        page.tsx
      settings/
        page.tsx

  blog/
    page.tsx
    [slug]/
      page.tsx

This keeps marketing pages, application UI, and content routes clearly separated.

Common Mistakes Developers Make

When I mentor developers using Next.js, these are the issues I see most often.

1. Mixing `pages/` and `app/`

While technically possible, it creates confusion.

If you start with app/, commit to it.

2. Over-nesting folders

Deep structures become hard to maintain.

Prefer:

dashboard/analytics

Instead of:

dashboard/features/analytics/pages

3. Ignoring layouts

Layouts are one of the most powerful features of the App Router.

Use them.

They dramatically simplify architecture.

Final Thoughts

The app/ directory might feel unfamiliar at first.

But once it clicks, it becomes one of the cleanest ways to structure React applications.

Instead of wrestling with routing configuration, global wrappers, and layout duplication, you get a clear, predictable architecture.

Folders represent routes
special files control behavior
layouts manage shared UI

And suddenly your project feels a lot more… Zen.

If this article helped you understand the Next.js app/ directory better:

Leave a ❤️ reaction
Drop a 🦄 unicorn if you love Next.js
Share in the comments how you structure your projects

And if you enjoy content like this, feel free to follow me here on DEV for more posts about Next.js, architecture, and developer productivity.

EDIT: A few people asked for an Italian version of this article.
You can read it here: Next.js Folder Zen: Padroneggiare la Directory app/

DEV Community: Gavin Cettolo

You Don’t Need Microservices (Yet): A Reality Check for Devs

You Don't Need Microservices (Yet): A Reality Check for Devs

How Premature Architecture Decisions Slow Down Teams and Burn Engineering Budget

TL;DR

Table of Contents

What Microservices Actually Solve

What a Well-Structured Monolith Looks Like

The Real Cost of Premature Decomposition

Monolith vs Microservices: A Concrete Comparison

In the modular monolith

In a microservices architecture

Rules of Thumb: When to Actually Consider Splitting

The Decision Framework

Monolith vs Microservices Decision Matrix

When Microservices Are the Right Call

Final Thoughts

API Calls Done Right: From Messy Fetch to Clean Data Layer

TL;DR

Table of Contents

What We're Building (and Why)

Step 1: The apiClient - One Place for Transport Logic

Step 2: Typed Responses and Structured Error Handling

Step 3: Service Modules - Organizing by Domain

Step 4: Authentication - Bearer Tokens Done Right

Step 5: Automatic Token Refresh

Step 6: Connecting the Data Layer to React with TanStack Query

TanStack Query

The Final Folder Structure

Final Thoughts

The Hidden Cost of "It Works": Why Quick Fixes Kill Long-Term Speed

TL;DR

Table of Contents

The Anatomy of a Quick Fix

The Two Places Quick Fixes Do Damage

In the codebase

In the team

The Broken Windows Effect in Codebases

Why "It Works" Is the Most Dangerous Phrase in Engineering

The Hidden Cost, Quantified

The Quick Fix Decision Framework

1. Is it documented?

2. Is it isolated?

3. Does it have a scheduled remediation?

4. Does the team know about it?

The decision matrix

When Quick Fixes Are Actually the Right Call

Building a Culture That Pays Debt on Schedule

Final Thoughts

Stop Using useEffect Like This: 5 Patterns That Are Silently Breaking Your React App

TL;DR

Table of Contents

Why useEffect Is Deceptively Hard

Pattern 1: Deriving State Inside useEffect

The fix

Pattern 2: Overloading a Single useEffect

The fix

Pattern 3: Missing or Suppressed Dependencies

The fix

Pattern 4: Fetching Data Without Structure

The fix: a custom hook

The fix: use a library (recommended)

TanStack Query

Pattern 5: Using useEffect When You Simply Don't Need It

The fix

Bonus: React 18, Strict Mode, and the Double-Mount Trap

The fix

Before vs After: A Real Refactoring

- No loading state, no error handling, no cleanup.

A Better Mental Model

Final Thoughts

The AI-Augmented Developer: How AI Is Changing the Way We Write Code

TL;DR

Table of Contents

From Searching to Asking

AI as a Copilot, Not an Autopilot

A Real Workflow: How Developers Actually Use AI

1. Start with your own idea

2. Use AI to explore options

3. Generate or refine code