nodejs-best-practices

Node.js Best Practices

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

When to Use

Use this skill when making Node.js architecture decisions, choosing frameworks, designing async patterns, or applying security and deployment best practices.

⚠️ 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

Module System Decision

Runtime Selection

3. Architecture Principles

Layered Structure Concept

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

Error Response Philosophy

Status Code Selection

5. Async Patterns Principles

When to Use Each

Event Loop Awareness

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

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

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+)

9. 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

10. 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.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.