Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

process.env.MY_VAR is undefined in my webpack browser bundle

Errorprocess.env.API_URL is undefined in the browser

Short answer

A browser has no process.env. Webpack can only swap the text process.env.NAME for a value while it builds, and only when you ask it to with DefinePlugin or EnvironmentPlugin. Add the plugin, give the value in quoted form, and rebuild, because changing the variable later does not change a finished bundle.

  • Applies to webpack 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the bundle contains your variable name at all. If it does, nothing replaced it at build time.

    grep -rn "process.env.API_URL" dist/ | head
  2. 2Match what you see, then jump to its fix

    1. 1The built file still contains process.env.API_URL as textNo plugin defines the variableFix
    2. 2EnvironmentPlugin - API_URL environment variable is undefinedA required variable has no value and no defaultFix
    3. 3The bundle has a syntax error or a bare identifier where a string should beDefinePlugin value is missing its quotesFix
    4. 4Other code that uses process (not just process.env.API_URL) starts failing after you added DefinePluginprocess was replaced as a whole objectFix

What does the error look like?

  • process.env.API_URL is undefined in the browser
  • EnvironmentPlugin - API_URL environment variable is undefined

Cause 1 of 4

No plugin defines the variable

1Check

EnvironmentPlugin is described as shorthand for DefinePlugin on process.env keys. Neither is in your plugin list.

grep -n "DefinePlugin\|EnvironmentPlugin" webpack.config.js

2Fix

Add EnvironmentPlugin with the names you need. A key in the object form gets its default when the variable is not set.

const webpack = require('webpack');

plugins: [
  new webpack.EnvironmentPlugin({
    NODE_ENV: 'development',
    API_URL: 'http://localhost:3000',
  }),
],

3Verify

Rebuild and search the bundle; the text process.env.API_URL is replaced by the value.

API_URL=https://api.example.com npx webpack
grep -rn "api.example.com" dist/ | head -3

Confirmed by webpack.js.org

Did this fix it?

Cause 2 of 4

A required variable has no value and no default

1Check

With the array form there is no default. If the variable is also missing from the shell that runs the build, the plugin throws.

echo "$API_URL"

2Fix

Export the variable before the build, or use the object form and give a default.

new webpack.EnvironmentPlugin({ API_URL: 'http://localhost:3000' })

3Verify

The build finishes without the plugin error.

npx webpack

Confirmed by webpack.js.org

Did this fix it?

Cause 3 of 4

DefinePlugin value is missing its quotes

1Check

DefinePlugin does a direct text replacement, so the value must include real quotes inside the string.

grep -n -A4 "DefinePlugin" webpack.config.js

2Fix

Wrap each value in JSON.stringify.

new webpack.DefinePlugin({
  'process.env.API_URL': JSON.stringify(process.env.API_URL),
})

3Verify

Rebuild; the replaced value shows as a quoted string in the bundle.

grep -rn "process.env.API_URL" dist/ | head

Confirmed by webpack.js.org

Did this fix it?

Cause 4 of 4

process was replaced as a whole object

1Check

Defining process: { env: { ... } } overwrites the process object, which the docs warn can break modules that expect other values on it.

grep -n -A6 "process:" webpack.config.js

2Fix

Define one key per variable, in the form 'process.env.NAME'.

new webpack.DefinePlugin({
  'process.env.NODE_ENV': JSON.stringify('production'),
})

3Verify

Rebuild and load the page; the modules that read process work again.

npx webpack

Confirmed by webpack.js.org

Did this fix it?

How do I stop it coming back?

  • Treat these values as public: anything put into a browser bundle can be read by every visitor, so no secrets.
  • List every variable the front end needs in one place, with defaults.
  • Rebuild after changing a variable; a finished bundle never re-reads the environment.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.