Follow us on Twitter! @nodepractices
1. When you read here, you in fact read dozens of the best Node.js articles - this is a summary and curation of the top-ranked content on Node.js best practices
2. It is the largest compilation, and it is growing every week - currently, more than 50 best practices, style guides, and architectural tips are presented. New issues and PR are created every day to keep this live book updated. We'd love to see you contributing here, whether fixing some code mistake or suggesting brilliant new ideas. See our milestones here
3. Most bullets have additional info - nearby most best practice bullets you'll find 🔗Read More link that will present you with code examples, quotes from selected blogs and more info
- Project structure Practices (5)
- Error Handling Practices (11)
- Code Style Practices (12)
- Testing And Overall Quality Practices (8)
- Going To Production Practices (16)
- Security Best Practices - Draft (22)
- Performance Practices (coming soon)
TL;DR: The worst large applications pitfall is maintaining a huge code base with hundreds of dependencies - such a monolith slows down developers as they try to incorporate new features. Instead, partition your code into components, each gets its own folder or a dedicated codebase, and ensure that each unit is kept small and simple. Visit 'Read More' below to see examples of correct project structure
Otherwise: When developers who code new features struggle to realize the impact of their change and fear to break other dependant components - deployments become slower and more risky. It's also considered harder to scale-out when all the business units are not separated
🔗 Read More: structure by components
TL;DR: Each component should contain 'layers' - a dedicated object for the web, logic and data access code. This not only draws a clean separation of concerns but also significantly eases mocking and testing the system. Though this is a very common pattern, API developers tend to mix layers by passing the web layer objects (Express req, res) to business logic and data layers - this makes your application dependant on and accessible by Express only
Otherwise: App that mixes web objects with other layers can not be accessed by testing code, CRON jobs and other non-Express callers
TL;DR: In a large app that constitutes a large code base, cross-cutting-concern utilities like logger, encryption and alike, should be wrapped by your own code and exposed as private NPM packages. This allows sharing them among multiple code bases and projects
Otherwise: You'll have to invent your own deployment and dependency wheel
🔗 Read More: Structure by feature
TL;DR: Avoid the nasty habit of defining the entire Express app in a single huge file - separate your 'Express' definition to at least two files: the API declaration (app.js) and the networking concerns (WWW). For even better structure, locate your API declaration within components
Otherwise: Your API will be accessible for testing via HTTP calls only (slower and much harder to generate coverage reports). It probably won't be a big pleasure to maintain hundreds of lines of code in a single file
🔗 Read More: separate Express 'app' and 'server'
TL;DR: A perfect and flawless configuration setup should ensure (a) keys can be read from file AND from environment variable (b) secrets are kept outside committed code (c) config is hierarchical for easier findability. There are a few packages that can help tick most of those boxes like rc, nconf and config.
Otherwise: Failing to satisfy any of the config requirements will simply bog down the development or devops team. Probably both
🔗 Read More: configuration best practices
TL;DR: Handling async errors in callback style is probably the fastest way to hell (a.k.a the pyramid of doom). The best gift you can give to your code is using a reputable promise library or async-await instead which enables a much more compact and familiar code syntax like try-catch
Otherwise: Node.js callback style, function(err, response), is a promising way to un-maintainable code due to the mix of error handling with casual code, excessive nesting and awkward coding patterns
🔗 Read More: avoiding callbacks
TL;DR: Many throws errors as a string or as some custom type – this complicates the error handling logic and the interoperability between modules. Whether you reject a promise, throw exception or emit error – using only the built-in Error object will increase uniformity and prevent loss of information
Otherwise: When invoking some component, being uncertain which type of errors come in return – it makes proper error handling much harder. Even worse, using custom types to describe errors might lead to loss of critical error information like the stack trace!
🔗 Read More: using the built-in error object
TL;DR: Operational errors (e.g. API received an invalid input) refer to known cases where the error impact is fully understood and can be handled thoughtfully. On the other hand, programmer error (e.g. trying to read undefined variable) refers to unknown code failures that dictate to gracefully restart the application
Otherwise: You may always restart the application when an error appears, but why let ~5000 online users down because of a minor, predicted, operational error? the opposite is also not ideal – keeping the application up when an unknown issue (programmer error) occurred might lead to an unpredicted behavior. Differentiating the two allows acting tactfully and applying a balanced approach based on the given context
🔗 Read More: operational vs programmer error
TL;DR: Error handling logic such as mail to admin and logging should be encapsulated in a dedicated and centralized object that all endpoints (e.g. Express middleware, cron jobs, unit-testing) call when an error comes in.
Otherwise: Not handling errors within a single place will lead to code duplication and probably to improperly handled errors
🔗 Read More: handling errors in a centralized place
TL;DR: Let your API callers know which errors might come in return so they can handle these thoughtfully without crashing. This is usually done with REST API documentation frameworks like Swagger
Otherwise: An API client might decide to crash and restart only because he received back an error he couldn’t understand. Note: the caller of your API might be you (very typical in a microservice environment)
🔗 Read More: documenting errors in Swagger
TL;DR: When an unknown error occurs (a developer error, see best practice number #3)- there is uncertainty about the application healthiness. A common practice suggests restarting the process carefully using a ‘restarter’ tool like Forever and PM2
Otherwise: When an unfamiliar exception is caught, some object might be in a faulty state (e.g an event emitter which is used globally and not firing events anymore due to some internal failure) and all future requests might fail or behave crazily
🔗 Read More: shutting the process
TL;DR: A set of mature logging tools like Winston, Bunyan or Log4J, will speed-up error discovery and understanding. So forget about console.log.
Otherwise: Skimming through console.logs or manually through messy text file without querying tools or a decent log viewer might keep you busy at work until late
🔗 Read More: using a mature logger
TL;DR: Whether professional automated QA or plain manual developer testing – Ensure that your code not only satisfies positive scenario but also handle and return the right errors. Testing frameworks like Mocha & Chai can handle this easily (see code examples within the "Gist popup")
Otherwise: Without testing, whether automatically or manually, you can’t rely on our code to return the right errors. Without meaningful errors – there’s no error handling
🔗 Read More: testing error flows
TL;DR: Monitoring and performance products (a.k.a APM) proactively gauge your codebase or API so they can auto-magically highlight errors, crashes and slow parts that you were missing
Otherwise: You might spend great effort on measuring API performance and downtimes, probably you’ll never be aware which are your slowest code parts under real world scenario and how these affects the UX
🔗 Read More: using APM products
TL;DR: Any exception thrown within a promise will get swallowed and discarded unless a developer didn’t forget to explicitly handle. Even if your code is subscribed to process.uncaughtException! Overcome this by registering to the event process.unhandledRejection
Otherwise: Your errors will get swallowed and leave no trace. Nothing to worry about
🔗 Read More: catching unhandled promise rejection
TL;DR: This should be part of your Express best practices – Assert API input to avoid nasty bugs that are much harder to track later. Validation code is usually tedious unless using a very cool helper libraries like Joi
Otherwise: Consider this – your function expects a numeric argument “Discount” which the caller forgets to pass, later on your code checks if Discount!=0 (amount of allowed discount is greater than zero), then it will allow the user to enjoy a discount. OMG, what a nasty bug. Can you see it?
TL;DR: ESLint is the de-facto standard for checking code style, not only to identify nitty-gritty spacing issues but also to detect serious code anti-patterns like developers throwing errors without classification. Using ESLint and following the rest of the code style practices below means following the same styles used by the rest of the community, as well as the same code styles used in the core products themselves.
Otherwise: developers will focus on tedious spacing and line-width concerns
TL;DR: On top of ESLint standard rules that cover vanilla JS only, add Node-specific plugins like eslint-plugin-node, eslint-plugin-mocha and eslint-plugin-node-security
Otherwise: Many faulty Node.js code patterns might escape under the radar. For example, developers might require(variableAsPath) files with a variable given as path which allows attackers to execute any JS script. Node.js linters can detect such patterns and complain early
TL;DR: The opening curly braces of a code block should be in the same line of the opening statement.
// Do
function someFunction() {
// code block
}
// Avoid
function someFunction()
{
// code block
}Otherwise: Deferring from this best practice might lead to unexpected results, as seen in the Stackoverflow thread below:
🔗 Read more: "Why does a results vary based on curly brace placement?" (Stackoverflow)
TL;DR: While not unanimously agreed upon, it is still recommended to put a semicolon at the end of each statement. This will make your code more readable and explicit to other developers who read it.
Otherwise: As seen in the previous section, JavaScript's interpreter automatically adds a semicolon at the end of a statement if there isn't one which might lead to some undesired results.
TL;DR: Name all functions, including closures and callbacks. Avoid anonymous functions. This is especially useful when profiling a Node.js application. Naming all functions will allow you to easily understand what you're looking at when checking a memory snapshot.
Otherwise: Debugging production issues using a core dump (memory snapshot) might become challenging as you notice significant memory consumption from anonymous functions.
TL;DR: Use lowerCamelCase when naming variables and functions, UpperCamelCase (capital first letter as well) when naming classes and UPPERCASE for constants. This will help you to easily distinguish between plain variables / functions, and classes that require instantiation. Use descriptive names, but try to keep them short.
Otherwise: Javascript is the only language in the world which allows to invoke a constructor ("Class") directly without instantiating it first. Consequently, Classes and function-constructors are differentiated by starting with UpperCamelCase.
// for class name we use UpperCamelCase
class SomeClassExample {
// for const name we use UPPERCASE
const CONFIG = {
key: 'value'
};
// for variables and functions names we use lowerCamelCase
let someVariableExample = 'value';
function doSomething() {
}
}TL;DR: Using const means that once a variable is assigned, it cannot be reassigned. Preferring const will help you to not be tempted to use the same variable for different uses, and make your code clearer. If a variable needs to be reassigned, in a for loop for example, use let to declare it. Another important aspect of let is that a variable declared using let is only available in the block scope in which it was defined. var is function scoped, not block scoped, and shouldn't be used in ES6 now that you have const and let at your disposal.
Otherwise: Debugging becomes way more cumbersome when following a variable that frequently changes.
🔗 Read more: JavaScript ES6+: var, let, or const?
TL;DR: Require modules at the beginning of each file, before and outside of any functions. This simple best practice will not only help you easily and quickly tell the dependencies of a file right at the top, but also avoids a couple of potential problems.
Otherwise: Requires are run synchronously by Node.js. If they are called from within a function, it may block other requests from being handled at a more critical time. Also, if a required module or any of its own dependencies throw an error and crash the server, it is best to find out about it as soon as possible, which might not be the case if that module is required from within a function.
TL;DR: When developing a module/library in a folder, place an index.js file that exposes the module's internals so every consumer will pass through it. This serves as an 'interface' to your module and ease future changes without breaking the contract.
Otherwise: Changing to the internal structure of files or the signature may break the interface with clients.
// Do
module.exports.SMSProvider = require('./SMSProvider');
module.exports.SMSNumberResolver = require('./SMSNumberResolver');
// Avoid
module.exports.SMSProvider = require('./SMSProvider/SMSProvider.js');
module.exports.SMSNumberResolver = require('./SMSNumberResolver/SMSNumberResolver.js');TL;DR: Prefer the strict equality operator === over the weaker abstract equality operator ==. == will compare two variables after converting them to a common type. There is no type conversion in ===, and both variables must be of the same type to be equal.
Otherwise: Unequal variables might return true when compared with the == operator.
'' == '0' // false
0 == '' // true
0 == '0' // true
false == 'false' // false
false == '0' // true
false == undefined // false
false == null // false
null == undefined // true
' \t\r\n ' == 0 // trueAll statements above will return false if used with ===
TL;DR: Node.js 8 LTS now has full support for Async-await. This is a new way of dealing with asynchronous code which supersedes callbacks and promises. Async-await is non-blocking, and it makes asynchronous code look synchronous. The best gift you can give to your code is using async-await which provides a much more compact and familiar code syntax like try-catch.
Otherwise: Handling async errors in callback style is probably the fastest way to hell - this style forces to check errors all over, deal with akward code nesting and make it difficult to reason about the code flow.
🔗Read more: Guide to async await 1.0
TL;DR: Though it's recommended to use async-await and avoid function parameters, when dealing with older API that accept promises or callbacks - arrow functions make the code structure more compact and keep the lexical context of the root function (i.e. 'this').
Otherwise: Longer code (in ES5 functions) is more prone to bugs and cumbersome to read.
🔗 Read mode: It’s Time to Embrace Arrow Functions
TL;DR: Most projects just don't have any automated testing due to short time tables or often the 'testing project' run out of control and being abandoned. For that reason, prioritize and start with API testing which are the easiest to write and provide more coverage than unit testing (you may even craft API tests without code using tools like Postman. Afterwards, should you have more resources and time, continue with advanced test types like unit testing, DB testing, performance testing, etc
Otherwise: You may spend long days on writing unit tests to find out that you got only 20% system coverage
TL;DR: ESLint is the de-facto standard for checking code style, not only to identify nitty-gritty spacing issues but also to detect serious code anti-patterns like developers throwing errors without classification. On top of ESLint standard rules that cover vanilla JS only, add Node-specific plugins like eslint-plugin-node, eslint-plugin-mocha and eslint-plugin-node-security
Otherwise: Many faulty Node.js code patterns might escape under the radar. For example, developers might require(variableAsPath) files with a variable given as path which allows attackers to execute any JS script. Node.js linters can detect such patterns and complain early
TL;DR: Your continuous integration platform (CICD) will host all the quality tools (e.g test, lint) so it should come with a vibrant ecosystem of plugins. Jenkins used to be the default for many projects as it has the biggest community along with a very powerful platform at the price of complex setup that demands a steep learning curve. Nowadays, it became much easier to setup a CI solution using SaaS tools like CircleCI and others. These tools allow crafting a flexible CI pipeline without the burden of managing the whole infrastructure. Eventually, it's a trade-off between robustness and speed - choose your side carefully.
Otherwise: Choosing some niche vendor might get you blocked once you need some advanced customization. On the other hand, going with Jenkins might burn precious time on infrastructure setup
🔗 Read More: Choosing CI platform
TL;DR: Even the most reputable dependencies such as Express have known vulnerabilities. This can get easily tamed using community and commercial tools such as 🔗 nsp that can be invoked from your CI on every build
Otherwise: Keeping your code clean from vulnerabilities without dedicated tools will require to constantly follow online publications about new threats. Quite tedious
TL;DR: Different tests must run on different scenarios: quick smoke, IO-less, tests should run when a developer saves or commits a file, full end-to-end tests usually run when a new pull request is submitted, etc. This can be achieved by tagging tests with keywords like #cold #api #sanity so you can grep with your testing harness and invoke the desired subset. For example, this is how you would invoke only the sanity test group with Mocha: mocha --grep 'sanity'
Otherwise: Running all the tests, including tests that perform dozens of DB queries, any time a developer makes a small change can be extremely slow and keeps developers away from running tests
TL;DR: Code coverage tools like Istanbul/NYC are great for 3 reasons: it comes for free (no effort is required to benefit this reports), it helps to identify a decrease in testing coverage, and last but not least it highlights testing mismatches: by looking at colored code coverage reports you may notice, for example, code areas that are never tested like catch clauses (meaning that tests only invoke the happy paths and not how the app behaves on errors). Set it to fail builds if the coverage falls under a certain threshold
Otherwise: There won't be any automated metric telling you when a large portion of your code is not covered by testing
TL;DR: Use your preferred tool (e.g. 'npm outdated' or npm-check-updates to detect installed packages which are outdated, inject this check into your CI pipeline and even make a build fail in a severe scenario. For example, a severe scenario might be when an installed package is 5 patch commits behind (e.g. local version is 1.3.1 and repository version is 1.3.8) or it is tagged as deprecated by its author - kill the build and prevent deploying this version
Otherwise: Your production will run packages that have been explicitly tagged by their author as risky
TL;DR: End to end (e2e) testing which includes live data used to be the weakest link of the CI process as it depends on multiple heavy services like DB. Docker-compose turns this problem into a breeze by crafting production-like environment using a simple text file and easy commands. It allows crafting all the dependent services, DB and isolated network for e2e testing. Last but not least, it can keep a stateless environment that is invoked before each test suite and dies right after
Otherwise: Without docker-compose teams must maintain a testing DB for each testing environment including developers machines, keep all those DBs in sync so test results won't vary across environments
TL;DR: Monitoring is a game of finding out issues before customers do – obviously this should be assigned unprecedented importance. The market is overwhelmed with offers thus consider starting with defining the basic metrics you must follow (my suggestions inside), then go over additional fancy features and choose the solution that ticks all boxes. Click ‘The Gist’ below for overview of solutions
Otherwise: Failure === disappointed customers. Simple.
TL;DR: Logs can be a dumb warehouse of debug statements or the enabler of a beautiful dashboard that tells the story of your app. Plan your logging platform from day 1: how logs are collected, stored and analyzed to ensure that the desired information (e.g. error rate, following an entire transaction through services and servers, etc) can really be extracted
Otherwise: You end-up with a blackbox that is hard to reason about, then you start re-writing all logging statements to add additional information
🔗 Read More: Increase transparency using smart logging
TL;DR: Node.js is awfully bad at doing CPU intensive tasks like gzipping, SSL termination, etc. Instead, use a ‘real’ middleware services like nginx, HAproxy or cloud vendor services
Otherwise: Your poor single thread will keep busy doing networking tasks instead of dealing with your application core and performance will degrade accordingly
🔗 Read More: Delegate anything possible (e.g. gzip, SSL) to a reverse proxy
TL;DR: Your code must be identical across all environments, but amazingly NPM lets dependencies drift across environments by default – when you install packages at various environments it tries to fetch packages’ latest patch version. Overcome this by using NPM config files , .npmrc, that tell each environment to save the exact (not the latest) version of each package. Alternatively, for finer grain control use NPM” shrinkwrap”. *Update: as of NPM5 , dependencies are locked by default. The new package manager in town, Yarn, also got us covered by default
Otherwise: QA will thoroughly test the code and approve a version that will behave differently at production. Even worse, different servers at the same production cluster might run different code
🔗 Read More: Lock dependencies
TL;DR: The process must go on and get restarted upon failures. For simple scenario, ‘restarter’ tools like PM2 might be enough but in today ‘dockerized’ world – a cluster management tools should be considered as well
Otherwise: Running dozens of instances without clear strategy and too many tools together (cluster management, docker, PM2) might lead to a devops chaos
🔗 Read More: Guard process uptime using the right tool
TL;DR: At its basic form, a Node.js application runs on a single CPU core while all other are left idling. It’s your duty to replicate the Node process and utilize all CPUs – For small-medium apps you may use Node.js Cluster or PM2. For a larger app consider replicating the process using some Docker cluster (e.g. K8S, ECS) or deployment scripts that are based on Linux init system (e.g. systemd)
Otherwise: Your app will likely utilize only 25% of its available resources(!) or even less. Note that a typical server has 4 CPU cores or more, naive deployment of Node.js utilizes only 1 (even using PaaS services like AWS beanstalk!)
🔗 Read More: Utilize all CPU cores
TL;DR: Expose a set of system-related information, like memory usage and REPL, etc in a secured API. Although it’s highly recommended to rely on standard and battle-tests tools, some valuable information and operations are easier done using code
Otherwise: You’ll find that you’re performing many “diagnostic deploys” – shipping code to production only to extract some information for diagnostic purposes
🔗 Read More: Create a ‘maintenance endpoint’
TL;DR: Monitoring and performance products (a.k.a APM) proactively gauge codebase and API so they can auto-magically go beyond traditional monitoring and measure the overall user-experience across services and tiers. For example, some APM products can highlight a transaction that loads too slow on the end-users side while suggesting the root cause
Otherwise: You might spend great effort on measuring API performance and downtimes, probably you’ll never be aware which is your slowest code parts under real world scenario and how these affects the UX
🔗 Read More: Discover errors and downtime using APM products
TL;DR: Code with the end in mind, plan for production from day 1. This sounds a bit vague so I’ve compiled a few development tips that are closely related to production maintenance (click Gist below)
Otherwise: A world champion IT/devops guy won’t save a system that is badly written
🔗 Read More: Make your code production-ready
TL;DR: Node.js has controversial relationships with memory: the v8 engine has soft limits on memory usage (1.4GB) and there are known paths to leaks memory in Node’s code – thus watching Node’s process memory is a must. In small apps you may gauge memory periodically using shell commands but in medium-large app consider baking your memory watch into a robust monitoring system
Otherwise: Your process memory might leak a hundred megabytes a day like happened in Wallmart
🔗 Read More: Measure and guard the memory usage
TL;DR: Serve frontend content using dedicated middleware (nginx, S3, CDN) because Node.js' performance really gets hurt when dealing with many static files due to its single threaded model
Otherwise: Your single Node.js thread will be busy streaming hundreds of html/images/angular/react files instead of allocating all its resources for the task it was born for – serving dynamic content
🔗 Read More: Get your frontend assets out of Node.js
TL;DR: Store any type of data (e.g. users session, cache, uploaded files) within external data stores. Consider ‘killing’ your servers periodically or use ‘serverless’ platform (e.g. AWS Lambda) that explicitly enforces a stateless behavior
Otherwise: Failure at a given server will result in application downtime instead of just killing a faulty machine. Moreover, scaling-out elasticity will get more challenging due to the reliance on a specific server
🔗 Read More: Be stateless, kill your Servers almost every day
TL;DR: Even the most reputable dependencies such as Express have known vulnerabilities (from time to time) that can put a system at risk. This can get easily tamed using community and commercial tools that constantly check for vulnerabilities and warn (locally or at GitHub), some can even patch them immediately
Otherwise: Otherwise: Keeping your code clean from vulnerabilities without dedicated tools will require to constantly follow online publications about new threats. Quite tedious
🔗 Read More: Use tools that automatically detect vulnerabilities
TL;DR: Assign the same identifier, transaction-id: {some value}, to each log entry within a single request. Then when inspecting errors in logs, easily conclude what happened before and after. Unfortunately, this is not easy to achieve in Node.js due its async nature, see code examples inside
Otherwise: Looking at a production error log without the context – what happened before – makes it much harder and slower to reason about the issue
🔗 Read More: Assign ‘TransactionId’ to each log statement
TL;DR: Set the environment variable NODE_ENV to ‘production’ or ‘development’ to flag whether production optimizations should get activated – many NPM packages determining the current environment and optimize their code for production
Otherwise: Omitting this simple property might greatly degrade performance. For example, when using Express for server side rendering omitting NODE_ENV makes the slower by a factor of three!
🔗 Read More: Set NODE_ENV=production
TL;DR: Researches show that teams who perform many deployments – lowers the probability of severe production issues. Fast and automated deployments that don’t require risky manual steps and service downtime significantly improves the deployment process. You should probably achieve that using Docker combined with CI tools as they became the industry standard for streamlined deployment
Otherwise: Long deployments -> production down time & human-related error -> team unconfident and in making deployment -> less deployments and features
TL;DR: Make use of security linter plugins such as eslint-plugin-security to enforce a policy for secure code (e.g. no use of eval, require with variables, etc).
Otherwise: Developers in the project may not follow consistent code security practices, leading to vulnerabilities being introduced, or sensitive secrets committed into remote repositories.
TL;DR: Implement rate limiting using an external service such as NGINX, or if that is not possible use a rate limiting middleware within the application
Otherwise: An application could be subject to an attack resulting in a denial of service where real users receive degraded service, or an unavailable application.
🔗 Read More: Implement rate limiting
TL;DR: Never store plain-text secrets in configuration files or source code. Instead, make use of secrets management systems like Vault, Docker Secrets, or inject secrets as environment variables accessible to an application. As a last result, storing secrets in source control must be encrypted, and managed (rolling keys, expiring, auditing, etc). Make use of pre-commit/push hooks to check for accidental commit of secrets.
Otherwise: Source control for even private repositories, can mistakenly be made public, at which point all secret has been exposed outside. Access to source control for an external party will inadvertently provide access to related systems (database, apis, etc).
TL;DR: To prevent SQL/noSQL injection attacks always make use of an ORM/ODM or a database library that escapes or supports named or indexed parameter binding, and takes care of validating user input for expected types. Never use JS template strings or string concatenation to inject values into queries.
Otherwise: Un-validated user input could lead to operator injection when working with MongoDB for noSQL, and unescaped use of proper ORM/ODM will allow easy SQL injection attacks.
TL;DR: There are many built-in and external ways to secure your Node.js applications starting from simple steps like running your server with ssl/tls enabled to more advanced features.
🔗 Read More: Common security best practices
TL;DR: Your application should be using secure headers to prevent attackers from using common attacks like cross-site scripting (XSS), clickjacking and other malicious attacks. These can be configured easily using modules like helmet.
Otherwise: Attackers could perform attacks on your application's users, leading to insecurity
🔗 Read More: Using secure headers in your application
TL;DR: With the npm ecosystem it is common to have many dependencies for a project. Dependencies should always be kept in check as new vulnerabilities are found. Use tools like nsp or snyk to track, monitor and patch vulnerable dependencies. Integrate these tools with your CI setup so you catch a vulnerable dependency before it makes it to production.
Otherwise: An attacker could detect your web framework and attack with all it's known vulnerabilities.
🔗 Read More: Dependency security
TL;DR: Passwords or secrets (API keys) should be stored using a secure hash function like bcrypt, that should be a preferred choice over its JavaScript implementation due to performance and security reasons.
Otherwise: Passwords or secrets that are persisted without using a secure hash function are vulnerable to brute forcing and dictionary attacks that will lead to their disclosure eventually.
TL;DR: Here we will write about sanitizing/escaping/encoding both the input and output. The top frontend libraries handle output encoding well, but nevertheless you should always make sure to output encode your user generated data in the correct context, and can make use of libraries such as node-esapi or escape-html.
Otherwise: Failure to encode user generated when outputting it can result in XSS, Log Injection or other vulnerabilities. Input validation should always be performed to confirm one is working with expected types and data properties (length, range, etc).
TL;DR: Validate the incoming requests` body payload and ensure it qualifies the expectations, fail fast if it doesn't. To avoid tedious validation coding within each route you may use lightweight JSON-based validation schemas such as jsonschema or JOI
Otherwise: Your generosity and permissive approach greatly increases the attack surface and encourage the attacker to try out many inputs until it finds some combination that crashes the application
🔗 Read More: Validate the incoming JSON schemas
TL;DR: When using JWT(for example, with Passport.js), a custom implementation for blacklisting untrusted or invalid tokens is required to revoke the token's access, due to the completely stateless approach of JWT.
Otherwise: Expired, or misplaced tokens could be used maliciously by a third party to access an application impersonating the owner of the token.
🔗 Read More: Blacklist JWT Tokens
TL;DR: Here we will write about designing and using middleware that doesn't make the process crash when an invalid JSON is passed since it opens the door for easy DDOS attacks
Otherwise:
TL;DR: There are common scenario where nodejs runs as a root user with unlimited permissions. For example this is the default behaviour in Docker containers. It's recommended to create a non-root user and always run the process on this user behalf by invoking the container with the flag "-u username"
Otherwise: An attacker who manages to run a script on the server gets unlimited power over the local machine (e.g. change iptable and re-route traffic to his server)
TL;DR: DOS attacks of many varieties can be mitigated by limiting the body size of incoming requests to your web application.
Otherwise: your application will have to deal with large requests, unable to process the other important work it has to accomplish, leading to performance implications and vulnerability towards DOS attacks
TL;DR: eval may be used to evaluate javascript code during run-time, but it is not just a performance concern but also an important security concern due to malicious javascript code that may be sourced from user input. Another language feature that should be avoided is new Function constructor. setTimeout and setInterval should never be passed dynamic javascript code either.
Otherwise: Malicious javascript code finds a way into a text passed into eval or other real-time evaluating javascript language functions, it will gain complete access to javascript permissions on the page, often manifesting as an XSS attack.
🔗 Read More: Avoid JS eval statements
TL;DR: Regular Expressions, while being handy, pose a real threat to JavaScript applications at large, and the Node.js platform in particular due to the fact that they require CPU cycles to compute a pattern test. Use the aforementioned validator.js package to validate data instead of writing your own, or make use of safe-regex to detect vulnerable regex patterns.
Otherwise: Poorly written regexes could be susceptible to Regular Expressions DoS attacks that will block the event loop completely. For example, the popular moment package was found vulnerable in Nov 2017.
TL;DR: Avoid requiring/importing another file with a path that was given as parameter due to the concern that it could have originated from user input. This rule can be extended for accessing files in general (i.e. fs.readFile()) or other sensitive resource access with dynamic variables originating from user input.
Otherwise: Malicious user input could find its way to a parameter that is used to require tampered files, for example a previously uploaded file on the filesystem, or access already existing system files.
🔗 Read More: Safe module loading
TL;DR: Here we will write about the need to run untrusted code, for example third-party components. In that case, we'd like to isolate our code from weakness of the 3rd party code. We can achieve that by running our code in a sandbox
Otherwise:
TL;DR: Avoid using child_process.exec when possible or validate and sanitize input to mitigate shell injection attacks. Prefer using child_process.execFile which by definition will only execute a single command with a set of attributes and will not allow shell parameter expansion.
Otherwise: Naive use of child_process.exec could result in remote command execution or shell injection attacks due to malicious user input passed to an unsanitized system command.
TL;DR: Use the default Express error handler, or ensure that custom error handlers avoid exposing error details to the client when running an application outside of development.
Otherwise: Sensitive application details such as server filepaths, third party modules in use, and other internal workings of the application which could be exploited by an attacker from information found in a stack trace.
🔗 Read More: Hide error details from client
TL;DR: Using the default settings for session middleware can be expose your app to module and framework specific hijacking attacks in a similar way to the X-Powered-By header.
Otherwise: Cookies could be sent over insecure connections, and an attacker can use session identification to identify the underlying framework of the web application, as well as module-specific vulnerabilities.
🔗 Read More: Cookie and session security
To maintain this guide and keep it up to date, we are constantly updating and improving the guidelines and best practices with the help of the community. You can follow our milestones and join the working groups if you want to contribute to this project.
Independent Node.JS consultant who works with customers at USA, Europe and Israel on building large-scale scalable Node applications. Many of the best practices above were first published on his blog post at http://www.goldbergyoni.com. Reach Yoni at @goldbergyoni or me@goldbergyoni.com
👨💻 Software engineer, 🌐 web developer, 🤖 emojis enthusiast.
Refael Ackermann @refack <refack@gmail.com> (he/him)
Node.js Core Collaborator, been noding since 0.4, and have noded in multiple production sites. Founded node4good home of lodash-contrib, formage, and asynctrace.
refack on freenode, Twitter, GitHub, GMail, and many other platforms. DMs are open, happy to help.
💻 full-stack web developer and Node.js enthusiast.
Liran Tal @lirantal <liran.tal@gmail.com> (he/him)
Node.js Security WG member, and author of Essential Node.js Security. Lead dev at @meanjs, and regular @OWASP contributor, passionate about Open Source, Node.js, JavaScript and Security.