How to Structure a Small Node.js API in 2026

Overview: Building a small API doesn't mean sacrificing quality. This guide lays out a pragmatic folder structure, recommended dependencies, testing approach, and deployment strategy that scales from prototypes to production-ready microservices.

Principles

• Keep it simple: Favor small, readable modules over clever abstractions.
• Test first: Unit tests for logic and integration tests for endpoints prevent regressions.
• Automate: CI runs tests, linters, and builds images for deployment.
• Observable: Logging and metrics are essential; instrument early.

Suggested folder layout

/src
  /api         // route definitions
  /controllers // request orchestration
  /services    // domain logic
  /models      // data shapes and ORM or query helpers
  /utils       // helpers
  /config      // configuration per environment
/tests         // unit and integration tests

Why this split?

This layout mirrors responsibilities. Controllers coordinate request/response, services contain business logic, and models handle persistence. Tests live separately to avoid accidental production imports and to make the test runner configuration explicit.

Dependencies we recommend

• Server: Fastify (lightweight, performant) or Express for familiarity.
• ORM/Query: Prisma for type-safe queries or Knex for query building.
• Testing: Vitest or Jest + Supertest for endpoint tests.
• Validation: Zod for runtime schema validation and parsing.
• Logging: Pino for structured logs.

Example controller

Controllers should be thin. Validate input, call service, and handle response. Keep error handling centralized so controllers remain focused on orchestration.

Testing strategy

Create unit tests for services and integration tests for routes. Use test doubles for external systems where possible. For database tests, use a lightweight test database or an in-memory option and reset state between tests.

Environment and config

Use environment variables with a small config module that validates required values at startup using Zod. Avoid scattering process.env across the codebase.

Deployment

Build containers with multi-stage Dockerfiles to keep images small. Deploy to a managed container service or a serverless platform. Use health-check endpoints and readiness probes, and ensure graceful shutdown logic is implemented for connection draining.

Observability

Emit structured logs and track request durations and error rates. Integrate lightweight metrics like Prometheus client or push metrics to your cloud provider. Correlate logs with request ids for easier debugging.

Sample checklist before going to production

• Automated tests passing on CI
• Linting and formatting applied
• Secrets stored in a secrets manager
• Health & readiness probes implemented
• Alerts configured on error rates and latency

Conclusion: A small Node.js API can be robust and maintainable with modest investment in structure, testing, and observability. Prioritize ergonomics for your team and incrementally add complexity as the project grows.