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 blockingperf-security-headers- Implement essential security headersperf-input-validation- Validate and sanitize all inputsperf-streaming- Use streams for large payloadsperf-memory-leaks- Prevent memory leaksperf-compression- Implement compression strategies
2. API Design & Database (CRITICAL)
api-rest-design- Follow RESTful design principlesapi-pagination- Implement efficient paginationapi-connection-pooling- Use connection poolingapi-query-optimization- Optimize database queriesapi-n-plus-one- Prevent N+1 query problemsapi-transactions- Handle transactions properly
3. Error Handling & Logging (HIGH)
error-middleware- Centralize error handlingerror-structured-logging- Use structured logging (Pino)error-async-errors- Handle async errors properlyerror-sensitive-data- Don't leak sensitive data in errorserror-unhandled-rejection- Handle unhandled rejectionserror-request-logging- Log requests efficiently
4. Fastify Optimization (MEDIUM-HIGH)
fastify-schema-validation- Use JSON schema validationfastify-hooks- Optimize hook usagefastify-plugins- Design reusable pluginsfastify-decorators- Use decorators effectivelyfastify-serialization- Optimize JSON serializationfastify-content-type- Handle content types properly
5. Async Patterns (MEDIUM)
async-parallel- Parallelize independent operationsasync-error-handling- Handle async errors gracefullyasync-backpressure- Handle backpressure in streamsasync-rate-limiting- Implement rate limitingasync-queue-management- Use queues for background jobsasync-timeout- Set timeouts for operations
6. Caching & State (MEDIUM)
cache-lru- Use in-memory LRU cachingcache-redis- Implement Redis cachingcache-http-headers- Use HTTP caching headerscache-invalidation- Implement cache invalidationcache-stale-revalidate- Use stale-while-revalidate patterncache-database- Cache database queries
7. Code Organization (LOW-MEDIUM)
code-module-structure- Organize code by featurecode-dependency-injection- Use dependency injectioncode-config-management- Manage configuration properlycode-env-variables- Handle environment variablescode-testing- Write testable codecode-typescript- Use TypeScript effectively
8. Monitoring & Diagnostics (LOW)
monitor-health-check- Implement health check endpointsmonitor-metrics- Collect application metricsmonitor-apm- Integrate APM toolsmonitor-memory- Monitor memory usagemonitor-cpu- Profile CPU usagemonitor-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.mdEach 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