DEV Community: Gavin Cettolo

Clean API Design in Node.js: A Practical Guide

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

Most Node.js APIs start the same way.

A server.js file. A few routes. Maybe an app.js if you've read a tutorial. Everything in one place because the app is small and there's no reason to complicate it yet.

Then the app grows.

Routes multiply. Business logic leaks into route handlers. Error handling is copy-pasted across files with slight variations. A new developer joins and spends their first week just trying to understand where things live.

The API still works. But it's become a place nobody wants to touch.

This guide is about building the structure that prevents that outcome — from the first route to a production-ready layer with validation, versioning, centralized error handling, rate limiting, and auto-generated documentation.

We'll build it incrementally, so every step is independently useful even if you stop halfway through.

TL;DR

Clean API design in Node.js is mostly about separation of concerns: routes, controllers, services, and validation each live in their own layer.
Zod handles validation at the boundary — before business logic ever runs.
Centralized error handling is the single change that improves the most codebases the fastest.

- Rate limiting, API versioning, and OpenAPI docs are not advanced topics — they're table stakes for any API that will be used by someone else.

What We're Building
Step 1: Project Structure
Step 2: The Express App Setup
Step 3: Routing and Controllers — Separating Concerns
Step 4: The Service Layer — Keeping Business Logic Out of Controllers
Step 5: Validation with Zod — Stop Trusting Your Inputs
Step 6: Centralized Error Handling
Step 7: Response Shaping — Consistent API Responses
Step 8: API Versioning
Step 9: Rate Limiting
Step 10: OpenAPI Documentation with Swagger
Why You Might Consider Fastify Instead

- Final Thoughts

What We're Building

We'll build a REST API for a simple product catalog — products with a name, price, and category. The domain is intentionally simple so the focus stays on structure, not business logic.

By the end, the API will have:

Clean separation between routing, controllers, and services
Request validation with Zod
Centralized error handling
Consistent response shaping
API versioning (/api/v1/)
Rate limiting
Auto-generated Swagger documentation Let's start from zero.

Step 1: Project Structure

Before writing a single line of code, let's define where things live.

src/
├── api/
│   └── v1/
│       ├── products/
│       │   ├── products.router.ts
│       │   ├── products.controller.ts
│       │   ├── products.service.ts
│       │   └── products.schema.ts
│       └── index.ts
│
├── middleware/
│   ├── errorHandler.ts
│   ├── rateLimiter.ts
│   └── validateRequest.ts
│
├── lib/
│   ├── AppError.ts
│   └── responseHelper.ts
│
├── app.ts
└── server.ts

The logic behind this structure:

api/v1/ — all routes are versioned from day one. Adding v2 later is a folder, not a refactor.
Feature folders (products/) — every domain owns its router, controller, service, and schema. Adding a new domain means adding a new folder, not touching existing files.
middleware/ — cross-cutting concerns that apply to multiple routes.

- `lib/` — shared utilities with no framework dependency.

Step 2: The Express App Setup

// src/app.ts

import express, { Application } from 'express'
import helmet from 'helmet'
import cors from 'cors'
import { rateLimiter } from './middleware/rateLimiter'
import { errorHandler } from './middleware/errorHandler'
import { setupSwagger } from './lib/swagger'
import v1Router from './api/v1'

export function createApp(): Application {
  const app = express()

  // Security headers
  app.use(helmet())

  // CORS
  app.use(cors({
    origin: process.env.ALLOWED_ORIGINS?.split(',') ?? '*',
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  }))

  // Body parsing
  app.use(express.json({ limit: '10kb' }))

  // Rate limiting — applied globally before any route
  app.use(rateLimiter)

  // API routes
  app.use('/api/v1', v1Router)

  // Swagger docs
  setupSwagger(app)

  // 404 handler — must come after all routes
  app.use((req, res) => {
    res.status(404).json({
      success: false,
      error: { code: 'NOT_FOUND', message: `Route ${req.method} ${req.path} not found` },
    })
  })

  // Centralized error handler — must be last
  app.use(errorHandler)

  return app
}

// src/server.ts

import { createApp } from './app'

const PORT = process.env.PORT ?? 3000

