Environment Variables and Telemetry

Purpose and Scope

Storybook projects usually run in more than one mode: a developer may start a local workshop, a continuous integration job may build a static Storybook, and a preview deployment may expose documentation to designers, product managers, or QA. Environment variables are the lightweight configuration surface for those mode-specific differences. Telemetry is a separate feedback surface that helps Storybook maintainers understand broad usage patterns. This page treats them together because both involve information crossing a boundary between the host environment and Storybook tooling, and because teams often review them during the same security or platform adoption process.

Telemetry is intentionally described as anonymous and optional in the Storybook documentation. The repository documentation says Storybook collects completely anonymous data to improve the user experience and that users may opt out if they do not want to participate. That framing is important for teams adopting Storybook at scale: telemetry is not an application logging system, a component-rendering dependency, or a replacement for project configuration. It is a maintainer-facing signal used to understand how Storybook is used across many frameworks, builders, addons, and workflows. Sources: docs/configure/telemetry.mdx

Environment variables solve a different problem. The official configuration docs describe environment variables as a way to change Storybook behavior in different modes. Variables intended for browser-side Storybook code use the public Storybook prefix, and the selected builder determines how preview code reads them. This makes them useful for themes, fixture choices, mocked service switches, documentation variants, or non-sensitive feature modes. It also means they should be treated like frontend build inputs rather than private server configuration, because Storybook output can be inspected after it is built.

Core Primitives

A Storybook environment variable is a value supplied before Storybook starts, usually by a shell command, package script, or CI configuration. Public values use the Storybook prefix documented in the official environment-variable guide. When a project uses Webpack, those values are available to preview code through the process environment object. When a project uses the Vite builder, they are available through the Vite environment object. In both cases, the values are intended for code that runs in or contributes to the preview, including stories, decorators, loaders, docs examples, and preview configuration.

A telemetry event is an anonymous usage record emitted by Storybook tooling. The telemetry documentation lists command invocation, Storybook version, addons, view layer, story count, package manager information, monorepo information, builder, meta framework, testing tools, and selected in-app events as examples of what can be tracked. It also describes one-way hashes for the Storybook unique identifier and the IP address used for spam detection. These details help maintainers reason about aggregate usage without needing to identify individual users. Sources: docs/configure/telemetry.mdx

The distinction between these primitives should guide project policy. Environment variables are controlled by the project and can directly affect what the rendered Storybook does or displays. Telemetry is controlled by Storybook’s tooling and summarizes the kind of project and command being used. A team might use public variables to switch between light and dark themes in the preview, while telemetry might record that the project uses Vite, TypeScript, React, certain addons, and a build command. Those two flows should not be confused, because one affects application-visible behavior and the other supports product improvement.

Relevant Source Files

• docs/configure/telemetry.mdx — Defines Storybook telemetry as optional and anonymous, explains why maintainers collect it, enumerates the metadata categories, describes privacy safeguards for sensitive data, and documents the debug inspection flow for viewing collected information.

System-to-Code Mapping

The telemetry source page is the authoritative repository-backed documentation for this topic. Its opening section establishes the user contract: data collection is completely anonymous, participation is optional, and users can opt out. Its motivation section explains why the project needs these signals. Storybook is framework agnostic and integrates with JavaScript frameworks, styling libraries, design tools, and workflow tools. Because that ecosystem is broad and constantly changing, maintainers use telemetry to prioritize work with more accuracy than manual feedback alone. Sources: docs/configure/telemetry.mdx

The collected-data section maps directly to the kinds of decisions maintainers need to make. Command names such as init, upgrade, dev, and build show which workflows are being exercised. Version, story count, language, view layer, builder, meta framework, addons, testing tools, package manager, and monorepo information reveal ecosystem trends. In-app events, such as the guided tour or a UI test run, help maintainers understand adoption of product features. The page also states that access to raw data is highly controlled and limited to selected core team members who maintain telemetry. Sources: docs/configure/telemetry.mdx

