Node.js Best Practices

// Recommended project structure
my-api/
├── src/
│   ├── config/        # Configuration files
│   │   └── index.js
│   ├── controllers/   # Request handlers
│   │   └── userController.js
│   ├── middleware/     # Custom middleware
│   │   ├── auth.js
│   │   └── errorHandler.js
│   ├── models/        # Database models
│   │   └── User.js
│   ├── routes/        # Route definitions
│   │   ├── index.js
│   │   └── userRoutes.js
│   ├── utils/         # Helper functions
│   │   └── AppError.js
│   └── app.js         # Express app setup
├── tests/             # Test files
├── .env               # Environment variables (never committed)
├── .env.example       # Template for .env (always committed)
├── .gitignore
├── package.json
└── server.js          # Entry point: config, DB connect, app.listen


// Once there are several resources, group by FEATURE rather than by layer:
src/
├── books/
│   ├── book.routes.js
│   ├── book.service.js
│   └── book.model.js
├── auth/
│   ├── auth.routes.js
│   └── auth.service.js
├── middleware/
├── config/
└── app.js

// A change is nearly always about one feature and almost never about
// "all routes", so one folder to open beats four.

// npm install helmet cors express-rate-limit

const express = require('express');
const helmet = require('helmet');
const cors = require('cors');
const rateLimit = require('express-rate-limit');

const app = express();

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

// CORS
app.use(cors({ origin: process.env.CORS_ORIGIN }));

// Rate limiting
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Max 100 requests per window
  message: { error: 'Too many requests, try again later' }
});
app.use('/api', limiter);

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

// Much tighter limits on the routes that get attacked first
const authLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 10 });
app.use('/api/auth/login', authLimiter);
app.use('/api/auth/forgot-password', authLimiter);

// Behind a proxy, this is what lets rate limiting see real client addresses
// app.set('trust proxy', 1);

// Dependency hygiene
//   npm audit            read it; judge each finding by where that package runs
//   npm ci               reproducible installs, straight from the lock file
//   npm ci --omit=dev    production installs skip devDependencies

// Least privilege: the application's database user should not be able to drop
// tables, and your test API keys should not carry production scope.

// A structured logger, configured once
const pino = require('pino');
const logger = pino({ level: process.env.LOG_LEVEL || 'info' });

// A request id, attached to everything this request produces
const crypto = require('node:crypto');
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] || crypto.randomUUID();
  req.log = logger.child({ requestId: req.id });
  res.setHeader('X-Request-Id', req.id);
  next();
});

app.post('/api/orders', async (req, res, next) => {
  req.log.info({ userId: req.user.id }, 'creating order');
  try {
    const order = await createOrder(req.user.id, req.body);
    req.log.info({ orderId: order.id }, 'order created');
    res.status(201).json(order);
  } catch (err) {
    req.log.error({ err }, 'order failed');   // logged once, where it is handled
    next(err);
  }
});

// NEVER:
// logger.info({ body: req.body });   // passwords, tokens, card numbers
// logger.info({ user });             // the whole document, hash included
// console.log('token', token);

// Log an error where you handle it, not at every level it passes through,
// or one failure produces six near-identical entries and none of them helps.

// npm install --save-dev supertest
// package.json:  "test": "node --test"

const test = require('node:test');
const assert = require('node:assert');
const request = require('supertest');

const app = require('../src/app');   // imported, NOT started — see lesson 8

test('GET /api/books returns an array', async () => {
  const res = await request(app).get('/api/books');
  assert.strictEqual(res.status, 200);
  assert.ok(Array.isArray(res.body));
});

test('POST /api/books rejects a missing title', async () => {
  const res = await request(app)
    .post('/api/books')
    .send({ author: 'Frank Herbert' });
  assert.strictEqual(res.status, 400);      // 400, not 500
});

test('GET /api/books/9999 is a 404, not a crash', async () => {
  const res = await request(app).get('/api/books/9999');
  assert.strictEqual(res.status, 404);
});

// Services are plain functions — no HTTP, no server, nothing to mock
const { calculateTotal } = require('../src/services/orderService');

test('calculateTotal applies the discount once', () => {
  assert.strictEqual(calculateTotal([{ price: 100 }, { price: 50 }], 0.1), 135);
});

// Measure first. The answer is nearly always one of three things.
console.time('query');
const rows = await findBooks(filter);
console.timeEnd('query');

// 1. Never block the request path
// const config = JSON.parse(fs.readFileSync('config.json'));  // fine at STARTUP
app.get('/report', (req, res) => {
  // const data = fs.readFileSync(bigFile);   // blocks every other request
});

// 2. Stream large files instead of buffering them into memory
const fs = require('node:fs');
app.get('/export.csv', (req, res) => {
  res.setHeader('Content-Type', 'text/csv');
  fs.createReadStream('/data/export.csv')
    .on('error', () => res.status(500).end())
    .pipe(res);                    // memory stays flat, whatever the file size
});

// 3. A health endpoint that actually means something
app.get('/health', async (req, res) => {
  try {
    await pingDatabase();
    res.json({ status: 'ok' });
  } catch {
    res.status(503).json({ status: 'degraded' });
  }
});

// More than one process means no shared memory. Anything in a module-level
// variable is per-process from that moment on — move it to a database or cache.