nodejs-best-practices

Node.js Best Practices

"Node.js excels when you respect its single-threaded, event-driven nature; fight it and you lose."

When to Use

• Building Node.js backend services or APIs
• Reviewing Node.js code for anti-patterns and security issues
• Optimizing Node.js application performance
• Structuring a new Node.js project
• Handling errors, logging, and graceful shutdown

Project Structure

Layered Architecture

src/
  config/           # Environment config, constants
  routes/           # Route definitions (Express/Fastify)
  controllers/      # Request handling, input validation
  services/         # Business logic (framework-agnostic)
  repositories/     # Data access layer (DB queries)
  middleware/       # Auth, rate limiting, error handling
  models/           # Database models / schemas
  utils/            # Pure utility functions
  types/            # TypeScript type definitions
  jobs/             # Background jobs, cron tasks
  __tests__/        # Test files mirroring src structure

Key Principles

• Separate business logic from framework code; services should not import Express
• Each module exports a clear interface; avoid circular dependencies
• Use dependency injection for testability (pass dependencies as function/constructor args)
• Keep the entry point (index.ts / app.ts) thin: wire up middleware, routes, and start server

Async/Await Patterns

Always Use async/await Over Raw Callbacks

• Never mix callbacks and promises in the same flow
• Use util.promisify() to convert legacy callback APIs
• Avoid the async/await + .then() hybrid; choose one style

Parallel Execution

• Use Promise.all() when all promises are independent and all must succeed
• Use Promise.allSettled() when you need results from all, even if some fail
• Use Promise.race() for timeouts: race the operation against a timer promise
• Limit concurrency for bulk operations with p-limit or p-map

Common Pitfalls

• Forgetting await: const data = fetchData() returns a Promise, not data
• Await inside loops: sequential when you want parallel; use Promise.all with map instead
• Unhandled promise rejections: always catch at the top level or use process event handlers
• Async functions always return promises; do not mix with synchronous return expectations