The environment-variable behavior is documented in the official configuration guide rather than in the requested repository file. For project authors, the practical mapping is still straightforward: values with the public Storybook prefix are bundled into the Storybook preview environment, with Webpack and Vite exposing them through their respective runtime conventions. That makes the builder choice relevant for code syntax, but not for the security model. If a value is available to preview code and embedded into a static build, it should be considered visible to anyone who can inspect the generated files.

Execution Flow

A typical local flow begins before the Storybook process starts. The developer chooses the mode they want, sets public variables in the shell or package script, and then runs the Storybook development command. During startup, the framework and builder configuration determine how those values are injected. Stories and preview configuration can then branch on the values to select a theme, enable a demo-only state, choose fixture data, or show a particular docs variant. This is convenient because it avoids hard-coding local-only assumptions inside story files, but it remains a public configuration mechanism.

STORYBOOK_THEME=red STORYBOOK_DATA_KEY=12345 npm run storybook

The corresponding build flow has a stricter operational consequence. If a CI job supplies public Storybook variables while producing a static Storybook, those values become part of the generated artifact. That artifact may be uploaded to a documentation host, attached to a pull request preview, shared with stakeholders, or archived for release validation. Teams should therefore review CI variables with the same care they apply to frontend build-time configuration. Public mode names, harmless identifiers, and mock switches are appropriate; passwords, private service tokens, production credentials, and sensitive internal endpoints are not.

Telemetry runs alongside Storybook commands and selected in-app behavior rather than replacing that configuration flow. When a command is invoked, the documented event model can include the command name, version, project metadata, and environment context. During product interactions, it can include in-app events that help maintainers understand feature usage. The repository documentation explains that these data help the maintainers prioritize high-impact projects, keep up with frontend ecosystem trends, and verify that community work has the intended result. Sources: docs/configure/telemetry.mdx

Privacy, Sensitive Data, and Debugging

The most important environment-variable rule is that public Storybook variables are not a secret store. The official docs explicitly warn that environment variables are embedded into the build and can be viewed by inspecting files. This warning applies even if a value is only used by a story, decorator, loader, or docs page. Storybook is designed to render UI examples in the browser, and browser-visible configuration should be assumed inspectable. Secrets should stay in backend services, test infrastructure, local unexposed processes, or other systems that do not publish them into the preview bundle.

Telemetry has its own privacy safeguards. The repository documentation states that Storybook performs additional steps to ensure secure data, including environment variables and other sensitive data, does not make its way into analytics. It also says the dataset is anonymized and untraceable back to the user. This is a telemetry guarantee, not permission to expose secrets through public preview configuration. In practice, teams should treat the two controls as complementary: Storybook avoids collecting sensitive configuration in telemetry, while project authors avoid placing sensitive values into browser-visible Storybook builds. Sources: docs/configure/telemetry.mdx

For inspection, the documented debug switch is the telemetry debug environment setting with a value of one. Running Storybook with that setting prints the information gathered for telemetry, allowing developers and platform teams to inspect the event shape before deciding how to handle telemetry in local development, enterprise workstations, or CI. The documentation’s example output includes an anonymous identifier, event type, and context such as terminal status, platform, Node version, and Storybook version. This makes debugging concrete without requiring teams to infer what might be sent. Sources: docs/configure/telemetry.mdx

STORYBOOK_TELEMETRY_DEBUG=1 npm run storybook

Compact Reference

A useful team convention is to document allowed public variables near the Storybook configuration and to review them whenever a new addon, builder, or deployment target is introduced. The review should ask whether a value is safe in a browser, whether it changes story behavior in a predictable way, and whether it will appear in a static artifact. Separately, teams can use telemetry debugging to inspect Storybook’s anonymous metadata and decide whether their organization will participate. Those checks keep configuration flexible while preserving a clear boundary around sensitive data.

Next Steps

Use this page when setting policy for Storybook builds, preview deployments, and CI jobs. Continue to configure-overview for the larger configuration model, then read vite-builder or webpack-builder for builder-specific behavior that affects how preview code accesses public variables. Pair this page with test-coverage-and-ci when deciding which values CI should supply during automated Storybook runs, and with publish-and-embed-storybook before sharing a static build outside the development team.