Skip to content

Docs: Clarify webpack process.env requires variables to be set #34558

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nitzan-treg wants to merge 2 commits into
base: next
Choose a base branch
from
+17 −1
Open

Docs: Clarify webpack process.env requires variables to be set #34558

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
36dcd51
docs: clarify webpack process.env requires variables to be set
nitzan-treg Apr 16, 2026
006e099
fix: replace smart quotes with ASCII quotes in JSX attributes
nitzan-treg Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion docs/configure/environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar:
title: Environment variables
---

You can use environment variables in Storybook to change its behavior in different “modes”.
You can use environment variables in Storybook to change its behavior in different "modes".
If you supply an environment variable prefixed with `STORYBOOK_`, it will be available in `process.env` when using Webpack, or `import.meta.env` when using the Vite builder:

```shell
Expand All @@ -22,6 +22,12 @@ Then we can access these environment variables anywhere inside our preview JavaS
{/* prettier-ignore-start */}

<CodeSnippets path="storybook-read-environment-variables.md" />

<Callout variant="warning">
With Webpack 5, `process.env` is only injected into the browser bundle for environment variables that are **actually defined** at build time. If a `STORYBOOK_*` variable is not set in your environment or `.env` file, referencing `process.env` will throw a `Can't find variable: process` runtime error.

To avoid this, make sure all `STORYBOOK_*` variables you reference are always defined — either in a `.env` file, on the command line, or by providing defaults in your `.storybook/main.ts` using the [`env` configuration field](#using-storybook-configuration).
</Callout>
</IfRenderer>

{/* prettier-ignore-end */}
Expand Down Expand Up @@ -112,6 +118,16 @@ The table below lists the available options:

## Troubleshooting

### Can't find variable: process (Webpack)

When using a Webpack-based framework (e.g., Angular with Webpack 5), you may see a `Can't find variable: process` runtime error if you reference `process.env.STORYBOOK_*` for a variable that is not actually set at build time. Unlike Vite, Webpack only injects `process.env` into the browser bundle when at least one matching environment variable is defined. If the variable is missing, `process` itself is not available in the browser and any reference to it will throw.

To fix this, make sure all `STORYBOOK_*` variables you reference are always defined. You can:

- Set them in a `.env` file at the root of your project
- Pass them on the command line when running Storybook
- Provide defaults in your `.storybook/main.ts` using the [`env` configuration field](#using-storybook-configuration)

### Environment variables are not working

If you're trying to use framework-specific environment variables (e.g.,`VUE_APP_`), you may run into issues primarily due to the fact that Storybook and your framework may have specific configurations and may not be able to recognize and use those environment variables. If you run into a similar situation, you may need to adjust your framework configuration to make sure that it can recognize and use those environment variables. For example, if you're working with a Vite-based framework, you can extend the configuration file and enable the [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) option. Other frameworks may require a similar approach.
Loading