Common Mistakes When Starting a Node.js Project (and How to Avoid Them)

Common Mistakes When Starting a Node.js Project

Most Node.js project failures are predictable. Here are the common mistakes and how to avoid them.

Mistake 1: Coding Without a Plan

You start typing before knowing what you build. Result: rework, scope creep, and a tangled codebase. Fix: write the vision, list features, sketch the database before coding.

Mistake 2: No Folder Structure

Everything lives in one file. Routes, handlers, models, config. Fix: split into folders: routes, controllers, models, middlewares, utils, config. Keep concerns separate.

Mistake 3: Secrets in Code

Database passwords and JWT secrets hardcoded in source files. Fix: use dotenv and .env files. Add .env to .gitignore. Never commit secrets.

Mistake 4: Skipping Input Validation

You trust the request body. Missing fields crash the server. Fix: validate input early with a library like zod or express-validator. Reject bad data at the door.

Mistake 5: No Error Handling

Errors crash the server or leak stack traces to users. Fix: use an error-handling middleware. Send safe error messages. Log the real error internally.

Mistake 6: Storing Passwords in Plain Text

Storing raw passwords is a disaster. Fix: hash with bcrypt before saving. Never log passwords. Never return passwords in responses.

Mistake 7: JWT in LocalStorage

LocalStorage is open to XSS. Fix: store JWT in an httpOnly, secure, sameSite cookie. This protects against XSS-driven token theft.

Mistake 8: No Health Check

You cannot tell if the server is alive. Fix: add GET /health that returns 200 OK. Useful for uptime monitors and load balancers.

Mistake 9: Blocking the Event Loop

Heavy sync code or huge loops block the event loop. Fix: keep handlers async. Offload heavy work to worker threads or background jobs.

Mistake 10: No Logging

No logs means no way to debug in production. Fix: add a logger (winston or pino). Log errors, warnings, and important events. Do not use console.log in production.

The Takeaway

Common mistakes: no plan, no folder structure, secrets in code, no validation, no error handling, plain-text passwords, JWT in LocalStorage, no health check, blocking the event loop, and no logging. Avoid these from day one.