JavaScript developers are keenly aware of the need to reduce the size of deployed assets, especially in today’s world of single-page apps. This usually means running increasingly complex JavaScript codebases through build steps that produce a minified bundle for deployment. However, if you read a typical tutorial on setting up a build tool like Browserify or Webpack, you’ll see numerous references to a variable called process.env.NODE_ENV. Tutorials always talk about how this needs to be set to a value like “production” in order to produce a properly optimized bundle, but most articles never really spell out why this value matters and how it relates to build optimization. Here’s an explanation of why process.env.NODE_ENV is used and how it fits into the typical build process.

Operating system environment variables are widely used as a method of configuring applications, especially as a way to activate behavior based on different deployment environments (such as development vs testing vs production). Node.js exposes the current process’s environment variables to the script as an object called process.env. From there, the Express web server framework popularized using an environment variable called NODE_ENV as a flag to indicate whether the server should be running in “development” mode vs “production” mode. At runtime, the script looks up that value by checking process.env.NODE_ENV.

Because it was used within the Node ecosystem, browser-focused libraries also started using it to determine what environment they were running in, and using it to control optimizations and debug mode behavior. For example, React uses it as the equivalent of a C preprocessor #ifdef to act as conditional checking for debug logging and perf tracking, roughly like this:

function someInternalReactFunction() {  
    // do actual work part 1  

    if(process.env.NODE_ENV === "development") {  
        // do debug-only work, like recording perf stats  
    }  

    // do actual work part 2  
}

If process.env.NODE_ENV is set to “production”, all those if clauses will evaluate to false, and the potentially expensive debug code won’t run. In addition, in conjunction with a tool like UglifyJS that does minification and removal of dead code blocks, a clause that is surrounded with if(process.env.NODE_ENV === “development”) will become dead code in a production build and be stripped out, thus reducing bundled code size and execution time.

However, because the NODE_ENV environment variable and the corresponding process.env.NODE_ENV runtime field are normally server-only concepts, by default those values do not exist in client-side code. This is where build tools such as Webpack’s DefinePlugin or the Browserify Envify transform come in, which perform search-and-replace operations on the original source code. Since these build tools are doing transformation of your code anyway, they can force the existence of global values such as process.env.NODE_ENV. (It’s also important to note that because DefinePlugin in particular does a direct text replacement, the value given to DefinePlugin must include actual quotes inside of the string itself. Typically, this is done either with alternate quotes, such as ‘“production”‘, or by using JSON.stringify(“production”)).

Here’s the key: the build tool could set that value to anything, based on any condition that you want, as you’re defining your build configuration. For example, I could have a webpack.production.config.js Webpack config file that always uses the DefinePlugin to set that value to “production” throughout the client-side bundle. It wouldn’t have to be checking the actual current value of the “real” process.env.NODE_ENV variable while generating the Webpack config, because as the developer I would know that any time I’m doing a “production” build, I would want to set that value in the client code to “production’.

This is where the “code I’m running as part of my build process” and “code I’m outputting from my build process” worlds come together. Because your build script is itself most likely to be JavaScript code running under Node, it’s going to have process.env.NODE_ENV available to it as it runs. Because so many tools and libraries already share the convention of using that field’s value to determine their dev-vs-production status, the common convention is to use the current value of that field inside the build script as it’s running to also determine the value of that field as applied to the client code being transformed.

Ultimately, it all comes down to a few key points:

1. NODE_ENV is a system environment variable that Node exposes into running scripts.
2. It’s used by convention to determine dev-vs-prod behavior, by both server tools, build scripts, and client-side libraries.
3. It’s commonly used inside of build scripts (such as Webpack config generation) as both an input value and an output value, but the tie between the two is still just convention.
4. Build tools generally do a transform step on the client-side code, replace any references to process.env.NODE_ENV with the desired value, and the resulting code will contain dead code blocks as debug-only code is now inside of an if(false)-type condition, ensuring that code doesn’t execute at runtime.
5. Minifier tools such as UglifyJS will strip out the dead code blocks, leaving the production bundle smaller.

So, the next time you see process.env.NODE_ENV mentioned in a build script, hopefully you’ll have a much better idea why it’s there.

About the author

Mark Erikson is a software engineer living in southwest Ohio, USA, where he patiently awaits the annual heartbreak from the Reds and the Bengals. Mark is author of the Redux FAQ, maintains the React/Redux Links list and Redux Addons Catalog, and occasionally tweets at @acemarke. He can be usually found in the Reactiflux chat channels, answering questions about React and Redux. He is also slightly disturbed by the number of third-person references he has written in this bio!