From a55a776445f0f7f1f8581452ae8137d9e7747f70 Mon Sep 17 00:00:00 2001 From: Norbert de Langen Date: Sat, 27 May 2017 02:14:06 +0200 Subject: [PATCH] FIX codemod && ADD migration.md && ADD story shots to addon gallery --- MIGRATION.md | 87 +++++++++++++++++++ docs/pages/addons/addon-gallery/index.md | 13 +++ docs/pages/basics/writing-stories/index.md | 1 + .../pages/configurations/cli-options/index.md | 34 ++++---- .../custom-webpack-config/index.md | 2 +- .../serving-static-files/index.md | 1 - lib/codemod/README.md | 12 +-- .../transforms/update-organisation-name.js | 1 + 8 files changed, 125 insertions(+), 26 deletions(-) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 000000000000..f97acf108527 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,87 @@ +# Migration + +## Table of contents + +- [from version 2.x.x to 3.x.x](#from-version-2xx-to-3xx) + - [Webpack upgrade](#webpack-upgrade) + - [Packages renaming](#packages-renaming) + - [Deprecated embedded addons](#deprecated-embedded-addons) + +## from version 2.x.x to 3.x.x + +This major release is mainly an internal restructuring. +Upgrading requires work on behalf of users, this was unavoidable. +We're sorry if this inconveniences you, we have tried via this document and provided tools to make the process as easy as possible. + +### Webpack upgrade + +Storybook will now use webpack 2 (and only webpack 2). +If you are using a custom `webpack.config.js` you need to change this to be compatible. +You can find the guide to upgrading your webpack config [on webpack.js.org](https://webpack.js.org/guides/migrating/). + +### Packages renaming + +All our packages have been renamed and published to npm as version 3.0.0. + +> We have adopted the same versioning strategy as have been adopted by babel, jest and apollo. +> It's a strategy best suited for ecosystem type tools, which consist of many seperately installable features / packages. +> We think this describes storybook pretty well. + +The new package names are: + +| old | new | +| -------------------------------------------- | -------------------------------- | +| `getstorybook` | `@storybook/cli` | +| `@kadira/getstorybook` | `@storybook/cli` | +| | | +| `@kadira/storybook` | `@storybook/react` | +| `@kadira/react-storybook` | `@storybook/react` | +| `@kadira/react-native-storybook` | `@storybook/react-native` | +| | | +| `storyshots` | `@storybook/addon-storyshots` | +| `@kadira/storyshots` | `@storybook/addon-storyshots` | +| | | +| `@kadira/storybook-ui` | `@storybook/ui` | +| `@kadira/storybook-addons` | `@storybook/addons` | +| `@kadira/storybook-channels` | `@storybook/channels` | +| `@kadira/storybook-channel-postmsg` | `@storybook/channel-postmessage` | +| `@kadira/storybook-channel-websocket` | `@storybook/channel-websocket` | +| | | +| `@kadira/storybook-addon-actions` | `@storybook/addon-actions` | +| `@kadira/storybook-addon-links` | `@storybook/addon-links` | +| `@kadira/storybook-addon-info` | `@storybook/addon-info` | +| `@kadira/storybook-addon-knobs` | `@storybook/addon-knobs` | +| `@kadira/storybook-addon-comments` | `@storybook/addon-comments` | +| `@kadira/storybook-addon-notes` | `@storybook/addon-notes` | +| `@kadira/storybook-addon-options` | `@storybook/addon-options` | +| `@kadira/storybook-addon-graphql` | `@storybook/addon-graphql` | +| `@kadira/react-storybook-decorator-centered` | `@storybook/addon-centered` | + +If your codebase is small, it's probably doable to just replace them by hand. (in your codebase and in `package.json`). + +But if you have a lot of occurances in your codebase, you can use a [codemod we created](./lib/codemod) for you. + +You have to change your `package.json`, prune old and install new dependencies by hand. + +`npm prune` will remove all dependecies from `node_modules` which are no longer referenced in `package.json`. + +### Deprecated embedded addons + +We used to ship 2 addons with every single installation of storybook: `actions` and `links`. But in practice not everyone is using them, so we decided to deprecate this and in the future they will be completely removed. If you use `@storybook/react/addons` you will get a deprecation warning. + +If you **are** using these addons, migrating is simple: + +- add the addons you use to your `package.json`. +- change your code to this: + change `addons.js` like so: + ```js + import '@storybook/addon-actions/register'; + import '@storybook/addon-links/register'; + ``` + change `x.story.js` like so: + ```js + import React from 'react'; + import { storiesOf } from '@storybook/react'; + import { action } from '@storybook/addon-actions'; + import { link } from '@storybook/addon-links'; + ``` diff --git a/docs/pages/addons/addon-gallery/index.md b/docs/pages/addons/addon-gallery/index.md index 2dc72518c701..6aa6e9057ef2 100644 --- a/docs/pages/addons/addon-gallery/index.md +++ b/docs/pages/addons/addon-gallery/index.md @@ -36,45 +36,58 @@ If you are using Storybook as a style guide, then this addon will help you to bu The Storybook webapp UI can be customised with this addon. It can be used to change the header, show/hide various UI elements and to enable full-screen mode by default. +### [Storyshots](https://github.com/storybooks/storybook/tree/master/addons/storyshots) + +Storyshots is a way to automaticly jest-snapshot all your stories. [More info here](../testing/structural-testing#). ## Community Addons You need to install these addons directly from NPM in order to use them. ### [README](https://github.com/tuchk4/storybook-readme) + With this addon, you can add docs in markdown format for each story. It very useful because most projects and components already have README.md files. Now it is easy to add them into your Storybook. ### [Story-router](https://github.com/gvaldambrini/storybook-router) + A [decorator](/addons/introduction) that allows you to integrate react-router components in your stories. ### [Host](https://github.com/philcockfield/storybook-host) + A [decorator](/addons/introduction) with powerful display options for hosting, sizing and framing your components. ### [Specs](https://github.com/mthuret/storybook-addon-specifications) + This is a very special addon where it'll allow you to write test specs directly inside your stories. You can even run these tests inside a CI box. ### [Chapters](https://github.com/yangshun/react-storybook-addon-chapters) + With this addon, you can showcase multiple components (or varying component states) within 1 story. Break your stories down into smaller categories (chapters) and subcategories (sections) for more organizational goodness. ### [Props Combinations](https://github.com/evgenykochetkov/react-storybook-addon-props-combinations) + Given possible values for each prop, renders your component with all combinations of prop values. Useful for finding edge cases or just seeing all component states at once. ### [Backgrounds](https://github.com/NewSpring/react-storybook-addon-backgrounds) + With this addon, you can switch between background colors and background images for your preview components. It is really helpful for styleguides. ### [Material-UI](https://github.com/sm-react/storybook-addon-material-ui) + Wraps your story into MuiThemeProvider. It allows you to add your custom themes, switch between them, make changes in the visual editor and download as JSON file ### [i18n tools](https://github.com/joscha/storybook-addon-i18n-tools) + With this addon, you can test your storybooks with a different text-direction. It is very useful if you are working on components that have to work both in LTR as well as in RTL languages. ### [JSX preview](https://github.com/Kilix/storybook-addon-jsx) + This addon shows a preview of the JSX code for each story. It allows you to configure the display and copy the code with a single click. diff --git a/docs/pages/basics/writing-stories/index.md b/docs/pages/basics/writing-stories/index.md index 47daae18cbc4..36eaeb115fc5 100644 --- a/docs/pages/basics/writing-stories/index.md +++ b/docs/pages/basics/writing-stories/index.md @@ -123,6 +123,7 @@ storiesOf('core.Button', module) Then you can filter stories to display only the stories you want to see. ### [Chapters](https://github.com/yangshun/react-storybook-addon-chapters) + With this addon, you can showcase multiple components (or varying component states) within 1 story. Break your stories down into smaller categories (chapters) and subcategories (sections) for more organizational goodness. diff --git a/docs/pages/configurations/cli-options/index.md b/docs/pages/configurations/cli-options/index.md index f4fcf8bb6529..ab002ee0073e 100644 --- a/docs/pages/configurations/cli-options/index.md +++ b/docs/pages/configurations/cli-options/index.md @@ -11,29 +11,25 @@ Here are all those options: ## For start-storybook -``` -Usage: start-storybook [options] + Usage: start-storybook [options] -Options: + Options: - -h, --help output usage information - -V, --version output the version number - -p, --port [number] Port to run Storybook (Required) - -h, --host [string] Host to run Storybook - -s, --static-dir Directory where to load static files from - -c, --config-dir [dir-name] Directory where to load Storybook configurations from -``` + -h, --help output usage information + -V, --version output the version number + -p, --port [number] Port to run Storybook (Required) + -h, --host [string] Host to run Storybook + -s, --static-dir Directory where to load static files from + -c, --config-dir [dir-name] Directory where to load Storybook configurations from ## For build-storybook -``` -Usage: build-storybook [options] + Usage: build-storybook [options] -Options: + Options: - -h, --help output usage information - -V, --version output the version number - -s, --static-dir Directory where to load static files from - -o, --output-dir [dir-name] Directory where to store built files - -c, --config-dir [dir-name] Directory where to load Storybook configurations from -``` + -h, --help output usage information + -V, --version output the version number + -s, --static-dir Directory where to load static files from + -o, --output-dir [dir-name] Directory where to store built files + -c, --config-dir [dir-name] Directory where to load Storybook configurations from diff --git a/docs/pages/configurations/custom-webpack-config/index.md b/docs/pages/configurations/custom-webpack-config/index.md index bfa2b6849c93..50e04edf57fa 100644 --- a/docs/pages/configurations/custom-webpack-config/index.md +++ b/docs/pages/configurations/custom-webpack-config/index.md @@ -13,7 +13,7 @@ There are a few ways to do it: ## Extend Mode -You'll get *extend-mode* by returning an object. +You'll get _extend-mode_ by returning an object. Let's say you want to add [SASS](http://sass-lang.com/) support to Storybook. This is how to do it. Simply add the following content to a file called `webpack.config.js` in your Storybook config directory (`.storybook` by default ). diff --git a/docs/pages/configurations/serving-static-files/index.md b/docs/pages/configurations/serving-static-files/index.md index fb20ec9e0c1f..d73462fdb0a6 100644 --- a/docs/pages/configurations/serving-static-files/index.md +++ b/docs/pages/configurations/serving-static-files/index.md @@ -78,7 +78,6 @@ storiesOf('', module) )); ``` - ## Absolute versus relative paths Sometimes, you may want to deploy your storybook into a subpath, like . diff --git a/lib/codemod/README.md b/lib/codemod/README.md index 693b2b6b57e6..f1f84352c6e5 100644 --- a/lib/codemod/README.md +++ b/lib/codemod/README.md @@ -17,8 +17,8 @@ npm install jscodeshift npm install @storybook/codemod ``` -- `@storybook/codemod` is out collection of codemod scripts. -- `jscodeshift` is a tool we use to apply our codemods. +- `@storybook/codemod` is out collection of codemod scripts. +- `jscodeshift` is a tool we use to apply our codemods. After running the migration commands, you can remove them from your `package.json`, if you added them. @@ -27,14 +27,14 @@ After running the migration commands, you can remove them from your `package.jso From the directory where you installed both `jscodeshift` and `@storybook/codemod` run: Example: + ```sh ./node_modules/.bin/jscodeshift -t ../react-storybook/lib/codemod/dist/update-organisation-name.js . --ignore-pattern "node_modules|dist" ``` Explanation: -``` - -t --ignore-pattern "" -``` + + -t --ignore-pattern "" ## Transforms @@ -49,12 +49,14 @@ Updates package names in imports to migrate to the new package names of storyboo There's a mapping of paths we replace but this example explains the gist of it: Example: + ```js import { storiesOf } from '@kadira/storybook'; import { storiesOf } from '@kadira/storybook-addon-links'; ``` Becomes + ```js import { storiesOf } from '@storybook/react'; import { storiesOf } from '@storybook/addon-links'; diff --git a/lib/codemod/src/transforms/update-organisation-name.js b/lib/codemod/src/transforms/update-organisation-name.js index db8ad7acd8d9..cfaf5afecbdb 100644 --- a/lib/codemod/src/transforms/update-organisation-name.js +++ b/lib/codemod/src/transforms/update-organisation-name.js @@ -4,6 +4,7 @@ export default function transformer(file, api) { const packageNames = { '@kadira/react-storybook-decorator-centered': '@storybook/addon-centered', '@kadira/storybook-addons': '@storybook/addons', + '@kadira/storybook-addon-actions': '@storybook/addon-actions', '@kadira/storybook-addon-comments': '@storybook/addon-comments', '@kadira/storybook-addon-graphql': '@storybook/addon-graphql', '@kadira/storybook-addon-info': '@storybook/addon-info',