nodejs-best-practices

Node.js Best Practices

Comprehensive guide for Node.js and Fastify applications, maintained by Nearform. Contains 48 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Node.js APIs or Fastify routes
• Implementing database operations
• Reviewing code for performance or security issues
• Refactoring existing Node.js/Fastify code
• Optimizing API response times
• Handling errors and logging
• Setting up monitoring and observability

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Performance & Security	CRITICAL	perf-
2	API Design & Database	CRITICAL	api-
3	Error Handling & Logging	HIGH	error-
4	Fastify Optimization	MEDIUM-HIGH	fastify-
5	Async Patterns	MEDIUM	async-
6	Caching & State	MEDIUM	cache-
7	Code Organization	LOW-MEDIUM	code-
8	Monitoring & Diagnostics	LOW	monitor-

Quick Reference

1. Performance & Security (CRITICAL)

• perf-block-event-loop - Detect and prevent event loop blocking
• perf-security-headers - Implement essential security headers
• perf-input-validation - Validate and sanitize all inputs
• perf-streaming - Use streams for large payloads
• perf-memory-leaks - Prevent memory leaks
• perf-compression - Implement compression strategies

2. API Design & Database (CRITICAL)

• api-rest-design - Follow RESTful design principles
• api-pagination - Implement efficient pagination
• api-connection-pooling - Use connection pooling
• api-query-optimization - Optimize database queries
• api-n-plus-one - Prevent N+1 query problems
• api-transactions - Handle transactions properly

3. Error Handling & Logging (HIGH)

• error-middleware - Centralize error handling
• error-structured-logging - Use structured logging (Pino)
• error-async-errors - Handle async errors properly
• error-sensitive-data - Don't leak sensitive data in errors
• error-unhandled-rejection - Handle unhandled rejections
• error-request-logging - Log requests efficiently

4. Fastify Optimization (MEDIUM-HIGH)

• fastify-schema-validation - Use JSON schema validation
• fastify-hooks - Optimize hook usage
• fastify-plugins - Design reusable plugins
• fastify-decorators - Use decorators effectively
• fastify-serialization - Optimize JSON serialization
• fastify-content-type - Handle content types properly

5. Async Patterns (MEDIUM)

• async-parallel - Parallelize independent operations
• async-error-handling - Handle async errors gracefully
• async-backpressure - Handle backpressure in streams
• async-rate-limiting - Implement rate limiting
• async-queue-management - Use queues for background jobs
• async-timeout - Set timeouts for operations

6. Caching & State (MEDIUM)

• cache-lru - Use in-memory LRU caching
• cache-redis - Implement Redis caching
• cache-http-headers - Use HTTP caching headers
• cache-invalidation - Implement cache invalidation
• cache-stale-revalidate - Use stale-while-revalidate pattern
• cache-database - Cache database queries

7. Code Organization (LOW-MEDIUM)

• code-module-structure - Organize code by feature
• code-dependency-injection - Use dependency injection
• code-config-management - Manage configuration properly
• code-env-variables - Handle environment variables
• code-testing - Write testable code
• code-typescript - Use TypeScript effectively

8. Monitoring & Diagnostics (LOW)

• monitor-health-check - Implement health check endpoints
• monitor-metrics - Collect application metrics
• monitor-apm - Integrate APM tools
• monitor-memory - Monitor memory usage
• monitor-cpu - Profile CPU usage
• monitor-distributed-tracing - Implement distributed tracing

How to Use

Read individual rule files for detailed explanations and code examples:

rules/perf-block-event-loop.md
rules/api-n-plus-one.md
rules/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md