nodebestpractices

Node.js Best Practices

🎊 2026 edition is here!

Welcome! 3 Things You Ought To Know First

By Yoni Goldberg

Table of Contents

`1. Project Architecture Practices`

![✔] 1.1 Structure your solution by business components

![✔] 1.2 Layer your components with 3-tiers, keep the web layer within its boundaries

![✔] 1.3 Wrap common utilities as packages, consider publishing

![✔] 1.4 Use environment aware, secure and hierarchical config

![✔] 1.5 Consider all the consequences when choosing the main framework

![✔] 1.6 Use TypeScript sparingly and thoughtfully

`2. Error Handling Practices`

![✔] 2.1 Use Async-Await or promises for async error handling

![✔] 2.2 Extend the built-in Error object

![✔] 2.3 Distinguish catastrophic errors from operational errors

![✔] 2.4 Handle errors centrally, not within a middleware

![✔] 2.5 Document API errors using OpenAPI or GraphQL

![✔] 2.6 Exit the process gracefully when a stranger comes to town

![✔] 2.7 Use a mature logger to increase errors visibility

![✔] 2.8 Test error flows using your favorite test framework

![✔] 2.9 Discover errors and downtime using APM products

![✔] 2.10 Catch unhandled promise rejections

![✔] 2.11 Fail fast, validate arguments using a dedicated library

![✔] 2.12 Always await promises before returning to avoid a partial stacktrace

![✔] 2.13 Subscribe to event emitters and streams 'error' event

`3. Code Patterns And Style Practices`

![✔] 3.1 Use ESLint

![✔] 3.2 Use Node.js eslint extension plugins

![✔] 3.3 Start a Codeblock's Curly Braces on the Same Line

![✔] 3.4 Separate your statements properly

![✔] 3.5 Name your functions

![✔] 3.6 Use naming conventions for variables, constants, functions and classes

![✔] 3.7 Prefer const over let. Ditch the var

![✔] 3.8 Require modules first, not inside functions

![✔] 3.9 Set an explicit entry point to a module/folder

![✔] 3.10 Use the `===` operator

![✔] 3.11 Use Async Await, avoid callbacks

![✔] 3.12 Use arrow function expressions (=>)

![✔] 3.13 Avoid effects outside of functions

`4. Testing And Overall Quality Practices`

![✔] 4.1 At the very least, write API (component) testing

![✔] 4.2 Include 3 parts in each test name

![✔] 4.3 Structure tests by the AAA pattern

![✔] 4.4 Ensure Node version is unified

![✔] 4.5 Avoid global test fixtures and seeds, add data per-test

![✔] 4.6 Tag your tests

![✔] 4.7 Check your test coverage, it helps to identify wrong test patterns

![✔] 4.8 Use production-like environment for e2e testing

![✔] 4.9 Refactor regularly using static analysis tools

![✔] 4.10 Mock responses of external HTTP services

![✔] 4.11 Test your middlewares in isolation

![✔] 4.12 Specify a port in production, randomize in testing

![✔] 4.13 Test the five possible outcomes

`5. Going To Production Practices`

![✔] 5.1. Monitoring

![✔] 5.2. Increase the observability using smart logging

![✔] 5.3. Delegate anything possible (e.g. gzip, SSL) to a reverse proxy

![✔] 5.4. Lock dependencies

![✔] 5.5. Guard process uptime using the right tool

![✔] 5.6. Utilize all CPU cores

![✔] 5.7. Create a ‘maintenance endpoint’

![✔] 5.8. Discover the unknowns using APM products

![✔] 5.9. Make your code production-ready

![✔] 5.10. Measure and guard the memory usage

![✔] 5.11. Get your frontend assets out of Node

![✔] 5.12. Strive to be stateless

![✔] 5.13. Use tools that automatically detect vulnerabilities

![✔] 5.14. Assign a transaction id to each log statement

![✔] 5.15. Set `NODEENV=production`

![✔] 5.16. Design automated, atomic and zero-downtime deployments

![✔] 5.17. Use an LTS release of Node.js

![✔] 5.18. Log to stdout, avoid specifying log destination within the app

![✔] 5.19. Install your packages with `npm ci`

`6. Security Best Practices`

![✔] 6.1. Embrace linter security rules

![✔] 6.2. Limit concurrent requests using a middleware

![✔] 6.3 Extract secrets from config files or use packages to encrypt them

![✔] 6.4. Prevent query injection vulnerabilities with ORM/ODM libraries

![✔] 6.5. Collection of generic security best practices

![✔] 6.6. Adjust the HTTP response headers for enhanced security

![✔] 6.7. Constantly and automatically inspect for vulnerable dependencies

![✔] 6.8. Protect Users' Passwords/Secrets using bcrypt or scrypt

![✔] 6.9. Escape HTML, JS and CSS output

![✔] 6.10. Validate incoming JSON schemas

![✔] 6.11. Support blocklisting JWTs

![✔] 6.12. Prevent brute-force attacks against authorization

![✔] 6.13. Run Node.js as non-root user

![✔] 6.14. Limit payload size using a reverse-proxy or a middleware

![✔] 6.15. Avoid JavaScript eval statements

![✔] 6.16. Prevent evil RegEx from overloading your single thread execution

![✔] 6.17. Avoid module loading using a variable

![✔] 6.18. Run unsafe code in a sandbox

![✔] 6.19. Take extra care when working with child processes

![✔] 6.20. Hide error details from clients

![✔] 6.21. Configure 2FA for npm or Yarn

![✔] 6.22. Modify session middleware settings

![✔] 6.23. Avoid DOS attacks by explicitly setting when a process should crash

![✔] 6.24. Prevent unsafe redirects

![✔] 6.25. Avoid publishing secrets to the npm registry

![✔] 6.26 Inspect for outdated packages

![✔] 6.27. Import built-in modules using the 'node:' protocol

`7. Draft: Performance Best Practices`

Our contributors are working on this section. Would you like to join?

![✔] 7.1. Don't block the event loop

![✔] 7.2. Prefer native JS methods over user-land utils like Lodash

`8. Docker Best Practices`

![✔] 8.1 Use multi-stage builds for leaner and more secure Docker images

![✔] 8.2. Bootstrap using `node` command, avoid `npm start`

![✔] 8.3. Let the Docker runtime handle replication and uptime

![✔] 8.4. Use .dockerignore to prevent leaking secrets

![✔] 8.5. Clean-up dependencies before production

![✔] 8.6. Shutdown smartly and gracefully

![✔] 8.7. Set memory limits using both Docker and v8

![✔] 8.8. Plan for efficient caching

![✔] 8.9. Use explicit image reference, avoid `latest` tag

![✔] 8.10. Prefer smaller Docker base images

![✔] 8.11. Clean-out build-time secrets, avoid secrets in args

![✔] 8.12. Scan images for multi layers of vulnerabilities

![✔] 8.13 Clean NODEMODULE cache

![✔] 8.14. Generic Docker practices

![✔] 8.15. Lint your Dockerfile

Milestones

Translations

Steering Committee

Contributing

Contributors ✨