Node.js Best Practices

Principles and decision-making for Node.js development in 2025. Learn to THINK, not memorize code patterns.

⚠️ How to Use This Skill

This skill teaches decision-making principles, not fixed code to copy.

• •ASK user for preferences when unclear
• •Choose framework/pattern based on CONTEXT
• •Don't default to same solution every time

1. Framework Selection (2025)

Decision Tree

What are you building?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, ultra-fast cold starts)
│
├── High Performance API
│   └── Fastify (2-3x faster than Express)
│
├── Enterprise/Team familiarity
│   └── NestJS (structured, DI, decorators)
│
├── Legacy/Stable/Maximum ecosystem
│   └── Express (mature, most middleware)
│
└── Full-stack with frontend
    └── Next.js API Routes or tRPC

Comparison Principles

Selection Questions to Ask:

1. •What's the deployment target?
2. •Is cold start time critical?
3. •Does team have existing experience?
4. •Is there legacy code to maintain?

2. Runtime Considerations (2025)

Native TypeScript

Node.js 22+: --experimental-strip-types
├── Run .ts files directly
├── No build step needed for simple projects
└── Consider for: scripts, simple APIs

Module System Decision

ESM (import/export)
├── Modern standard
├── Better tree-shaking
├── Async module loading
└── Use for: new projects

CommonJS (require)
├── Legacy compatibility
├── More npm packages support
└── Use for: existing codebases, some edge cases

Runtime Selection

3. Architecture Principles

Layered Structure Concept

Request Flow:
│
├── Controller/Route Layer
│   ├── Handles HTTP specifics
│   ├── Input validation at boundary
│   └── Calls service layer
│
├── Service Layer
│   ├── Business logic
│   ├── Framework-agnostic
│   └── Calls repository layer
│
└── Repository Layer
    ├── Data access only
    ├── Database queries
    └── ORM interactions

Why This Matters:

• •Testability: Mock layers independently
• •Flexibility: Swap database without touching business logic
• •Clarity: Each layer has single responsibility

When to Simplify:

• •Small scripts -> Single file OK
• •Prototypes -> Less structure acceptable
• •Always ask: "Will this grow?"

4. Error Handling Principles

Centralized Error Handling

Pattern:
├── Create custom error classes
├── Throw from any layer
├── Catch at top level (middleware)
└── Format consistent response

Error Response Philosophy

Client gets:
├── Appropriate HTTP status
├── Error code for programmatic handling
├── User-friendly message
└── NO internal details (security!)

Logs get:
├── Full stack trace
├── Request context
├── User ID (if applicable)
└── Timestamp

Status Code Selection

5. Async Patterns Principles

When to Use Each

Event Loop Awareness

I/O-bound (async helps):
├── Database queries
├── HTTP requests
├── File system
└── Network operations

CPU-bound (async doesn't help):
├── Crypto operations
├── Image processing
├── Complex calculations
└── -> Use worker threads or offload

Avoiding Event Loop Blocking

• •Never use sync methods in production (fs.readFileSync, etc.)
• •Offload CPU-intensive work
• •Use streaming for large data

6. Validation Principles

Validate at Boundaries

Where to validate:
├── API entry point (request body/params)
├── Before database operations
├── External data (API responses, file uploads)
└── Environment variables (startup)

Validation Library Selection

Validation Philosophy

• •Fail fast: Validate early
• •Be specific: Clear error messages
• •Don't trust: Even "internal" data

7. Security Principles

Security Checklist (Not Code)

• • Input validation: All inputs validated
• • Parameterized queries: No string concatenation for SQL
• • Password hashing: bcrypt or argon2
• • JWT verification: Always verify signature and expiry
• • Rate limiting: Protect from abuse
• • Security headers: Helmet.js or equivalent
• • HTTPS: Everywhere in production
• • CORS: Properly configured
• • Secrets: Environment variables only
• • Dependencies: Regularly audited

Security Mindset

Trust nothing:
├── Query params -> validate
├── Request body -> validate
├── Headers -> verify
├── Cookies -> validate
├── File uploads -> scan
└── External APIs -> validate response

8. Testing Principles

Test Strategy Selection

What to Test (Priorities)

1. •Critical paths: Auth, payments, core business
2. •Edge cases: Empty inputs, boundaries
3. •Error handling: What happens when things fail?
4. •Not worth testing: Framework code, trivial getters

Built-in Test Runner (Node.js 22+)

node --test src/**/*.test.ts
├── No external dependency
├── Good coverage reporting
└── Watch mode available

10. Anti-Patterns to Avoid

❌ DON'T:

• •Use Express for new edge projects (use Hono)
• •Use sync methods in production code
• •Put business logic in controllers
• •Skip input validation
• •Hardcode secrets
• •Trust external data without validation
• •Block event loop with CPU work

✅ DO:

• •Choose framework based on context
• •Ask user for preferences when unclear
• •Use layered architecture for growing projects
• •Validate all inputs
• •Use environment variables for secrets
• •Profile before optimizing

11. Decision Checklist

Before implementing:

• • Asked user about stack preference?
• • Chosen framework for THIS context? (not just default)
• • Considered deployment target?
• • Planned error handling strategy?
• • Identified validation points?
• • Considered security requirements?

Remember: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.