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

Docs: Update useSWC API reference #22984

Merged
merged 3 commits into from
Jun 12, 2023
Merged

Docs: Update useSWC API reference #22984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b22c1ac
Update `useSWC` docs
kylegach Jun 8, 2023
852cc70
Move "experimental" label beneath heading
kylegach Jun 8, 2023
817d30c
Merge branch 'next' into api-reference-use-swc
jonniebigodes Jun 12, 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
8 changes: 8 additions & 0 deletions docs/api/main-config-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ Type:

Configures Storybook's builder, [Vite](../builders/vite.md) or [Webpack](../builders/webpack.md).

<div class="aside">

💡 With the new [Framework API](./new-frameworks.md), [`framework.options.builder`](./main-config-framework.md#optionsbuilder) is now the preferred way to configure the builder.

You should only use `core.builder.options` if you need to configure a builder that is not part of a framework.

</div>

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

<CodeSnippets
Expand Down
4 changes: 3 additions & 1 deletion docs/api/main-config-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,9 @@ Opts out of [on-demand story loading](#on-demand-story-loading); loads all stori

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

## `argTypeTargetsV7` (EXPERIMENTAL)
## `argTypeTargetsV7`

(⚠️ **Experimental**)

Type: `boolean`

Expand Down
39 changes: 37 additions & 2 deletions docs/api/main-config-framework.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ Required: `true`

Configures Storybook based on a set of [framework-specific](../configure/frameworks.md) settings.

For available frameworks and their options, see their respective [documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks).

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

<CodeSnippets
Expand All @@ -22,3 +20,40 @@ For available frameworks and their options, see their respective [documentation]
/>

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

## `name`

Type: `string`

For available frameworks and their options, see their respective [documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks).

## `options`

Type: `Record<string, any>`

While many options are specific to a framework, there are some options that are shared across some frameworks, e.g. those that configure Storybook's [builder](./main-config-core.md#builder).

### `options.builder`

Type: `Record<string, any>`

Configures Storybook's builder, [Vite](../builders/vite.md) or [Webpack](../builders/webpack.md).

#### `options.builder.useSWC`

(⚠️ **Experimental**)

For frameworks made with the [Webpack](../builders/webpack.md) builder, this option allows you to use the [SWC](https://swc.rs/) compiler instead of [Babel](../configure/babel.md).

When Storybook loads, it will update Webpack's configuration including the required loaders (e.g., [`TerserPlugin`](https://webpack.js.org/plugins/terser-webpack-plugin/), [`babel-loader`](https://webpack.js.org/loaders/babel-loader/)) with SWC equivalents (e.g., [`swc-loader`](https://swc.rs/docs/usage/swc-loader)) for bundling and minification.

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

<CodeSnippets
paths={[
'common/main-config-framework-options-builder-use-swc.js.mdx',
'common/main-config-framework-options-builder-use-swc.ts.mdx',
]}
/>

<!-- prettier-ignore-end -->
10 changes: 5 additions & 5 deletions docs/configure/babel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,19 +133,19 @@ When the command finishes running, it will display the available Babel configura

For more info, please refer to the [Babel documentation](https://babeljs.io/docs/en/configuration#print-effective-configs).

### SWC fallback
### SWC alternative (experimental)

If you're working with a Webpack-based project and having issues with Babel configuration, you can opt into replacing Babel with the [SWC](https://swc.rs/) compiler. To do so, update your Storybook configuration file (e.g., `.storybook/main.js|ts`) to enable the experimental `useSWC` option:
If you're working with a Webpack-based project, you can opt into replacing Babel with the [SWC](https://swc.rs/) compiler, which can be faster for some projects. To do so, update your [Storybook configuration file](../api/main-config.md) (e.g., `.storybook/main.js|ts`) to enable the experimental `useSWC` option:

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

<CodeSnippets
paths={[
'common/storybook-enable-swc-loader.js.mdx',
'common/storybook-enable-swc-loader.ts.mdx',
'common/main-config-framework-options-builder-use-swc.js.mdx',
'common/main-config-framework-options-builder-use-swc.ts.mdx',
]}
/>

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

When Storybook loads, it will update Webpack's configuration including the required loaders (e.g., [`TerserPlugin`](https://webpack.js.org/plugins/terser-webpack-plugin/), [`babel-loader`](https://webpack.js.org/loaders/babel-loader/)) with SWC equivalents (e.g., [`swc-loader`](https://swc.rs/docs/usage/swc-loader)) for bundling and minification.
See the [`useSWC` API reference](../api/main-config-framework.md#optionsbuilderuseswc) for more information.
1 change: 0 additions & 1 deletion docs/configure/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,6 @@ Additionally, you can also provide additional feature flags to your Storybook co
| `storyStoreV7` | Configures Storybook to load stories [on demand](#on-demand-story-loading), rather than during boot up <br/> `features: { storyStoreV7: true }` |
| `buildStoriesJson` | Generates a `stories.json` file to help story loading with the on-demand mode <br/> `features: { buildStoriesJson: true }` |
| `legacyMdx1` | Enables support for MDX version 1 as a fallback. Requires [`@storybook/mdx1-csf`](https://github.com/storybookjs/mdx1-csf) <br/> `features: { legacyMdx1: true }` |
| `useSWC` | Enables experimental support for [SWC](https://swc.rs/) as a Babel alternative for Webpack-based projects<br/> `builder: { useSWC: true }` |

## Configure story loading

Expand Down
5 changes: 0 additions & 5 deletions ...common/storybook-enable-swc-loader.js.mdx → ...-framework-options-builder-use-swc.js.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,5 @@ export default {
},
},
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/addon-interactions',
],
};
```
5 changes: 0 additions & 5 deletions ...common/storybook-enable-swc-loader.ts.mdx → ...-framework-options-builder-use-swc.ts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,6 @@ const config: StorybookConfig = {
},
},
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
Copy link
Contributor

Choose a reason for hiding this comment

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

I've been noticing a pattern of renaming snippets lately, and if you're ok, we'll need to figure out not only the naming convention and what goes in and what doesn't go in them

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yeah, I need to document all of the conventions we're landing on for the docs, particularly the API references. I've waited until the patterns are proved out across more pages, first. Might be that time now, though...

For the snippet names, there's two reasons I changed this one:

  1. It used to be storybook-enable-swc-loader. Nearly all of our snippets pertain to Storybook, so a prefix of storybook- is unnecessary. Also, it's enabling the SWC compiler, not the loader.
  2. The API references (and their snippets) should contain the canonical docs information. Wherever reasonable, the guide pages should reuse and reference what is there. The snippet name reflects that.

addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/addon-interactions',
],
};

export default config;
Expand Down