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

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