Skip to content
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

Jump to bottom

Docs: Minor updates to the Environment variables docs #23605

Merged
merged 3 commits into from
Jul 25, 2023
Merged

Docs: Minor updates to the Environment variables docs #23605

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
daa1b33
Minor updates to the Environment variables docs
jonniebigodes Jul 25, 2023
d2711ed
Adjusts pnpm snippets to prevent regression
jonniebigodes Jul 25, 2023
5dd7fef
Tweaks per feedback
jonniebigodes Jul 25, 2023
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
67 changes: 54 additions & 13 deletions docs/configure/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: 'Environment variables'
---

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:
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
STORYBOOK_THEME=red STORYBOOK_DATA_KEY=12345 npm run storybook
Expand All @@ -17,14 +17,33 @@ STORYBOOK_THEME=red STORYBOOK_DATA_KEY=12345 npm run storybook

Then we can access these environment variables anywhere inside our preview JavaScript code like below:

<IfRenderer renderer={['angular', 'ember' ]}>

<!-- prettier-ignore-start -->

<CodeSnippets
paths={[
'common/storybook-read-environment-variables.node-env.js.mdx',
]}
/>

</IfRenderer>

<!-- prettier-ignore-end -->

<IfRenderer renderer={['html', 'react', 'qwik', 'preact','svelte', 'solid', 'vue', 'web-components' ]}>

<!-- prettier-ignore-start -->

<CodeSnippets
paths={[
'common/storybook-read-environment-variables.js.mdx',
'common/storybook-read-environment-variables.node-env.js.mdx',
'common/storybook-read-environment-variables.vite-env.js.mdx',
]}
/>

</IfRenderer>

<!-- prettier-ignore-end -->

You can also access these variables in your custom `<head>`/`<body>` using the substitution `%STORYBOOK_X%`, for example: `%STORYBOOK_THEME%` will become `red`.
Expand All @@ -49,25 +68,41 @@ Then you can access this environment variable anywhere, even within your stories

<CodeSnippets
paths={[
'react/my-component-with-env-variables.js.mdx',
'react/my-component-with-env-variables.ts.mdx',
'vue/my-component-with-env-variables.js.mdx',
'vue/my-component-with-env-variables.ts.mdx',
'angular/my-component-with-env-variables.ts.mdx',
'web-components/my-component-with-env-variables.js.mdx',
'web-components/my-component-with-env-variables.ts.mdx',
'svelte/my-component-with-env-variables.js.mdx',
'solid/my-component-with-env-variables.js.mdx',
'solid/my-component-with-env-variables.ts.mdx',
'common/my-component-with-env-variables.js.mdx',
'common/my-component-with-env-variables.ts.mdx',
]}
/>

<!-- prettier-ignore-end -->

<IfRenderer renderer={['html', 'react', 'qwik', 'preact','svelte', 'solid', 'vue', 'web-components' ]}>

#### With Vite

Out of the box, Storybook provides a [Vite builder](../builders/vite.md), so using environment variables here will be quite different from using environment variables in other frameworks that use other build tools. To access environment variables in Storybook (e.g., `STORYBOOK_`, `VITE_`), you can use the `import.meta.env`, which is specific to Vite. For example:
jonniebigodes marked this conversation as resolved.
Show resolved Hide resolved

<!-- prettier-ignore-start -->

<CodeSnippets
paths={[
'web-components/my-component-vite-env-variables.js.mdx',
'web-components/my-component-vite-env-variables.ts.mdx',
'common/my-component-vite-env-variables.js.mdx',
'common/my-component-vite-env-variables.ts.mdx',
]}
usesCsf3
csf2Path="configure/environment-variables#snippet-my-component-with-env-variables"
/>

<!-- prettier-ignore-end -->

</IfRenderer>

<div class="aside">
You can also use specific files for specific modes. Add a <code>.env.development</code> or <code>.env.production</code> to apply different values to your environment variables.

You can also use specific files for specific modes. Add a `.env.development` or `.env.production` to apply different values to your environment variables.

</div>

You can also pass these environment variables when you are [building your Storybook](../sharing/publish-storybook.md) with `build-storybook`.
Expand All @@ -76,7 +111,7 @@ Then they'll be hardcoded to the static version of your Storybook.

### Using Storybook configuration

