GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-03-17 05:02:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

Zero-config typescript: Updated MIGRATION and storybook documentation

Browse Source
This commit is contained in:
Michael Shilman 2020-05-20 16:35:20 +08:00
parent 3f4d4ef98d
commit 4a4ccb48e6
2 changed files with 38 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
MIGRATION.md
View File

@ -1,6 +1,7 @@
<h1>Migration</h1>
- [From version 5.3.x to 6.0.x](#from-version-53x-to-60x)
- [Zero config typescript](#zero-config-typescript)
- [Backgrounds addon has a new api](#backgrounds-addon-has-a-new-api)
- [CRA preset removed](#cra-preset-removed)
- [Args passed as first argument to story](#args-passed-as-first-argument-to-story)
@ -113,6 +114,12 @@
## From version 5.3.x to 6.0.x
### Zero config typescript
Storybook has built-in Typescript support in 6.0. That means you should remove your complex Typescript configurations from your `.storybook` config. We've tried to pick sensible defaults that work out of the box, especially for nice prop table generation in `@storybook/addon-docs`.
To migrate from an old setup, we recommend deleting any typescript-specific webpack/babel configurations in your project. If you want to override the defaults, see the [typescript configuration docs](https://github.com/storybookjs/storybook/blob/next/docs/src/pages/configurations/typescript-config/index.md).
### Backgrounds addon has a new api
Starting in 6.0, the backgrounds addon now receives an object instead of an array as parameter, with a property to define the default background.

241
docs/src/pages/configurations/typescript-config/index.md
View File

@ -3,235 +3,56 @@ id: 'typescript-config'
title: 'TypeScript Config'
---
> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
Storybook has built-in Typescript support, so your Typescript project should work with zero configuration needed.
This is a central reference for using Storybook with TypeScript.
- [Default configuration](#default-configuration)
- [Main.js configuration](#mainjs-configuration)
- [Manual configuration](#manual-configuration)
- [More Resources](#more-resources)
## Typescript configuration presets
## Default configuration
The fastest and easiest way to write and configure your stories in TypeScript is by using a Storybook preset.
The base Typescript configuration uses `babel-loader` for Typescript transpilation, and optionally `fork-ts-checker-webpack-plugin` for checking.
* If you're using Create React App (CRA) and have configured it to work with TS, you should use [`@storybook/preset-create-react-app`](https://github.com/storybookjs/presets/tree/master/packages/preset-create-react-app), which configures Storybook to reuse CRA's TS handling.
Each framework uses the base configuration unless otherwise specified:
* If you are not using CRA or have other requirements, then the next best option is [`@storybook/preset-typescript`](https://github.com/storybookjs/presets/tree/master/packages/preset-typescript), which configures `ts-loader` under the hood.
- **Angular** ignores the base and uses `ts-loader` and `ngx-template-loader`.
- **Vue** ignores the uses `ts-loader` and applies it to both `.tsx?` and `.vue` files.
- **React** adds `react-docgen-typescript-loader` the base.
If you need more control than these presets offer, read on for manual configuration instructions.
## Main.js configuration
You can learn more about Storybook presets [over here](../../presets/introduction).
To make it easier to configure Typescript handling, we've added a new field, `typescript`, to [`main.js`](../overview/index.md).
> If using TypeScript, some addons require features available in TS version 3.4+.
## Setting up TypeScript with ts-loader
### Dependencies you may need
```bash
yarn add -D typescript
yarn add -D ts-loader
yarn add -D @storybook/addon-info react-docgen-typescript-loader # optional but recommended
yarn add -D jest "@types/jest" ts-jest #testing
```
### Setting up TypeScript to work with Storybook
We [configure storybook's webpack](/configurations/custom-webpack-config/#full-control-mode--default) by changing `.storybook/main.js`:
Here are the default values:
```js
module.exports = {
webpackFinal: async config => {
config.module.rules.push({
test: /\.(ts|tsx)$/,
use: [
{
loader: require.resolve('ts-loader'),
},
// Optional
{
loader: require.resolve('react-docgen-typescript-loader'),
},
],
});
config.resolve.extensions.push('.ts', '.tsx');
return config;
},
};
```
The above example shows a working Webpack config with the [TSDocgen plugin](https://github.com/strothj/react-docgen-typescript-loader) integrated. This plugin is not necessary to use Storybook and the section marked `// optional` can be safely removed if the features of TSDocgen are not required.
### `tsconfig.json`
```json
{
"compilerOptions": {
"outDir": "build/lib",
"module": "commonjs",
"target": "es5",
"lib": ["es5", "es6", "es7", "es2017", "dom"],
"sourceMap": true,
"allowJs": false,
"jsx": "react",
"moduleResolution": "node",
"rootDirs": ["src", "stories"],
"baseUrl": "src",
"forceConsistentCasingInFileNames": true,
"noImplicitReturns": true,
"noImplicitThis": true,
"noImplicitAny": true,
"strictNullChecks": true,
"suppressImplicitAnyIndexErrors": true,
"noUnusedLocals": true,
"declaration": true,
"allowSyntheticDefaultImports": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "build", "scripts"]
}
```
This is for the default configuration where `/stories` is a peer of `src`. If you have them all in `src`, you may wish to replace `"rootDirs": ["src", "stories"]` above with `"rootDir": "src",`.
## Setting up TypeScript with babel-loader
### A note for Create React App users
Please use [`@storybook/preset-create-react-app`](https://github.com/storybookjs/presets/tree/master/packages/preset-create-react-app) for full compatibility with [Create React App](https://create-react-app.dev/) features - which includes TypeScript support.
### Setting up TypeScript to work with Storybook
The following code uses [`babel-preset-react-app`](https://github.com/facebook/create-react-app/tree/master/packages/babel-preset-react-app).
We will create a [custom Webpack config](/configurations/custom-webpack-config/) by creating editing/creating the `.storybook/main.js`:
```js
module.exports = {
stories: ['../src/**/*.stories.tsx'],
webpackFinal: async config => {
config.module.rules.push({
test: /\.(ts|tsx)$/,
loader: require.resolve('babel-loader'),
options: {
presets: [['react-app', { flow: false, typescript: true }]],
},
});
config.resolve.extensions.push('.ts', '.tsx');
return config;
},
};
```
### `tsconfig.json`
If your stories are outside the `src` folder, for example the `stories` folder in root, then `"rootDirs": ["src", "stories"]` needs to be added to be added to `compilerOptions` so it knows what folders to compile. Make sure `jsx` is set to preserve. Should be unchanged.
## Create a TSX storybook index
The default storybook index file is `stories/index.stories.js` -- you'll want to rename this to `stories/index.stories.tsx`.
## Using TypeScript with the TSDocgen addon
The very handy [Storybook Info addon](https://github.com/storybookjs/storybook/tree/master/addons/info) autogenerates prop tables documentation for each component, however it doesn't work with Typescript types. The current solution is to use [react-docgen-typescript-loader](https://github.com/strothj/react-docgen-typescript-loader) to preprocess the TypeScript files to give the Info addon what it needs. The webpack config above does this, and so for the rest of your stories you use it as per normal:
```js
import * as React from 'react';
import TicTacToeCell from './TicTacToeCell';
export default {
title: 'Components',
parameters: {
info: { inline: true },
},
};
export const TicTacToeCell = () => (
<TicTacToeCell value="X" position={{ x: 0, y: 0 }} />,
);
```
## Customizing Type annotations/descriptions
Please refer to the [react-docgen-typescript-loader](https://github.com/strothj/react-docgen-typescript-loader) docs for writing prop descriptions and other annotations to your Typescript interfaces.
Additional annotation can be achieved by setting a default set of info parameters in `.storybook/preview.js`:
```ts
import { addDecorator } from '@storybook/react';
import { withInfo } from '@storybook/addon-info';
addDecorator(
withInfo({
styles: {
header: {
h1: {
marginRight: '20px',
fontSize: '25px',
display: 'inline',
},
body: {
paddingTop: 0,
paddingBottom: 0,
},
h2: {
display: 'inline',
color: '#999',
},
},
infoBody: {
backgroundColor: '#eee',
padding: '0px 5px',
lineHeight: '2',
},
typescript: {
check: false,
checkOptions: {},
reactDocgen: 'react-docgen-typescript',
reactDocgenTypescriptOptions: {
propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
},
inline: true,
source: false,
})
);
```
Note: Component docgen information can not be generated for components that are only exported as default. You can work around the issue by exporting the component using a named export.
## Setting up Jest tests
The ts-jest [README](https://github.com/kulshekhar/ts-jest) explains pretty clearly how to get Jest to recognize TypeScript code.
This is an example `jest.config.js` file for jest:
```js
module.exports = {
transform: {
'.(ts|tsx)': 'ts-jest',
},
testPathIgnorePatterns: ['/node_modules/', '/lib/'],
testRegex: '(/test/.*|\\.(test|spec))\\.(ts|tsx|js)$',
moduleFileExtensions: ['ts', 'tsx', 'js', 'json'],
};
```
## Building your TypeScript Storybook
And here are the meaning of each field:
You will need to set up some scripts - these may help:
| Field | Framework | Description | Type |
| -------------------------------- | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **check** | All | optionally run `fork-ts-checker-webpack-plugin` | `boolean` |
| **checkOptions** | All | Options to pass to `fork-ts-checker-webpack-plugin` if it's enabled | [See docs](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) |
| **reactDocgen** | React | which variant docgen processor to run | `'react-docgen-typescript' | 'react-docgen' | false` |
| **reactDocgenTypescriptOptions** | React | Options to pass to `react-docgen-typescript-loader` if `react-docgen-typescript` is enabled. | [See docs](https://github.com/strothj/react-docgen-typescript-loader) |
```json
"scripts": {
"start": "react-scripts-ts start",
"build": "npm run lint && npm run build-lib && build-storybook",
"build-lib-watch": "tsc -w",
"build-lib": "tsc && npm run copy-css-to-lib && npm run copy-svg-to-lib && npm run copy-png-to-lib && npm run copy-woff2-to-lib",
"test": "react-scripts-ts test --env=jsdom",
"test:coverage": "npm test -- --coverage",
"eject": "react-scripts-ts eject",
"storybook": "start-storybook -p 6006",
"build-storybook": "build-storybook",
"copy-css-to-lib": "cpx \"./src/**/*.css\" ./build/lib",
"copy-woff2-to-lib": "cpx \"./src/**/*.woff2\" ./build/lib",
"copy-svg-to-lib": "cpx \"./src/**/*.svg\" ./build/lib",
"copy-png-to-lib": "cpx \"./src/**/*.png\" ./build/lib",
},
```
## Manual configuration
## Related Issues and Helpful Resources
Manual configuration support will be added in a later pre-release.
## More Resources
- [Storybook, React, TypeScript and Jest](https://medium.com/@mtiller/storybook-react-typescript-and-jest-c9059ea06fa7)
- [React, Storybook & TypeScript](http://www.joshschreuder.me/react-storybooks-with-typescript/)