Skip to content

Commit a77de33

Browse files
anselm94LekoArtsgatsbybot
authored
chore(docs): Update Storybook guide to v6 (#31653)
* Added Storybook v6 section - Updated Storybook v6 section as per this [guide](https://gist.github.com/shilman/8856ea1786dcd247139b47b270912324) to use Webpack v5 version - Since [Webpack v5 bundler experimental support](https://storybook.js.org/blog/storybook-for-webpack-5/) will work without much fuss in the upcoming v6.3.0 (currently in beta), this guide may require slight modification in the coming days * updated docs for storybook v6.3 and webpack 5 * remove stale whitespaces * Update visual-testing-with-storybook.md * chore: format * Update visual-testing-with-storybook.md * Update visual-testing-with-storybook.md Co-authored-by: Lennart <[email protected]> Co-authored-by: gatsbybot <[email protected]>
1 parent 72657b5 commit a77de33

File tree

1 file changed

+44
-197
lines changed

1 file changed

+44
-197
lines changed

‎docs/docs/how-to/testing/visual-testing-with-storybook.md

+44-197
Original file line numberDiff line numberDiff line change
@@ -11,260 +11,109 @@ As your project grows over time having this information available will be invalu
1111

1212
## Setting up your environment
1313

14-
> Note that the following instructions are using [npx](https://www.npmjs.com/package/npx). `npx` is a part of npm and in this case it allows you to automatically generate a file/folder structure complete with the default configuration. If you're running an older version of `npm` (`<5.2.0`) you should run the following command instead: `npm install -g @storybook/cli`. You can then run `sb init` from your Gatsby root directory to initialize Storybook.
14+
> **Note:** The following instructions are using [npx](https://www.npmjs.com/package/npx). `npx` is a part of npm and in this case it allows you to automatically generate a file/folder structure complete with the default configuration. If you're running an older version of `npm` (`<5.2.0`) you should run the following command instead: `npm install -g @storybook/cli`. You can then run `sb init` from your Gatsby root directory to initialize Storybook.
1515
1616
To set up Storybook you need to install dependencies and do some custom configuration. You can get started quickly by using the automated command line tool from your Gatsby root directory:
1717

1818
```shell
1919
npx -p @storybook/cli sb init
2020
```
2121

22-
This command adds a set of boilerplate files for Storybook in your project. However, since this is for a Gatsby project, you need to update the default Storybook configuration a bit so you don't get errors when trying to use Gatsby specific components inside of the stories.
22+
This command adds a set of boilerplate files for Storybook in your project. However, since this is for a Gatsby project, you need to update the default Storybook configuration a bit so you don't get errors when trying to use Gatsby specific components inside of the stories. You should have a configuration file at `.storybook/main.js` now.
2323

24-
### Storybook version 5
24+
## Configuration
2525

26-
Storybook version 5.3 [brought a major change to how Storybook is configured](https://medium.com/storybookjs/declarative-storybook-configuration-49912f77b78).
26+
> **Note:** Make sure that you are using a Storybook version `>=6.3.0` before following the instructions below. For older versions of Storybook you can visit the [Gatsby v2 documentation](https://v2.gatsbyjs.com/docs/how-to/testing/visual-testing-with-storybook/).
2727
28-
When you first install Storybook the only configuration file that will exist is `.storybook/main.js`, which will have the default stories location and default addons.
28+
Storybook v6 uses webpack v4 by default, while Gatsby uses webpack v5. Hence, the webpack version for Storybook should be changed to match that of Gatsby to prevent conflicts. Storybook has [official webpack v5 support](https://storybook.js.org/blog/storybook-for-webpack-5/) and can be enabled in your Storybook config.
29+
30+
Install the necessary npm packages:
31+
32+
```shell
33+
npm i -D @storybook/builder-webpack5 @storybook/manager-webpack5
34+
```
35+
36+
Update your `.storybook/main.js` file to use webpack v5:
2937

3038
```js:title=.storybook/main.js
3139
module.exports = {
32-
stories: ["../stories/**/*.stories.js"],
33-
addons: ["@storybook/addon-actions", "@storybook/addon-links"],
40+
core: {
41+
builder: "webpack5",
42+
},
3443
}
3544
```
3645

37-
Adjustments to Storybook's default `webpack` configuration are required so that you can transpile Gatsby source files and to ensure you have the necessary Babel plugins to transpile Gatsby components. Add the following section to the `module.exports` object in `.storybook/main.js`.
46+
Adjustments to Storybook's default webpack configuration are required so that you can transpile Gatsby source files and to ensure you have the necessary Babel plugins to transpile Gatsby components. Add the following section to your `.storybook/main.js`:
3847

3948
```js:title=.storybook/main.js
40-
webpackFinal: async config => {
41-
// Transpile Gatsby module because Gatsby includes un-transpiled ES6 code.
49+
module.exports = {
50+
webpackFinal: async config => {
51+
// transpile Gatsby module because Gatsby includes un-transpiled ES6 code.
4252
config.module.rules[0].exclude = [/node_modules\/(?!(gatsby)\/)/]
4353

44-
// use installed babel-loader which is v8.0-beta (which is meant to work with @babel/core@7)
45-
config.module.rules[0].use[0].loader = require.resolve("babel-loader")
46-
47-
// use @babel/preset-react for JSX and env (instead of staged presets)
48-
config.module.rules[0].use[0].options.presets = [
49-
require.resolve("@babel/preset-react"),
50-
require.resolve("@babel/preset-env"),
51-
]
52-
53-
config.module.rules[0].use[0].options.plugins = [
54-
// use @babel/plugin-proposal-class-properties for class arrow functions
55-
require.resolve("@babel/plugin-proposal-class-properties"),
56-
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
57-
require.resolve("babel-plugin-remove-graphql-queries"),
58-
]
59-
60-
// Prefer Gatsby ES6 entrypoint (module) over commonjs (main) entrypoint
61-
config.resolve.mainFields = ["browser", "module", "main"];
54+
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
55+
config.module.rules[0].use[0].options.plugins.push(
56+
require.resolve("babel-plugin-remove-graphql-queries")
57+
)
6258

63-
return config;
59+
return config
6460
},
61+
}
6562
```
6663

67-
The final output will look as follows:
64+
The final `.storybook/main.js` should look something like this:
6865

6966
```js:title=.storybook/main.js
7067
module.exports = {
71-
// You will want to change this to wherever your Stories will live.
72-
stories: ["../stories/**/*.stories.js"],
73-
addons: ["@storybook/addon-actions", "@storybook/addon-links"],
68+
// You will want to change this to wherever your Stories will live
69+
stories: ["../src/**/*.stories.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
70+
addons: ["@storybook/addon-links", "@storybook/addon-essentials"],
7471
// highlight-start
72+
core: {
73+
builder: "webpack5",
74+
},
7575
webpackFinal: async config => {
7676
// Transpile Gatsby module because Gatsby includes un-transpiled ES6 code.
7777
config.module.rules[0].exclude = [/node_modules\/(?!(gatsby)\/)/]
7878

79-
// use installed babel-loader which is v8.0-beta (which is meant to work with @babel/core@7)
80-
config.module.rules[0].use[0].loader = require.resolve("babel-loader")
81-
82-
// use @babel/preset-react for JSX and env (instead of staged presets)
83-
config.module.rules[0].use[0].options.presets = [
84-
require.resolve("@babel/preset-react"),
85-
require.resolve("@babel/preset-env"),
86-
]
87-
88-
config.module.rules[0].use[0].options.plugins = [
89-
// use @babel/plugin-proposal-class-properties for class arrow functions
90-
require.resolve("@babel/plugin-proposal-class-properties"),
91-
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
92-
require.resolve("babel-plugin-remove-graphql-queries"),
93-
]
94-
95-
// Prefer Gatsby ES6 entrypoint (module) over commonjs (main) entrypoint
96-
config.resolve.mainFields = ["browser", "module", "main"]
79+
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
80+
config.module.rules[0].use[0].options.plugins.push(
81+
require.resolve("babel-plugin-remove-graphql-queries")
82+
)
9783

9884
return config
9985
},
10086
// highlight-end
10187
}
10288
```
10389

104-
Next create a new file under `.storybook` called `preview.js`. This configuration file preview.js is not responsible for loading any stories. Its main purpose is to add global parameters and [decorators](https://storybook.js.org/docs/addons/introduction/#1-decorators).
90+
Create a new file under `.storybook` called `preview.js`. This configuration file `preview.js` is not responsible for loading any stories but for [configuring story rendering](https://storybook.js.org/docs/react/configure/overview#configure-story-rendering). Its main purpose is to add [global parameters](https://storybook.js.org/docs/react/writing-stories/parameters#global-parameters) and [decorators](https://storybook.js.org/docs/react/writing-stories/decorators).
10591

10692
```js:title=.storybook/preview.js
10793
import { action } from "@storybook/addon-actions"
10894

10995
// Gatsby's Link overrides:
11096
// Gatsby Link calls the `enqueue` & `hovering` methods on the global variable ___loader.
11197
// This global object isn't set in storybook context, requiring you to override it to empty functions (no-op),
112-
// so Gatsby Link doesn't throw any errors.
98+
// so Gatsby Link doesn't throw errors.
11399
global.___loader = {
114100
enqueue: () => {},
115101
hovering: () => {},
116102
}
117-
// This global variable is prevents the "__BASE_PATH__ is not defined" error inside Storybook.
103+
// This global variable prevents the "__BASE_PATH__ is not defined" error inside Storybook.
118104
global.__BASE_PATH__ = "/"
119105

120106
// Navigating through a gatsby app using gatsby-link or any other gatsby component will use the `___navigate` method.
121-
// In Storybook it makes more sense to log an action than doing an actual navigate. Checkout the actions addon docs for more info: https://github.com/storybookjs/storybook/tree/master/addons/actions.
107+
// In Storybook it makes more sense to log an action than doing an actual navigate. Checkout the actions addon docs for more info: https://github.com/storybookjs/storybook/tree/master/addons/actions
122108

123109
window.___navigate = pathname => {
124110
action("NavigateTo:")(pathname)
125111
}
126112
```
127113

128-
#### Add TypeScript Support
129-
130-
To configure TypeScript with Storybook and Gatsby, add the following configuration to `.storybook/main.js`.
114+
## TypeScript Support
131115

132-
Add `tsx` as a file type to look for in the `stories` array. This assumes the default Storybook path, but the array configuration can be modified to where your stories live.
133-
134-
```js:title=.storybook/main.js
135-
stories: ["../stories/**/*.stories.js","../stories/**/*.stories.tsx"],
136-
```
137-
138-
Add the following code after the line containing `config.resolve.mainFields = ["browser", "module", "main"];` (line 25) and before the `return config;` in the same function body (line 27):
139-
140-
```js:title=.storybook/main.js
141-
config.module.rules.push({
142-
test: /\.(ts|tsx)$/,
143-
loader: require.resolve("babel-loader"),
144-
options: {
145-
presets: [["react-app", { flow: false, typescript: true }]],
146-
plugins: [
147-
require.resolve("@babel/plugin-proposal-class-properties"),
148-
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
149-
require.resolve("babel-plugin-remove-graphql-queries"),
150-
],
151-
},
152-
})
153-
154-
config.resolve.extensions.push(".ts", ".tsx")
155-
```
156-
157-
The final output, with TypeScript support, will look as follows:
158-
159-
```js:title=.storybook/main.js
160-
module.exports = {
161-
// highlight-start
162-
stories: ["../stories/**/*.stories.js", "../stories/**/*.stories.tsx"],
163-
// highlight-end
164-
addons: ["@storybook/addon-actions", "@storybook/addon-links"],
165-
webpackFinal: async config => {
166-
// Transpile Gatsby module because Gatsby includes un-transpiled ES6 code.
167-
config.module.rules[0].exclude = [/node_modules\/(?!(gatsby)\/)/]
168-
169-
// use installed babel-loader which is v8.0-beta (which is meant to work with @babel/core@7)
170-
config.module.rules[0].use[0].loader = require.resolve("babel-loader")
171-
172-
// use @babel/preset-react for JSX and env (instead of staged presets)
173-
config.module.rules[0].use[0].options.presets = [
174-
require.resolve("@babel/preset-react"),
175-
require.resolve("@babel/preset-env"),
176-
]
177-
178-
config.module.rules[0].use[0].options.plugins = [
179-
// use @babel/plugin-proposal-class-properties for class arrow functions
180-
require.resolve("@babel/plugin-proposal-class-properties"),
181-
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
182-
require.resolve("babel-plugin-remove-graphql-queries"),
183-
]
184-
185-
// Prefer Gatsby ES6 entrypoint (module) over commonjs (main) entrypoint
186-
config.resolve.mainFields = ["browser", "module", "main"]
187-
188-
// highlight-start
189-
config.module.rules.push({
190-
test: /\.(ts|tsx)$/,
191-
loader: require.resolve("babel-loader"),
192-
options: {
193-
presets: [["react-app", { flow: false, typescript: true }]],
194-
plugins: [
195-
require.resolve("@babel/plugin-proposal-class-properties"),
196-
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
197-
require.resolve("babel-plugin-remove-graphql-queries"),
198-
],
199-
},
200-
})
201-
202-
config.resolve.extensions.push(".ts", ".tsx")
203-
204-
// highlight-end
205-
return config
206-
},
207-
}
208-
```
209-
210-
The `babel-preset-react-app` package will also need to be installed.
211-
212-
```shell
213-
npm install --save-dev babel-preset-react-app
214-
```
215-
216-
With setup completed for Storybook 5, you can continue with the [information below to write stories](#writing-stories).
217-
218-
### Storybook version 4
219-
220-
To use Storybook version 4 with Gatsby, use the following setup instructions:
221-
222-
```js:title=.storybook/webpack.config.js
223-
module.exports = (baseConfig, env, defaultConfig) => {
224-
// Transpile Gatsby module because Gatsby includes un-transpiled ES6 code.
225-
defaultConfig.module.rules[0].exclude = [/node_modules\/(?!(gatsby)\/)/]
226-
227-
// use installed babel-loader which is v8.0-beta (which is meant to work with @babel/core@7)
228-
defaultConfig.module.rules[0].use[0].loader = require.resolve("babel-loader")
229-
230-
// use @babel/preset-react for JSX and env (instead of staged presets)
231-
defaultConfig.module.rules[0].use[0].options.presets = [
232-
require.resolve("@babel/preset-react"),
233-
require.resolve("@babel/preset-env"),
234-
]
235-
236-
defaultConfig.module.rules[0].use[0].options.plugins = [
237-
// use @babel/plugin-proposal-class-properties for class arrow functions
238-
require.resolve("@babel/plugin-proposal-class-properties"),
239-
// use babel-plugin-remove-graphql-queries to remove static queries from components when rendering in storybook
240-
require.resolve("babel-plugin-remove-graphql-queries"),
241-
]
242-
243-
// Prefer Gatsby ES6 entrypoint (module) over commonjs (main) entrypoint
244-
defaultConfig.resolve.mainFields = ["browser", "module", "main"]
245-
246-
return defaultConfig
247-
}
248-
```
249-
250-
Once you have this configured you should run Storybook to ensure it can start up properly and you can see the default stories installed by the CLI. To run storybook:
251-
252-
```shell
253-
npm run storybook
254-
```
255-
256-
Storybook CLI adds this command to your `package.json` for you so you shouldn't have to anything other than run the command. If Storybook builds successfully you should be able to navigate to `http://localhost:6006` and see the default stories supplied by the Storybook CLI.
257-
258-
However, if you use `StaticQuery` or `useStaticQuery` in your project Storybook needs to be run with the `NODE_ENV` set to `production` (as Storybook sets this by default to `development`). Otherwise `babel-plugin-remove-graphql-queries` won't be run. Moreover Storybook needs to know about [static files](https://storybook.js.org/docs/configurations/serving-static-files/#2-via-a-directory) generated by Gatsby's `StaticQuery`. Your scripts should look like:
259-
260-
```json:title=package.json
261-
{
262-
"scripts": {
263-
"storybook": "NODE_ENV=production start-storybook -s public",
264-
"build-storybook": "NODE_ENV=production build-storybook -s public"
265-
}
266-
}
267-
```
116+
The Storybook v6 has [out-of-the-box support for TypeScript](https://storybook.js.org/docs/react/configure/typescript). The stories and components can be authored with `.tsx` extension
268117

269118
## Writing stories
270119

@@ -292,6 +141,4 @@ This is a very simple story without much going on, but honestly, nothing else re
292141

293142
## Other resources
294143

295-
- For more information on Storybook, visit
296-
[the Storybook site](https://storybook.js.org/).
297-
- Get started with a [Jest and Storybook starter](https://github.com/Mathspy/gatsby-storybook-jest-starter)
144+
- For more information on Storybook, visit [the Storybook site](https://storybook.js.org/)

0 commit comments

Comments
 (0)