Additionally, you can extend your Storybook configuration file (i.e., [`.storybook/main.js`](../configure/overview.md#configure-story-rendering)) and provide a configuration field that you can use to define specific variables (e.g., API URLs). For example:
Additionally, you can extend your Storybook configuration file (i.e., [`.storybook/main.js|.ts`](../configure/overview.md#configure-story-rendering)) and provide a configuration field that you can use to define specific variables (e.g., API URLs). For example:

<!-- prettier-ignore-start -->

Expand Down Expand Up @@ -122,3 +157,9 @@ The table below lists the available options:
<div class="aside">
💡 By default, Storybook will open a new Chrome window as part of its startup process. If you don't have Chrome installed, make sure to include one of the following options, or set your default browser accordingly.
</div>

## Troubleshooting

### 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 and are interested in helping us improving support for this feature, we encourage you to reach out to the maintainers using the default communication channels (e.g., [Discord server](https://discord.com/channels/486522875931656193/570426522528382976), [GitHub issues](https://github.com/storybookjs/storybook/issues)).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Storybook and your framework may have specific configurations and may not be able to recognize and use those environment variables.

This is where envPrefix can be used, right? Is that worth mentioning here instead of making it seem like there is no solution?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a great catch, and we can pivot the documentation toward it and provide a workaround for this for now. I'll update it shortly.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@IanVS just updated this based on your suggestion. Let me know, and we'll go from there.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I think this is good. For some reason I thought that envPrefix was a storybook option, but you're right it's in Vite. I believe we do read that option though when deciding which env variables to expose to stories. So, ideally environment variables should "just work" from Storybook's perspective. But doesn't hurt to point it out and give folks the option to contact us if something wonky is happening.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No problem. Appreciate you taking the time to review it and point me in that direction 🙇 .

3 changes: 2 additions & 1 deletion ...id/my-component-with-env-variables.js.mdx → ...on/my-component-vite-env-variables.js.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ export default {

export const ExampleStory = {
args: {
propertyA: process.env.STORYBOOK_DATA_KEY,
propertyA: import.meta.env.STORYBOOK_DATA_KEY,
propertyB: import.meta.env.VITE_CUSTOM_VAR,
},
};
```
8 changes: 5 additions & 3 deletions ...y-component-with-env-variables.ts-4-9.mdx → ...y-component-vite-env-variables.ts-4-9.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
```tsx
// MyComponent.stories.ts| tsx
// MyComponent.stories.ts|tsx

import type { Meta, StoryObj } from 'storybook-solidjs';
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';

import { MyComponent } from './MyComponent';

Expand All @@ -14,7 +15,8 @@ type Story = StoryObj<typeof meta>;

export const ExampleStory: Story = {
args: {
propertyA: process.env.STORYBOOK_DATA_KEY,
propertyA: import.meta.env.STORYBOOK_DATA_KEY,
propertyB: import.meta.env.VITE_CUSTOM_VAR,
},
};
```
22 changes: 22 additions & 0 deletions docs/snippets/common/my-component-vite-env-variables.ts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
```tsx
// MyComponent.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';

import { MyComponent } from './MyComponent';

const meta: Meta<typeof MyComponent> = {
component: MyComponent,
};

export default meta;
type Story = StoryObj<typeof MyComponent>;

export const ExampleStory: Story = {
args: {
propertyA: import.meta.env.STORYBOOK_DATA_KEY,
propertyB: import.meta.env.VITE_CUSTOM_VAR,
},
};
```
0 ...ct/my-component-with-env-variables.js.mdx → ...on/my-component-with-env-variables.js.mdx
View file
Open in desktop
File renamed without changes.
5 changes: 3 additions & 2 deletions ...y-component-with-env-variables.ts-4-9.mdx → ...y-component-with-env-variables.ts-4-9.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
```ts
// MyComponent.stories.ts| tsx
// MyComponent.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';

import { MyComponent } from './MyComponent';

Expand Down
5 changes: 3 additions & 2 deletions ...ct/my-component-with-env-variables.ts.mdx → ...on/my-component-with-env-variables.ts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
```ts
// MyComponent.stories.ts| tsx
// MyComponent.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';

import { MyComponent } from './MyComponent';

Expand Down
0 ...orybook-read-environment-variables.js.mdx → ...ead-environment-variables.node-env.js.mdx
View file
Open in desktop
File renamed without changes.
4 changes: 4 additions & 0 deletions docs/snippets/common/storybook-read-environment-variables.vite-env.js.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
```js
console.log(import.meta.env.STORYBOOK_THEME);
console.log(import.meta.env.STORYBOOK_DATA_KEY);
```
20 changes: 0 additions & 20 deletions docs/snippets/solid/my-component-with-env-variables.ts.mdx
View file
Open in desktop

This file was deleted.

19 changes: 0 additions & 19 deletions docs/snippets/svelte/my-component-with-env-variables.js.mdx
View file
Open in desktop

This file was deleted.

15 changes: 0 additions & 15 deletions docs/snippets/vue/my-component-with-env-variables.js.mdx
View file
Open in desktop

This file was deleted.

21 changes: 0 additions & 21 deletions docs/snippets/vue/my-component-with-env-variables.ts-4-9.mdx
View file
Open in desktop

This file was deleted.

21 changes: 0 additions & 21 deletions docs/snippets/vue/my-component-with-env-variables.ts.mdx
View file
Open in desktop

This file was deleted.

14 changes: 14 additions & 0 deletions docs/snippets/web-components/my-component-vite-env-variables.js.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
```js
// MyComponent.stories.js

export default {
component: 'my-component',
};

export const ExampleStory = {
args: {
propertyA: import.meta.env.STORYBOOK_DATA_KEY,
propertyB: import.meta.env.VITE_CUSTOM_VAR,
},
};
```
19 changes: 19 additions & 0 deletions docs/snippets/web-components/my-component-vite-env-variables.ts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
```ts
// MyComponent.stories.ts

import type { Meta, StoryObj } from '@storybook/web-components';

const meta: Meta = {
component: 'my-component',
};

export default meta;
type Story = StoryObj;

export const ExampleStory: Story = {
args: {
propertyA: import.meta.env.STORYBOOK_DATA_KEY,
propertyB: import.meta.env.VITE_CUSTOM_VAR,
},
};
```