Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
when_to_use
When building Node.js backends, selecting frameworks (Express/Fastify/NestJS), or implementing async patterns.
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
Factor
Hono
Fastify
Express
Best for
Edge, serverless
Performance
Legacy, learning
Cold start
Fastest
Fast
Moderate
Ecosystem
Growing
Good
Largest
TypeScript
Native
Excellent
Good
Learning curve
Low
Medium
Low
Selection Questions to Ask:
What's the deployment target?
Is cold start time critical?
Does team have existing experience?
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
Runtime
Best For
Node.js
General purpose, largest ecosystem
Bun
Performance, built-in bundler
Deno
Security-first, built-in TypeScript
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
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
Library
Best For
Zod
TypeScript first, inference
Valibot
Smaller bundle (tree-shakeable)
ArkType
Performance critical
Yup
Existing React Form usage
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
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.