const app = createApp()

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`)
})

Two files, two responsibilities. app.ts defines the application. server.ts starts it. This separation makes testing significantly easier — you can import createApp() in tests without starting a real server.

Step 3: Routing and Controllers — Separating Concerns

The most common mistake in Express apps is putting business logic inside route handlers:

// ❌ Everything in one place — this is how the mess starts
app.get('/products/:id', async (req, res) => {
  try {
    const product = products.find(p => p.id === req.params.id)
    if (!product) {
      return res.status(404).json({ error: 'Product not found' })
    }
    res.json(product)
  } catch (error) {
    res.status(500).json({ error: 'Something went wrong' })
  }
})

The route handler is doing three things: routing, business logic, and error handling. As the application grows, this becomes unmaintainable.

The fix is a clean separation between the router (where) and the controller (what):

// src/api/v1/products/products.router.ts

import { Router } from 'express'
import { productController } from './products.controller'
import { validateRequest } from '@/middleware/validateRequest'
import {
  createProductSchema,
  updateProductSchema,
  productIdSchema,
} from './products.schema'

const router = Router()

router.get('/', productController.getAll)
router.get('/:id', validateRequest({ params: productIdSchema }), productController.getById)
router.post('/', validateRequest({ body: createProductSchema }), productController.create)
router.put('/:id',
  validateRequest({ params: productIdSchema, body: updateProductSchema }),
  productController.update
)
router.delete('/:id', validateRequest({ params: productIdSchema }), productController.remove)

export default router

// src/api/v1/products/products.controller.ts

import { Request, Response, NextFunction } from 'express'
import { productService } from './products.service'
import { sendSuccess } from '@/lib/responseHelper'
import { AppError } from '@/lib/AppError'

export const productController = {
  async getAll(req: Request, res: Response, next: NextFunction) {
    try {
      const products = await productService.getAll()
      sendSuccess(res, products)
    } catch (error) {
      next(error)
    }
  },

  async getById(req: Request, res: Response, next: NextFunction) {
    try {
      const product = await productService.getById(req.params.id)
      if (!product) throw new AppError('Product not found', 404, 'NOT_FOUND')
      sendSuccess(res, product)
    } catch (error) {
      next(error)
    }
  },

  async create(req: Request, res: Response, next: NextFunction) {
    try {
      const product = await productService.create(req.body)
      sendSuccess(res, product, 201)
    } catch (error) {
      next(error)
    }
  },

  async update(req: Request, res: Response, next: NextFunction) {
    try {
      const product = await productService.update(req.params.id, req.body)
      if (!product) throw new AppError('Product not found', 404, 'NOT_FOUND')
      sendSuccess(res, product)
    } catch (error) {
      next(error)
    }
  },

  async remove(req: Request, res: Response, next: NextFunction) {
    try {
      await productService.remove(req.params.id)
      sendSuccess(res, null, 204)
    } catch (error) {
      next(error)
    }
  },
}

The controller's only job is to translate HTTP into service calls and back. It doesn't know how products are stored. It doesn't know the business rules. It knows HTTP.

Notice the next(error) pattern — every caught error is forwarded to the centralized error handler, which we'll define in Step 6.

Step 4: The Service Layer — Keeping Business Logic Out of Controllers

The service layer is where business logic lives. It knows nothing about HTTP — no req, no res, no status codes.

// src/api/v1/products/products.service.ts

import { Product, CreateProductPayload, UpdateProductPayload } from './products.schema'
import { AppError } from '@/lib/AppError'

// In-memory mock — replace with your DB layer
const mockProducts: Product[] = [
  { id: '1', name: 'Wireless Keyboard', price: 79.99, category: 'Electronics', createdAt: new Date().toISOString() },
  { id: '2', name: 'Standing Desk', price: 349.00, category: 'Furniture', createdAt: new Date().toISOString() },
  { id: '3', name: 'Noise-Cancelling Headphones', price: 199.99, category: 'Electronics', createdAt: new Date().toISOString() },
]

let nextId = 4

export const productService = {
  async getAll(): Promise<Product[]> {
    return mockProducts
  },

  async getById(id: string): Promise<Product | null> {
    return mockProducts.find(p => p.id === id) ?? null
  },

  async create(payload: CreateProductPayload): Promise<Product> {
    // Business rule: no duplicate product names
    const existing = mockProducts.find(
      p => p.name.toLowerCase() === payload.name.toLowerCase()
    )
    if (existing) {
      throw new AppError('A product with this name already exists', 409, 'CONFLICT')
    }

    const product: Product = {
      id: String(nextId++),
      ...payload,
      createdAt: new Date().toISOString(),
    }

    mockProducts.push(product)
    return product
  },

  async update(id: string, payload: UpdateProductPayload): Promise<Product | null> {
    const index = mockProducts.findIndex(p => p.id === id)
    if (index === -1) return null

    mockProducts[index] = { ...mockProducts[index], ...payload }
    return mockProducts[index]
  },

  async remove(id: string): Promise<void> {
    const index = mockProducts.findIndex(p => p.id === id)
    if (index === -1) {
      throw new AppError('Product not found', 404, 'NOT_FOUND')
    }
    mockProducts.splice(index, 1)
  },
}

The service throws AppError for business rule violations — not HTTP errors. The controller translates those into HTTP responses. The layers don't bleed into each other.

When you replace the mock with a real database, you only touch the service. The controller, the router, the validation — none of them change.

Step 5: Validation with Zod — Stop Trusting Your Inputs

Every API that accepts external input needs validation. Without it, you're one malformed request away from a runtime error, a data integrity problem, or a security vulnerability.

Zod lets you define a schema and validate against it with full TypeScript inference — the same schema gives you runtime validation and compile-time types.

// src/api/v1/products/products.schema.ts

import { z } from 'zod'

const CATEGORIES = ['Electronics', 'Furniture', 'Clothing', 'Books', 'Other'] as const

export const createProductSchema = z.object({
  name: z.string()
    .min(2, 'Name must be at least 2 characters')
    .max(100, 'Name must be at most 100 characters')
    .trim(),
  price: z.number()
    .positive('Price must be a positive number')
    .multipleOf(0.01, 'Price must have at most 2 decimal places'),
  category: z.enum(CATEGORIES, {
    errorMap: () => ({ message: `Category must be one of: ${CATEGORIES.join(', ')}` }),
  }),
})

export const updateProductSchema = createProductSchema.partial()

export const productIdSchema = z.object({
  id: z.string().min(1, 'Product ID is required'),
})

// TypeScript types derived directly from the schemas
export type Product = z.infer<typeof createProductSchema> & {
  id: string
  createdAt: string
}
export type CreateProductPayload = z.infer<typeof createProductSchema>
export type UpdateProductPayload = z.infer<typeof updateProductSchema>

Now the validateRequest middleware that the router uses:

// src/middleware/validateRequest.ts

import { Request, Response, NextFunction } from 'express'
import { ZodSchema, ZodError } from 'zod'
import { AppError } from '@/lib/AppError'

interface ValidationSchemas {
  body?: ZodSchema
  params?: ZodSchema
  query?: ZodSchema
}

export function validateRequest(schemas: ValidationSchemas) {
  return (req: Request, res: Response, next: NextFunction) => {
    try {
      if (schemas.body) {
        req.body = schemas.body.parse(req.body)
      }
      if (schemas.params) {
        req.params = schemas.params.parse(req.params)
      }
      if (schemas.query) {
        req.query = schemas.query.parse(req.query)
      }
      next()
    } catch (error) {
      if (error instanceof ZodError) {
        const details = error.errors.map(e => ({
          field: e.path.join('.'),
          message: e.message,
        }))
        next(new AppError('Validation failed', 400, 'VALIDATION_ERROR', details))
      } else {
        next(error)
      }
    }
  }
}

Validation happens at the boundary — before the request reaches the controller. If the input is invalid, the request never gets further. The controller and service can trust that req.body and req.params are exactly the shape they expect.

Step 6: Centralized Error Handling

Scattered error handling is one of the most common problems in Node.js APIs. Some routes return { error: "message" }. Others return { message: "error" }. Some return HTML error pages by accident. None of them are consistent.

The fix is a single error handler that every error flows through:

// src/lib/AppError.ts

export class AppError extends Error {
  constructor(
    public readonly message: string,
    public readonly statusCode: number = 500,
    public readonly code: string = 'INTERNAL_ERROR',
    public readonly details?: unknown
  ) {
    super(message)
    this.name = 'AppError'
  }
}

// src/middleware/errorHandler.ts

import { Request, Response, NextFunction } from 'express'
import { AppError } from '@/lib/AppError'
import { ZodError } from 'zod'

export function errorHandler(
  error: unknown,
  req: Request,
  res: Response,
  next: NextFunction
) {
  // Known application error
  if (error instanceof AppError) {
    return res.status(error.statusCode).json({
      success: false,
      error: {
        code: error.code,
        message: error.message,
        ...(error.details ? { details: error.details } : {}),
      },
    })
  }

  // Unhandled Zod error (shouldn't reach here, but just in case)
  if (error instanceof ZodError) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Validation failed',
        details: error.errors,
      },
    })
  }

  // JSON parse errors from express.json()
  if (error instanceof SyntaxError && 'body' in error) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'INVALID_JSON',
        message: 'Request body contains invalid JSON',
      },
    })
  }

  // Unknown errors — log and return generic response
  console.error('[Unhandled Error]', error)

  return res.status(500).json({
    success: false,
    error: {
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred',
    },
  })
}

Every error in the entire application flows through this single function. Every error response has the same shape. Debugging is easier. Client-side error handling is easier. Adding logging or monitoring is a one-line change in one place.

Step 7: Response Shaping — Consistent API Responses

Error responses are consistent. Success responses should be too.

// src/lib/responseHelper.ts

import { Response } from 'express'

interface SuccessResponse<T> {
  success: true
  data: T
  meta?: Record<string, unknown>
}

export function sendSuccess<T>(
  res: Response,
  data: T,
  statusCode = 200,
  meta?: Record<string, unknown>
): void {
  if (statusCode === 204) {
    res.status(204).send()
    return
  }

  const response: SuccessResponse<T> = {
    success: true,
    data,
    ...(meta ? { meta } : {}),
  }

  res.status(statusCode).json(response)
}

Every successful response now looks like this:

{
  "success": true,
  "data": {
    "id": "1",
    "name": "Wireless Keyboard",
    "price": 79.99,
    "category": "Electronics",
    "createdAt": "2025-06-01T10:00:00.000Z"
  }
}

Every error response looks like this:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "price", "message": "Price must be a positive number" }
    ]
  }
}

Consistent. Predictable. Easy to consume from a frontend or a third-party client.

Step 8: API Versioning

Versioning from day one costs almost nothing. Adding it later costs a lot.

// src/api/v1/index.ts

import { Router } from 'express'
import productsRouter from './products/products.router'

const v1Router = Router()

v1Router.use('/products', productsRouter)
// v1Router.use('/orders', ordersRouter)
// v1Router.use('/users', usersRouter)

export default v1Router

In app.ts, the router is already mounted at /api/v1. When you need a breaking change, you create src/api/v2/, mount it at /api/v2, and both versions coexist without conflict.

// app.ts — adding v2 is a two-line change
app.use('/api/v1', v1Router)
app.use('/api/v2', v2Router)

No migration pain. No breaking existing clients.

Step 9: Rate Limiting

Rate limiting protects your API from abuse — intentional or accidental. It's a one-time setup with express-rate-limit:

// src/middleware/rateLimiter.ts

import rateLimit from 'express-rate-limit'

export const rateLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,                  // max 100 requests per window per IP
  standardHeaders: true,     // return rate limit info in headers
  legacyHeaders: false,
  message: {
    success: false,
    error: {
      code: 'RATE_LIMIT_EXCEEDED',
      message: 'Too many requests, please try again later.',
    },
  },
})

// Stricter limiter for write operations
export const writeLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 20,
  standardHeaders: true,
  legacyHeaders: false,
  message: {
    success: false,
    error: {
      code: 'RATE_LIMIT_EXCEEDED',
      message: 'Too many write requests, please slow down.',
    },
  },
})

Apply the stricter limiter to mutation routes:

// products.router.ts — add writeLimiter to POST, PUT, DELETE
import { writeLimiter } from '@/middleware/rateLimiter'

router.post('/', writeLimiter, validateRequest({ body: createProductSchema }), productController.create)
router.put('/:id', writeLimiter, validateRequest({ params: productIdSchema, body: updateProductSchema }), productController.update)
router.delete('/:id', writeLimiter, validateRequest({ params: productIdSchema }), productController.remove)

Step 10: OpenAPI Documentation with Swagger

An API without documentation is an API that only you can use.

swagger-jsdoc generates an OpenAPI spec from JSDoc comments. swagger-ui-express serves it as an interactive UI.

// src/lib/swagger.ts

import swaggerJsdoc from 'swagger-jsdoc'
import swaggerUi from 'swagger-ui-express'
import { Application } from 'express'

const options: swaggerJsdoc.Options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Product Catalog API',
      version: '1.0.0',
      description: 'A clean REST API for managing products',
    },
    servers: [{ url: '/api/v1' }],
  },
  apis: ['./src/api/**/*.router.ts'],
}

const spec = swaggerJsdoc(options)

export function setupSwagger(app: Application): void {
  app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(spec))
}

Now add JSDoc annotations to your router:

// products.router.ts — with Swagger annotations

/**
 * @swagger
 * /products:
 *   get:
 *     summary: Get all products
 *     tags: [Products]
 *     responses:
 *       200:
 *         description: List of products
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/Product'
 *
 * /products/{id}:
 *   get:
 *     summary: Get a product by ID
 *     tags: [Products]
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Product found
 *       404:
 *         description: Product not found
 */

The interactive documentation is now available at http://localhost:3000/api/docs. Every endpoint is documented, explorable, and testable directly from the browser.

Why You Might Consider Fastify Instead

Everything we've built works well with Express. But if you're starting a new project in 2025, Fastify deserves serious consideration.

Here's an honest comparison:

	Express	Fastify
Performance	Good	~2x faster (benchmarks)
TypeScript support	Manual setup	First-class, built-in
Schema validation	Via middleware (Zod, Joi)	Built-in (JSON Schema / Zod plugin)
Plugin ecosystem	Massive, mature	Smaller, but growing fast
Learning curve	Very low	Low
Logging	Manual (Winston, Pino)	Built-in (Pino)
OpenAPI generation	Manual (swagger-jsdoc)	Via `@fastify/swagger`

The most important differences in practice:

Performance. Fastify is consistently faster than Express in benchmarks — sometimes significantly. For most applications, this doesn't matter at all. For high-throughput APIs, it can.

TypeScript. Fastify was designed with TypeScript in mind. Route handlers are typed end-to-end with no extra configuration. In Express, you need to augment Request types manually.

Schema-first validation. Fastify uses JSON Schema (or Zod via a plugin) for validation and serialization. Responses are validated before they're sent, which means TypeScript types and runtime behavior are guaranteed to match.

When to stick with Express:

You're joining an existing Express codebase.
Your team already knows Express deeply.
You rely on Express-specific middleware that has no Fastify equivalent.
You want the largest possible ecosystem of tutorials, Stack Overflow answers, and community resources. When to consider Fastify:
You're starting a new project from scratch.
TypeScript support matters to you out of the box.
You care about raw performance.
You want built-in logging and schema validation without extra setup. The architecture we've built in this article — feature folders, controller/service separation, centralized error handling, versioning — applies equally to Fastify. The structural principles don't change. Only the framework-specific syntax does.

{% embed https://fastify.dev %}

Final Thoughts

We started with a server.js file and a vague sense that things should be better organized.

We ended with a structure that scales:

Routes declare what exists and what middleware applies.
Controllers translate HTTP into service calls.
Services contain business logic, framework-agnostic.
Schemas define and validate the contract at the boundary.
Middleware handles cross-cutting concerns once, globally. None of these steps are complicated individually. The value is in the combination — and in doing it from the start, before the codebase makes it expensive.

The next time you start a Node.js API, resist the temptation to put everything in one file "just for now." The structure we've built here isn't overengineering — it's the minimum that makes a backend maintainable by more than one person.

What does your current Express setup look like?

Are you working with a structure like this, or inheriting something that grew organically? Drop your setup — or your horror story — in the comments.

If this was useful, a ❤️ or a 🦄 helps it reach more backend developers who need it.
And follow along for the next article in the series.

The 3 Types of Developers Every Team Has (And Why It Matters)

Gavin Cettolo — Mon, 08 Jun 2026 15:06:29 +0000

The 3 Types of Developers Every Team Has (And Why It Matters)

I've worked with a lot of developers over the years.

Different companies, different stacks, different cultures. Startups where five people were responsible for everything. Scale-ups where the engineering org had its own org chart. Agencies where the team changed every quarter.

And across all of them, I kept seeing the same three people.

Not the same names. Not the same faces. But the same dynamics, playing out with different actors on different stages.

Once I started noticing them, I couldn't stop. They were everywhere. And more importantly, I started to see how the combination of these three types, more than any individual, determined whether a team shipped well, burned out, or quietly fell apart.

This article is about those three types. Who they are, what they bring, where they struggle, and what it means for you if you're the one responsible for the team.

TL;DR

Every engineering team has a Lone Rocket, a Glue Engineer, and a Big Picture Skeptic, whether they're aware of it or not.
None of these types is inherently better than the others. Each one is essential in the right context, and destructive in the wrong one.
As a tech lead, your job isn't to change these people. It's to understand them well enough to put them in positions where their natural tendencies become team strengths.

A Note Before We Start
Type 1: The Lone Rocket
Type 2: The Glue Engineer
Type 3: The Big Picture Skeptic
Why the Mix Matters More Than the Individuals
What This Means for You as a Tech Lead
Final Thoughts

A Note Before We Start

These are archetypes, not boxes.

Real people are more complex than any category. Most developers have traits from all three types, with one tendency that's more dominant depending on the context, the project, or where they are in their career.

The point of naming these patterns isn't to label people. It's to make visible something that's usually invisible, the different ways people contribute to a team, and why some of those ways are easier to recognize and reward than others.

With that said, let's meet the three types.

Type 1: The Lone Rocket

You know this person the moment you look at the commit history.

The Lone Rocket is technically brilliant. They move fast, think clearly, and produce more output than anyone else on the team. When there's a hard problem, a gnarly performance bug, a tricky architectural decision, a deadline that should be impossible, the Lone Rocket is the one you call.

They deliver. Almost always.

In a team I worked with a few years ago, there was a developer, I'll call him Marcus, who had single-handedly built the entire data pipeline that the product ran on. It was elegant, it was fast, and it was completely inside his head.

No documentation. Minimal comments. PR descriptions that said things like "fixes the thing from last week."

When Marcus was around, everything was fine. When Marcus went on vacation for two weeks, the team ground to a halt. Nobody else fully understood how the pipeline worked. A minor configuration change turned into a five-day incident because three different people were afraid to touch the code without him.

Marcus wasn't being malicious. He just worked the way that felt natural to him: fast, focused, and alone.

What the Lone Rocket brings

Raw output. When velocity matters, they deliver.
Deep technical ownership. They know their domain better than anyone.
Problem-solving under pressure. They thrive when the stakes are high.

Where the Lone Rocket struggles

Knowledge transfer. Information lives in their head, not in the codebase.
Collaboration. Working with others slows them down, and they know it.
Bus factor. The team's resilience depends on their availability.

The context where they shine

The Lone Rocket is at their best in the early stages of a product, when speed matters more than process, and depth of expertise matters more than documentation. They're also invaluable in high-stakes firefighting situations, where you need someone to go deep fast.

They become a liability when the product matures and the team grows, and the code they own becomes critical infrastructure that nobody else understands.

As a tech lead

Your job with the Lone Rocket is not to slow them down. It's to make their work transferable.

That means pair programming sessions where they're the driver and someone else is the navigator. It means requiring PR descriptions that explain why, not just what. It means gently but consistently asking: "if you were hit by a bus tomorrow, what would break and who would know how to fix it?"

Not as a threat. As a genuine engineering concern.

Type 2: The Glue Engineer

The Glue Engineer is the hardest type to see, because their work is specifically the work that doesn't show up in metrics.

They don't have the highest commit count. They're not closing the most tickets. You won't find their name in the release notes for the biggest features.

What you will find: they're the ones who answered twelve Slack messages this week from confused teammates. They did three thorough code reviews that prevented two bugs from reaching production. They updated the onboarding doc that nobody else had touched in eight months. They noticed that two teams were building the same thing in parallel and quietly connected the right people before it became a problem.

They are the connective tissue of the team.

I once worked alongside a developer, I'll call her Priya, who was consistently rated as a "solid mid-level" in performance reviews. Not a standout. Not on the promotion track.

Then she went on parental leave for four months.

In those four months, two junior developers got stuck and spun their wheels for weeks on problems Priya would have unblocked in an afternoon. A decision that needed three teams to align took two months instead of two weeks because nobody was naturally playing the connector role. The team's PR review turnaround time doubled.

When Priya came back, nobody said "we finally realized how much you were doing." But the team noticeably reaccelerated.

The Glue Engineer's impact is often only visible in their absence.

What the Glue Engineer brings

Team coherence. They prevent the small frictions that compound into big dysfunction.
Knowledge distribution. They actively spread context across the team.
Psychological safety. Their availability makes it easier for others to ask for help.

Where the Glue Engineer struggles

Visibility. Their work is hard to quantify in a performance review.
Burnout risk. Being the person everyone comes to is exhausting, especially if it's not acknowledged.
Their own depth. Time spent helping others is time not spent on deep technical work.

The context where they shine

The Glue Engineer is most valuable in teams that are growing, onboarding new people, or navigating organizational complexity. They're the stabilizing force during periods of change.

They can become frustrated, and start to disengage, in environments that only reward individual technical output and don't recognize coordination and knowledge-sharing as real work.

As a tech lead

Your job with the Glue Engineer is to make their contribution visible.

This is not easy in a culture that measures story points and merged PRs. But it matters.

Name the work. In team retros, in 1:1s, in performance conversations, be specific: "you unblocked three people this sprint, and that has real value." Advocate for promotion criteria that include collaboration and knowledge-sharing, not just technical output.

And watch for burnout. The Glue Engineer will often absorb team stress before it becomes visible. Check in before the signs appear, not after.

Type 3: The Big Picture Skeptic

The Big Picture Skeptic is the one who asks the uncomfortable question right when everyone else is ready to start building.

"Do we actually need this feature?"

"What happens to this data model when we add multi-tenancy in six months?"

"We built something almost identical to this last year. Why are we starting from scratch?"

In the middle of a sprint, with a deadline looming and momentum building, these questions are deeply unwelcome. The Big Picture Skeptic can feel like a brake pedal when everyone wants to accelerate.

And sometimes, honestly, they are just slowing things down.

But sometimes they're the only thing standing between the team and three months of work that turns out to be solving the wrong problem.

I worked with a developer, I'll call him Daniel, who had a reputation for being "difficult." He pushed back on scope in planning meetings. He asked uncomfortable questions during architecture reviews. More than once, I heard other developers say: "Daniel always has to complicate everything."

Then one day, in a planning meeting, Daniel asked why the new reporting dashboard needed to be built as a standalone service. The project had already been scoped, estimated, and approved.

His question opened a thirty-minute conversation that revealed the feature would duplicate functionality already being built by another team, a team nobody in the room had been in contact with. The duplication would have taken two months to untangle after the fact.

Daniel's question saved six weeks of engineering time.

He was still described as "difficult" in his next performance review.

What the Big Picture Skeptic brings

Risk reduction. They catch architectural problems before they're expensive.
Long-term thinking. They hold the team accountable to decisions made three months ago.
Scope discipline. They push back on complexity creep.

Where the Big Picture Skeptic struggles

Timing. Their instinct to question can misfire in contexts that need momentum, not analysis.
Perception. They are frequently labeled as negative, resistant, or not a team player.
Execution mode. Once a decision is made, shifting from questioning to building can be genuinely difficult for them.

The context where they shine

The Big Picture Skeptic is most valuable in planning and architecture phases, before the team has committed to a direction. In execution mode, with the decision already made, their skepticism has less to contribute and can damage morale.

As a tech lead

Your job with the Big Picture Skeptic is to give their instincts a designated space.

Create a moment in planning where skeptical questions are explicitly invited, before the team shifts into execution mode. Make it a structural part of the process: "before we finalize this, let's spend ten minutes asking what we might be missing."

This does two things. It harnesses the Skeptic's strength at the moment it's most valuable. And it signals to the rest of the team that skepticism has a place, just not at every moment of every sprint.

Also: when the Skeptic is right, say so explicitly. Their contributions are easy to forget once the crisis they prevented never happens.

Why the Mix Matters More Than the Individuals

Here's the thing about these three types: a team made entirely of one type is almost always dysfunctional.

A team of only Lone Rockets moves fast and breaks things, including itself. Knowledge is siloed. Collaboration is minimal. When one person leaves, a piece of the product leaves with them. The team scales output, not resilience.

A team of only Glue Engineers is cohesive, kind, and stuck. Everyone is well-connected. Nobody is pushing hard on the hard problems. Alignment happens easily; execution happens slowly. The team has great retros and mediocre sprints.

A team of only Big Picture Skeptics never ships. Every decision is questioned. Every scope is challenged. Every architecture is relitigated. The team produces excellent pre-mortems for projects that don't exist yet.

The strength isn't in having any one type. It's in having all three, and understanding how to position them so their strengths reinforce each other instead of colliding.

The Lone Rocket builds the thing. The Glue Engineer makes sure the rest of the team understands it. The Big Picture Skeptic makes sure it was the right thing to build.

That's not a formula. It's more of an ideal. Real teams are messier. But it's a useful picture to hold in your head when you're thinking about what a team is missing.

What This Means for You as a Tech Lead

If you're leading a team, here's the most useful thing this framework offers: a way to see gaps before they become problems.

Look at your team and ask:

Who is the Lone Rocket? Do they have a knowledge transfer habit, or is critical information living only in their head? What happens to the team if they leave?

Who is the Glue Engineer? Are they recognized for what they do, or are they quietly absorbing team friction without acknowledgment? Are they at risk of burning out?

Who is the Big Picture Skeptic? Do they have a designated space to contribute their best work, or are they fighting against the process at every turn? When was the last time their skepticism was publicly credited with preventing a real problem?

And the harder question: what's missing?

If your team has no one playing the Glue role, coordination problems are going to compound quietly until they become a crisis. If your team has no one playing the Skeptic role, you'll ship faster, right up until you ship the wrong thing. If your team has no Lone Rocket, you'll have excellent process and sluggish output.

Recognizing the gap is the first step to addressing it, whether that means hiring for it, reassigning responsibilities, or creating structural conditions that bring out a latent strength in someone already on the team.

Final Thoughts

The best teams I've ever worked with weren't the ones with the highest average technical skill.

They were the ones where different people were contributing in genuinely different ways, and where the team lead understood that difference well enough to make it work.

Brilliant individuals working in isolation don't make great teams. Cohesive teams that never challenge their own decisions don't ship great products. Fast teams that never slow down to ask hard questions eventually run fast in the wrong direction.

The Lone Rocket, the Glue Engineer, and the Big Picture Skeptic.

You've worked with all three.

The question worth sitting with is: which one are you, and is the team you're on creating the conditions for that to be a strength?

Which of these three types resonates most with your experience, as a developer, or as someone leading a team?

And the harder question: which one does your current team desperately need more of?

Drop it in the comments. These conversations are always the most honest ones.

If this resonated, a ❤️ or a 🦄 helps it reach more people who need to read it.
And if you want more articles from the Team Lead Chronicles series, follow along.

React State Management: When to Use useState, Context, or Zustand

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

Here's a conversation I've had more than once.

A developer is building a React app. It starts simple, a few components, some local state, everything in useState. Then the app grows. Props start getting passed down two levels, then three, then five. Someone suggests Context. Someone else says "just use Redux." A third person has heard of Zustand.

Three hours later, the team is arguing about state management instead of building the product.

The problem isn't that there are too many options. The problem is that most teams pick a tool based on what they've heard of, not based on what problem they're actually solving.

This article gives you a decision framework, and a single example that grows with you, so the next time this conversation comes up, you know exactly what to reach for and why.

TL;DR

useState is not a "beginner tool", it's the right tool for local, component-scoped state, at any level of experience.
Context API solves prop drilling, not state management. Using it as a global store causes re-render problems that are hard to debug.
Zustand is the pragmatic choice for shared global state in most real-world apps, minimal boilerplate, excellent performance, no ceremony.
Redux still has a place, but that place is narrower than most teams think.

The Example We'll Use Throughout
Stage 1: useState: Local State Done Right
Stage 2: Prop Drilling and When It Actually Becomes a Problem
Stage 3: Context API: What It's Good For and Where It Breaks
Stage 4: Zustand: Shared State Without the Ceremony
Where Redux Fits (and Where It Doesn't)
The Decision Tree
Final Thoughts

The Example We'll Use Throughout

We're building a shopping cart for an e-commerce app.

The features we'll implement:

Add and remove products from the cart
Show the cart item count in the navbar
Show the full cart contents in a sidebar

Here's the component tree we're working with:

App
├── Navbar
│   └── CartIcon (shows item count)
├── ProductList
│   └── ProductCard (has "Add to Cart" button)
└── CartSidebar (shows items, totals, remove buttons)

This structure is intentionally realistic. CartIcon and CartSidebar both need cart data. ProductCard needs to modify it. They share no direct parent except App.

We'll implement this cart four times, once with each approach, so the trade-offs are concrete and visible.

Stage 1: useState: Local State Done Right

useState is the foundation. Before reaching for anything else, understand what it does well.

It manages state that belongs to a single component, state that doesn't need to be shared, doesn't need to persist across navigation, and doesn't need to be accessed from a sibling or distant ancestor.

For our cart, let's start with just the ProductCard. It has a small piece of truly local state: whether the "Add to Cart" button has just been clicked and should show a brief "Added!" confirmation.

// src/components/ProductCard.tsx

import { useState } from 'react'
import { Product } from '@/types'

interface Props {
  product: Product
  onAddToCart: (product: Product) => void
}

export function ProductCard({ product, onAddToCart }: Props) {
  // This state belongs entirely to this component.
  // Nothing outside needs to know about it.
  const [justAdded, setJustAdded] = useState(false)

  function handleAdd() {
    onAddToCart(product)
    setJustAdded(true)
    setTimeout(() => setJustAdded(false), 1500)
  }

  return (
    <div className="product-card">
      <h3>{product.name}</h3>
      <p>€{product.price.toFixed(2)}</p>
      <button onClick={handleAdd} disabled={justAdded}>
        {justAdded ? 'Added!' : 'Add to Cart'}
      </button>
    </div>
  )
}

justAdded is the textbook case for useState: it's ephemeral, it's local, and nothing outside ProductCard would ever need to know about it.

Now, where does the actual cart state live?

If we lift it to App and pass it down as props, we get this:

// src/App.tsx

import { useState } from 'react'
import { CartItem, Product } from '@/types'

export function App() {
  const [cartItems, setCartItems] = useState<CartItem[]>([])

  function addToCart(product: Product) {
    setCartItems(prev => {
      const existing = prev.find(item => item.product.id === product.id)
      if (existing) {
        return prev.map(item =>
          item.product.id === product.id
            ? { ...item, quantity: item.quantity + 1 }
            : item
        )
      }
      return [...prev, { product, quantity: 1 }]
    })
  }

  function removeFromCart(productId: string) {
    setCartItems(prev => prev.filter(item => item.product.id !== productId))
  }

  return (
    <div>
      <Navbar cartItems={cartItems} />
      <ProductList cartItems={cartItems} onAddToCart={addToCart} />
      <CartSidebar
        cartItems={cartItems}
        onRemove={removeFromCart}
      />
    </div>
  )
}

This works. For a small app, this is perfectly fine.

The question is: when does it stop being fine?

Stage 2: Prop Drilling and When It Actually Becomes a Problem

Right now, cartItems and the cart callbacks are passed from App to three direct children. One level deep. No real problem.

But Navbar doesn't use cartItems directly, it passes them down to CartIcon:

// src/components/Navbar.tsx

interface Props {
  cartItems: CartItem[] // Navbar doesn't need this...
}

export function Navbar({ cartItems }: Props) {
  return (
    <nav>
      <Logo />
      <CartIcon cartItems={cartItems} /> {/* ...it just passes it here */}
    </nav>
  )
}

And ProductList doesn't use onAddToCart directly, it passes it to each ProductCard:

// src/components/ProductList.tsx

interface Props {
  cartItems: CartItem[]      // Also just passing through
  onAddToCart: (product: Product) => void
}

export function ProductList({ cartItems, onAddToCart }: Props) {
  return (
    <div>
      {products.map(product => (
        <ProductCard
          key={product.id}
          product={product}
          onAddToCart={onAddToCart}
        />
      ))}
    </div>
  )
}

This is prop drilling: components accepting props purely to pass them to their children, with no use for those props themselves.

At two levels, it's annoying. At four or five levels, it becomes a maintenance problem:

Every intermediate component needs to be updated when the shape of the data changes.
It's hard to understand which component actually uses the data vs which one is just a courier.
Refactoring the tree requires touching every level simultaneously.

This is the signal to reach for something else.

But the question is: what something else?

Stage 3: Context API - What It's Good For and Where It Breaks

Context is React's built-in solution to prop drilling. It lets you put data in a "context" at a high level in the tree, and read it directly from any descendant, without threading it through every intermediate component.

Let's implement the cart with Context:

// src/context/CartContext.tsx

import { createContext, useContext, useState, ReactNode } from 'react'
import { CartItem, Product } from '@/types'

interface CartContextValue {
  cartItems: CartItem[]
  addToCart: (product: Product) => void
  removeFromCart: (productId: string) => void
  totalItems: number
}

const CartContext = createContext<CartContextValue | null>(null)

export function CartProvider({ children }: { children: ReactNode }) {
  const [cartItems, setCartItems] = useState<CartItem[]>([])

  function addToCart(product: Product) {
    setCartItems(prev => {
      const existing = prev.find(item => item.product.id === product.id)
      if (existing) {
        return prev.map(item =>
          item.product.id === product.id
            ? { ...item, quantity: item.quantity + 1 }
            : item
        )
      }
      return [...prev, { product, quantity: 1 }]
    })
  }

  function removeFromCart(productId: string) {
    setCartItems(prev => prev.filter(item => item.product.id !== productId))
  }

  const totalItems = cartItems.reduce((sum, item) => sum + item.quantity, 0)

  return (
    <CartContext.Provider value={{ cartItems, addToCart, removeFromCart, totalItems }}>
      {children}
    </CartContext.Provider>
  )
}

export function useCart() {
  const context = useContext(CartContext)
  if (!context) throw new Error('useCart must be used within CartProvider')
  return context
}

Now Navbar, CartIcon, ProductCard, and CartSidebar can all access the cart directly:

// src/components/CartIcon.tsx
import { useCart } from '@/context/CartContext'

export function CartIcon() {
  const { totalItems } = useCart() // Direct access, no prop drilling
  return <div className="cart-icon">🛒 {totalItems}</div>
}

// src/components/ProductCard.tsx
import { useCart } from '@/context/CartContext'

export function ProductCard({ product }: { product: Product }) {
  const { addToCart } = useCart()
  const [justAdded, setJustAdded] = useState(false)

  function handleAdd() {
    addToCart(product)
    setJustAdded(true)
    setTimeout(() => setJustAdded(false), 1500)
  }

  return (
    <div className="product-card">
      <h3>{product.name}</h3>
      <p>€{product.price.toFixed(2)}</p>
      <button onClick={handleAdd} disabled={justAdded}>
        {justAdded ? 'Added!' : 'Add to Cart'}
      </button>
    </div>
  )
}

App is now clean:

// src/App.tsx
export function App() {
  return (
    <CartProvider>
      <Navbar />
      <ProductList />
      <CartSidebar />
    </CartProvider>
  )
}

This is much better. No prop drilling. Clean component interfaces.

So why not stop here?

The re-render problem

Context has a performance characteristic that surprises many developers: every component that consumes a context re-renders whenever any value in that context changes.

Let's say your context holds both cartItems and userPreferences:

// ❌ One context for unrelated data, a performance trap
const AppContext = createContext({
  cartItems: [],
  addToCart: () => {},
  userPreferences: { theme: 'dark', language: 'en' },
  updatePreferences: () => {},
})

Now, when a user adds a product to the cart, every component consuming AppContext re-renders, including those that only care about userPreferences and have nothing to do with the cart.

In a small app, this is invisible. As the app grows and the context accumulates more state, it becomes a real performance problem that's notoriously hard to debug, because the cause (a context update) and the symptom (a slow UI) are spatially distant in the code.

The fix is to split contexts by concern:

// ✅ Separate contexts for separate concerns
const CartContext = createContext(/* cart state */)
const UserPreferencesContext = createContext(/* user preferences */)

But this adds overhead, multiple providers, multiple hooks, multiple files. And it still doesn't solve the fundamental issue: any component that needs any value from CartContext will re-render on every cart update, even if it only cares about totalItems and cartItems didn't change in a way that affects totalItems.

When Context is the right tool

Context is excellent for:

Static or rarely-changing data: theme, locale, authenticated user info, feature flags.
Avoiding prop drilling for configuration: things components need to read but almost never cause re-renders because they don't change.
Dependency injection: passing services or callbacks down the tree without threading them through props.

Context is the wrong tool for:

Frequently updated shared state: a cart that changes on every user interaction.
State that many components subscribe to independently: each subscriber re-renders on every update.
Complex state with many actions: the logic in the Provider grows unwieldy quickly.

If you find yourself optimizing Context with useMemo and useCallback to prevent re-renders, that's a signal you've pushed Context beyond what it was designed for.

Stage 4: Zustand, Shared State Without the Ceremony

Zustand is a small, fast state management library built specifically for the problems Context struggles with. It uses a store outside the React tree, which means components can subscribe to specific slices of state, and only re-render when those slices change.

Let's rewrite the cart as a Zustand store:

// src/store/cartStore.ts

import { create } from 'zustand'
import { CartItem, Product } from '@/types'

interface CartState {
  cartItems: CartItem[]
  addToCart: (product: Product) => void
  removeFromCart: (productId: string) => void
  clearCart: () => void
  totalItems: () => number
  totalPrice: () => number
}

export const useCartStore = create<CartState>((set, get) => ({
  cartItems: [],

  addToCart: (product) => {
    set(state => {
      const existing = state.cartItems.find(
        item => item.product.id === product.id
      )
      if (existing) {
        return {
          cartItems: state.cartItems.map(item =>
            item.product.id === product.id
              ? { ...item, quantity: item.quantity + 1 }
              : item
          ),
        }
      }
      return {
        cartItems: [...state.cartItems, { product, quantity: 1 }],
      }
    })
  },

  removeFromCart: (productId) => {
    set(state => ({
      cartItems: state.cartItems.filter(
        item => item.product.id !== productId
      ),
    }))
  },

  clearCart: () => set({ cartItems: [] }),

  // Derived values as functions, computed on access, not stored
  totalItems: () =>
    get().cartItems.reduce((sum, item) => sum + item.quantity, 0),

  totalPrice: () =>
    get().cartItems.reduce(
      (sum, item) => sum + item.product.price * item.quantity,
      0
    ),
}))

Now each component subscribes to exactly what it needs:

// src/components/CartIcon.tsx
// Only re-renders when totalItems changes
import { useCartStore } from '@/store/cartStore'

export function CartIcon() {
  const totalItems = useCartStore(state => state.totalItems())
  return <div className="cart-icon">🛒 {totalItems}</div>
}

// src/components/ProductCard.tsx
// Only re-renders when addToCart reference changes (it doesn't)
import { useCartStore } from '@/store/cartStore'

export function ProductCard({ product }: { product: Product }) {
  const addToCart = useCartStore(state => state.addToCart)
  const [justAdded, setJustAdded] = useState(false)

  function handleAdd() {
    addToCart(product)
    setJustAdded(true)
    setTimeout(() => setJustAdded(false), 1500)
  }

  return (
    <div className="product-card">
      <h3>{product.name}</h3>
      <p>€{product.price.toFixed(2)}</p>
      <button onClick={handleAdd} disabled={justAdded}>
        {justAdded ? 'Added!' : 'Add to Cart'}
      </button>
    </div>
  )
}

// src/components/CartSidebar.tsx
// Re-renders when cartItems changes, which is exactly when it should
import { useCartStore } from '@/store/cartStore'

export function CartSidebar() {
  const cartItems = useCartStore(state => state.cartItems)
  const removeFromCart = useCartStore(state => state.removeFromCart)
  const totalPrice = useCartStore(state => state.totalPrice())

  return (
    <aside className="cart-sidebar">
      {cartItems.map(item => (
        <div key={item.product.id}>
          <span>{item.product.name} × {item.quantity}</span>
          <button onClick={() => removeFromCart(item.product.id)}>
            Remove
          </button>
        </div>
      ))}
      <p>Total: €{totalPrice.toFixed(2)}</p>
    </aside>
  )
}

No Provider. No wrapping. No prop drilling. Each component subscribes to exactly the slice it needs.

CartIcon does not re-render when cartItems changes, it only re-renders when totalItems() returns a different value. That's the performance win Context can't give you without significant extra work.

What Zustand adds beyond Context

Selective subscriptions: components only re-render for the state they care about.
No provider required: the store lives outside the component tree, accessible anywhere, including outside React (utility functions, event handlers, tests).
Actions co-located with state: logic lives in the store, not scattered across components or context files.
Middleware support: you can add persist (localStorage sync), devtools (Redux DevTools integration), or immer (immutable update syntax) with one line each.

// Adding persistence in one line
import { persist } from 'zustand/middleware'

export const useCartStore = create<CartState>()(
  persist(
    (set, get) => ({
      // ...same store definition
    }),
    { name: 'cart-storage' } // key in localStorage
  )
)

The cart now survives page refreshes. With Context, you'd need to wire this manually.

Where Redux Fits (and Where It Doesn't)

Redux is the elephant in the room of React state management. For years, it was the default answer. It's worth being precise about when it's still the right one.

Redux earns its complexity when you have:

A large team with strict data flow requirements. Redux's unidirectional data flow and explicit action types make state changes auditable and predictable. In a team of twenty developers, that discipline has real value.

Complex state interactions with time-travel debugging needs. The Redux DevTools' ability to replay actions and inspect state at every step is genuinely powerful for debugging complex flows.

An existing Redux codebase. Migrating away from Redux has a cost. If the codebase is well-structured and the team knows it, the cost of switching often outweighs the benefits.

Where Redux is usually the wrong choice:

New projects without an existing Redux investment.
Small to medium teams where the boilerplate overhead slows everyone down.
Apps where Zustand or Context would solve the actual problem with less ceremony.

Redux Toolkit has significantly reduced the boilerplate of modern Redux, if you're using Redux, you should be using Redux Toolkit. But even with Toolkit, Zustand remains simpler for the majority of use cases that don't require Redux's specific strengths.

The Decision Tree

Here's the framework. When you're deciding where new state should live, walk through these questions in order:

Is this state used by only one component?
│
├── YES → useState
│         (local, ephemeral, no sharing needed)
│
└── NO → Is it shared, but changes infrequently
          (theme, locale, auth user, feature flags)?
          │
          ├── YES → Context API
          │         (low update frequency = no re-render problem)
          │
          └── NO → Does it change frequently, or do
                    many components subscribe independently?
                    │
                    ├── YES → Zustand
                    │         (selective subscriptions, no re-render issues)
                    │
                    └── Is your team large (10+ devs), or do you need
                        strict auditability / time-travel debugging?
                        │
                        ├── YES → Redux Toolkit
                        │
                        └── NO  → Still Zustand

In practice, most apps end up using a combination:

useState for local UI state (open/closed, form inputs, loading indicators).
Context for static configuration (theme, i18n, auth).
Zustand for shared, dynamic state (cart, notifications, user session after login).

These three layers don't compete, they complement each other.

Quick reference

Tool	Best for	Watch out for
`useState`	Local, component-scoped state	Lifting too high - that's the signal to move on
Context API	Infrequently changing shared data	Re-renders when used for dynamic state
Zustand	Frequently updated shared state	Overkill for truly local state
Redux Toolkit	Large teams, complex flows, auditability	Boilerplate overhead in small/medium projects

Final Thoughts

The most common state management mistake isn't choosing the wrong tool.

It's reaching for a powerful tool before you've felt the pain that tool was designed to solve.

useState in a single component isn't a sign of inexperience. It's the right tool for the job, until the job changes. The same goes for Context, Zustand, and Redux. Each one exists because a real problem existed first.

The developers who write the most maintainable React code aren't the ones who know the most tools. They're the ones who can accurately identify which problem they're solving and match it to the simplest tool that solves it.

Start with useState. Feel the prop drilling. Add Context. Feel the re-renders. Add Zustand. Stop when the pain stops.

That's not laziness. That's the right process.

Which tool is your team currently using for state management, and does it match the problem you're actually solving?

Drop your setup in the comments. I'm especially curious about teams that migrated away from Redux: what pushed you over the edge?

If this was useful, a ❤️ or a 🦄 helps it reach more developers making this decision.
And follow along for the next article in the series.

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.

DEV Community: Gavin Cettolo

Clean API Design in Node.js: A Practical Guide

TL;DR

- Rate limiting, API versioning, and OpenAPI docs are not advanced topics — they're table stakes for any API that will be used by someone else.

Table of Contents

- Final Thoughts

What We're Building

Step 1: Project Structure

- lib/ — shared utilities with no framework dependency.

Step 2: The Express App Setup

Step 3: Routing and Controllers — Separating Concerns

Step 4: The Service Layer — Keeping Business Logic Out of Controllers

Step 5: Validation with Zod — Stop Trusting Your Inputs

Step 6: Centralized Error Handling

Step 7: Response Shaping — Consistent API Responses

Step 8: API Versioning

Step 9: Rate Limiting

Step 10: OpenAPI Documentation with Swagger

Why You Might Consider Fastify Instead

Final Thoughts

The 3 Types of Developers Every Team Has (And Why It Matters)

The 3 Types of Developers Every Team Has (And Why It Matters)

TL;DR

Table of Contents

A Note Before We Start

Type 1: The Lone Rocket

What the Lone Rocket brings

Where the Lone Rocket struggles

The context where they shine

As a tech lead

Type 2: The Glue Engineer

What the Glue Engineer brings

Where the Glue Engineer struggles

The context where they shine

As a tech lead

Type 3: The Big Picture Skeptic

What the Big Picture Skeptic brings

Where the Big Picture Skeptic struggles

The context where they shine

As a tech lead

Why the Mix Matters More Than the Individuals

What This Means for You as a Tech Lead

Final Thoughts

React State Management: When to Use useState, Context, or Zustand

TL;DR

Table of Contents

The Example We'll Use Throughout

Stage 1: useState: Local State Done Right

Stage 2: Prop Drilling and When It Actually Becomes a Problem

Stage 3: Context API - What It's Good For and Where It Breaks

The re-render problem

When Context is the right tool

Stage 4: Zustand, Shared State Without the Ceremony

What Zustand adds beyond Context

Where Redux Fits (and Where It Doesn't)

The Decision Tree

Quick reference

Final Thoughts

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

- `lib/` — shared utilities with no framework dependency.