diff --git a/MIGRATION.md b/MIGRATION.md index 2e5b4eae8b12..ff58f5d72079 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -11,6 +11,7 @@ - [Webpack 4](#webpack-4) - [Babel 7](#babel-7) - [Create-react-app](#create-react-app) + - [CLI rename](#cli-rename) - [From version 3.3.x to 3.4.x](#from-version-33x-to-34x) - [From version 3.2.x to 3.3.x](#from-version-32x-to-33x) - [Refactored Knobs](#refactored-knobs) @@ -65,7 +66,7 @@ Since storybook version v4.0 packager is removed from storybook. The suggested s If you want to keep the old behaviour, you have to start the packager yourself with a different project root. `npm run storybook start -p 7007 | react-native start --projectRoot storybook` -Removed cli options: `--packager-port --root --projectRoots -r, --reset-cache --skip-packager --haul --platform --metro-config` +Removed cli options: `--packager-port --root --projectRoots -r, --reset-cache --skip-packager --haul --platform --metro-config` ### Removed RN addons @@ -134,6 +135,14 @@ Also make sure you have a `.babelrc` in your project directory. You probably alr If you're using `start-storybook` on CI, you may need to opt out of this using the new `--ci` flag. +### CLI Rename + +We've deprecated the `getstorybook` CLI in 4.0. The new way to install storybook is `sb init`. We recommend using `npx` for convenience and to make sure you're always using the latest version of the CLI: + +``` +npx -p @storybook/cli sb init +``` + ## From version 3.3.x to 3.4.x There are no expected breaking changes in the 3.4.x release, but 3.4 contains a major refactor to make it easier to support new frameworks, and we will document any breaking changes here if they arise. diff --git a/README.md b/README.md index 2cd29b9823b2..64847f2d79c4 100644 --- a/README.md +++ b/README.md @@ -10,22 +10,24 @@ [![Backers on Open Collective](https://opencollective.com/storybook/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/storybook/sponsors/badge.svg)](#sponsors) [![License](https://img.shields.io/github/license/storybooks/storybook.svg)](https://github.com/storybooks/storybook/blob/master/LICENSE) + -* * * +--- Storybook is a development environment for UI components. It allows you to browse a component library, view the different states of each component, and interactively develop and test components. ## Intro +
README for: -- [![Alpha](https://img.shields.io/npm/v/@storybook/core/alpha.svg)](https://github.com/storybooks/storybook) -- [![Latest](https://img.shields.io/npm/v/@storybook/core/latest.svg)](https://github.com/storybooks/storybook/tree/release/3.4) +- [![Alpha](https://img.shields.io/npm/v/@storybook/core/alpha.svg)](https://github.com/storybooks/storybook) +- [![Latest](https://img.shields.io/npm/v/@storybook/core/latest.svg)](https://github.com/storybooks/storybook/tree/release/3.4) Storybook runs outside of your app. This allows you to develop UI components in isolation, which can improve component reuse, testability, and development speed. You can build quickly without having to worry about application-specific dependencies. @@ -35,38 +37,36 @@ Storybook comes with a lot of [addons](https://storybook.js.org/addons/introduct ## Table of contents -- 🚀[Getting Started](#getting-started) -- 📒[Projects](#projects) - - 🛠[Supported Frameworks & Examples](#supported-frameworks) - - 🚇[Sub Projects](#sub-projects) - - 🔗[Addons](#addons) -- 🏅[Badges & Presentation materials](#badges--presentation-materials) -- 👥[Community](#community) -- 👏[Contributing](#contributing) - - 👨‍💻[Development scripts](#development-scripts) - - 💵[Backers](#backers) - - 💸[Sponsors](#sponsors) +- 🚀[Getting Started](#getting-started) +- 📒[Projects](#projects) + - 🛠[Supported Frameworks & Examples](#supported-frameworks) + - 🚇[Sub Projects](#sub-projects) + - 🔗[Addons](#addons) +- 🏅[Badges & Presentation materials](#badges--presentation-materials) +- 👥[Community](#community) +- 👏[Contributing](#contributing) + - 👨‍💻[Development scripts](#development-scripts) + - 💵[Backers](#backers) + - 💸[Sponsors](#sponsors) ## Getting Started First install storybook: ```sh -npm i -g @storybook/cli cd my-react-app -getstorybook +npx -p @storybook/cli sb init ``` -The `-g` global install is used to run our cli tool in your project directory to generate templates for your existing projects. To avoid the global install and start your project manually, take a look at our [Slow Start Guide](https://storybook.js.org/basics/slow-start-guide/). +If you'd rather set up your project manually, take a look at our [Slow Start Guide](https://storybook.js.org/basics/slow-start-guide/). Once it's installed, you can `npm run storybook` and it will run the development server on your local machine, and give you a URL to browse some sample stories. -**Storybook v2.x migration note**: If you're using Storybook v2.x and want to shift to 3.x version the easiest way is: +**Storybook v2.x migration note**: If you're using Storybook v2.x and want to shift to 4.x version the easiest way is: ```sh -npm i -g @storybook/cli cd my-storybook-v2-app -getstorybook +npx -p @storybook/cli sb init ``` It runs a codemod to update all package names. Read all migration details in our [Migration Guide](MIGRATION.md) @@ -79,44 +79,44 @@ For additional help, join us [in our Slack](https://now-examples-slackin-rrirkqo ### Supported Frameworks -| Framework | Demo latest | Demo prerelease | | -|----|---|---|---| -| [React](app/react) | [v3.4.x](https://release-3-4--storybooks-official.netlify.com), [v3.3.x](https://release-3-3--storybooks-official.netlify.com) | [v4.0.0-alpha](https://storybooks-official.netlify.com) | [![React](https://img.shields.io/npm/dt/@storybook/react.svg)](app/react) | -| [React Native](app/react-native) | - | - | [![React Native](https://img.shields.io/npm/dt/@storybook/react-native.svg)](app/react-native) | -| [Vue](app/vue) | [v3.4.x](https://release-3-4--storybooks-vue.netlify.com/), [v3.3.x](https://release-3-3--storybooks-vue.netlify.com/) | [v4.0.0-alpha](https://storybooks-vue.netlify.com/) | [![Vue](https://img.shields.io/npm/dt/@storybook/vue.svg)](app/vue) | -| [Angular](app/angular) | [v3.4.x](https://release-3-4--storybooks-angular.netlify.com/), [v3.3.x](https://release-3-3--storybooks-angular.netlify.com/) | [v4.0.0-alpha](https://storybooks-angular.netlify.com/) | [![Angular](https://img.shields.io/npm/dt/@storybook/angular.svg)](app/angular) | -| [Polymer](app/polymer) | [v3.4.x](https://release-3-4--storybooks-polymer.netlify.com/) | [v4.0.0-alpha](https://storybooks-polymer.netlify.com/) | [![Polymer](https://img.shields.io/npm/dt/@storybook/polymer.svg)](app/polymer) | -| [Mithril](app/mithril) alpha | - | [v4.0.0-alpha](https://storybooks-mithril.netlify.com/) | [![Mithril](https://img.shields.io/npm/dt/@storybook/mithril.svg)](app/mithril) | -| [Marko](app/marko) alpha | - | [v4.0.0-alpha](https://storybooks-marko.netlify.com/) | [![Marko](https://img.shields.io/npm/dt/@storybook/marko.svg)](app/marko) | -| [HTML](app/html) alpha | - | [v4.0.0-alpha](https://storybooks-html.netlify.com/) | [![HTML](https://img.shields.io/npm/dt/@storybook/html.svg)](app/html) | -| [Svelte](app/svelte) alpha | - | [v4.0.0-alpha](https://storybooks-svelte.netlify.com/) | [![Svelte](https://img.shields.io/npm/dt/@storybook/svelte.svg)](app/svelte) | -| [Riot](app/riot) alpha | - | [v4.0.0-alpha](https://storybooks-riot.netlify.com/) | [![Riot](https://img.shields.io/npm/dt/@storybook/riot.svg)](app/riot) | -| [Ember](app/ember) | - | [v4.0.0-alpha](https://storybooks-ember.netlify.com/) | [![Ember](https://img.shields.io/npm/dt/@storybook/ember.svg)](app/ember) | +| Framework | Demo latest | Demo prerelease | | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [React](app/react) | [v3.4.x](https://release-3-4--storybooks-official.netlify.com), [v3.3.x](https://release-3-3--storybooks-official.netlify.com) | [v4.0.0-alpha](https://storybooks-official.netlify.com) | [![React](https://img.shields.io/npm/dt/@storybook/react.svg)](app/react) | +| [React Native](app/react-native) | - | - | [![React Native](https://img.shields.io/npm/dt/@storybook/react-native.svg)](app/react-native) | +| [Vue](app/vue) | [v3.4.x](https://release-3-4--storybooks-vue.netlify.com/), [v3.3.x](https://release-3-3--storybooks-vue.netlify.com/) | [v4.0.0-alpha](https://storybooks-vue.netlify.com/) | [![Vue](https://img.shields.io/npm/dt/@storybook/vue.svg)](app/vue) | +| [Angular](app/angular) | [v3.4.x](https://release-3-4--storybooks-angular.netlify.com/), [v3.3.x](https://release-3-3--storybooks-angular.netlify.com/) | [v4.0.0-alpha](https://storybooks-angular.netlify.com/) | [![Angular](https://img.shields.io/npm/dt/@storybook/angular.svg)](app/angular) | +| [Polymer](app/polymer) | [v3.4.x](https://release-3-4--storybooks-polymer.netlify.com/) | [v4.0.0-alpha](https://storybooks-polymer.netlify.com/) | [![Polymer](https://img.shields.io/npm/dt/@storybook/polymer.svg)](app/polymer) | +| [Mithril](app/mithril) alpha | - | [v4.0.0-alpha](https://storybooks-mithril.netlify.com/) | [![Mithril](https://img.shields.io/npm/dt/@storybook/mithril.svg)](app/mithril) | +| [Marko](app/marko) alpha | - | [v4.0.0-alpha](https://storybooks-marko.netlify.com/) | [![Marko](https://img.shields.io/npm/dt/@storybook/marko.svg)](app/marko) | +| [HTML](app/html) alpha | - | [v4.0.0-alpha](https://storybooks-html.netlify.com/) | [![HTML](https://img.shields.io/npm/dt/@storybook/html.svg)](app/html) | +| [Svelte](app/svelte) alpha | - | [v4.0.0-alpha](https://storybooks-svelte.netlify.com/) | [![Svelte](https://img.shields.io/npm/dt/@storybook/svelte.svg)](app/svelte) | +| [Riot](app/riot) alpha | - | [v4.0.0-alpha](https://storybooks-riot.netlify.com/) | [![Riot](https://img.shields.io/npm/dt/@storybook/riot.svg)](app/riot) | +| [Ember](app/ember) | - | [v4.0.0-alpha](https://storybooks-ember.netlify.com/) | [![Ember](https://img.shields.io/npm/dt/@storybook/ember.svg)](app/ember) | ### Sub Projects -- [CLI](lib/cli) - Streamlined installation for a variety of app types -- [examples](examples) - Code examples to illustrate different Storybook use cases +- [CLI](lib/cli) - Streamlined installation for a variety of app types +- [examples](examples) - Code examples to illustrate different Storybook use cases ### Addons -| Addons | | -|----|---| -| [a11y](addons/a11y/) | Test components for user accessibility in Storybook | -| [actions](addons/actions/) | Log actions as users interact with components in the Storybook UI | -| [backgrounds](addons/backgrounds/) | Let users choose backgrounds in the Storybook UI | -| [centered](addons/centered/) | Center the alignment of your components within the Storybook UI | -| [events](addons/events/) | Interactively fire events to components that respond to EventEmitter | -| [graphql](addons/graphql/) | Query a GraphQL server within Storybook stories | -| [info](addons/info/) | Annotate stories with extra component usage information | -| [jest](addons/jest/) | View the results of components' unit tests in Storybook | -| [knobs](addons/knobs/) | Interactively edit component prop data in the Storybook UI | -| [links](addons/links/) | Create links between stories | -| [notes](addons/notes/) | Annotate Storybook stories with notes | -| [options](addons/options/) | Customize the Storybook UI in code | -| [storyshots](addons/storyshots/) | Easy snapshot testing for components in Storybook | -| [storysource](addons/storysource/) | View the code of your stories within the Storybook UI | -| [viewport](addons/viewport/) | Change display sizes and layouts for responsive components using Storybook | +| Addons | | +| ---------------------------------- | -------------------------------------------------------------------------- | +| [a11y](addons/a11y/) | Test components for user accessibility in Storybook | +| [actions](addons/actions/) | Log actions as users interact with components in the Storybook UI | +| [backgrounds](addons/backgrounds/) | Let users choose backgrounds in the Storybook UI | +| [centered](addons/centered/) | Center the alignment of your components within the Storybook UI | +| [events](addons/events/) | Interactively fire events to components that respond to EventEmitter | +| [graphql](addons/graphql/) | Query a GraphQL server within Storybook stories | +| [info](addons/info/) | Annotate stories with extra component usage information | +| [jest](addons/jest/) | View the results of components' unit tests in Storybook | +| [knobs](addons/knobs/) | Interactively edit component prop data in the Storybook UI | +| [links](addons/links/) | Create links between stories | +| [notes](addons/notes/) | Annotate Storybook stories with notes | +| [options](addons/options/) | Customize the Storybook UI in code | +| [storyshots](addons/storyshots/) | Easy snapshot testing for components in Storybook | +| [storysource](addons/storysource/) | View the code of your stories within the Storybook UI | +| [viewport](addons/viewport/) | Change display sizes and layouts for responsive components using Storybook | See [Addon / Framework Support Table](ADDONS_SUPPORT.md) @@ -134,11 +134,11 @@ If you're looking for material to use in your presentation about storybook, like ## Community -- Tweeting via [@storybookjs](https://twitter.com/storybookjs) -- Blogging at [Medium](https://medium.com/storybookjs) -- Chatting on [Slack](https://now-examples-slackin-rrirkqohko.now.sh/) -- Discussions on [Discord](https://discord.gg/sMFvFsG) -- Streaming saved at [Youtube](https://www.youtube.com/channel/UCr7Quur3eIyA_oe8FNYexfg) +- Tweeting via [@storybookjs](https://twitter.com/storybookjs) +- Blogging at [Medium](https://medium.com/storybookjs) +- Chatting on [Slack](https://now-examples-slackin-rrirkqohko.now.sh/) +- Discussions on [Discord](https://discord.gg/sMFvFsG) +- Streaming saved at [Youtube](https://www.youtube.com/channel/UCr7Quur3eIyA_oe8FNYexfg) ## Contributing @@ -146,8 +146,8 @@ If you're looking for material to use in your presentation about storybook, like We welcome contributions to Storybook! -- ⇄ Pull requests and ★ Stars are always welcome. -- Read our [contributing guide](CONTRIBUTING.md) to get started. +- ⇄ Pull requests and ★ Stars are always welcome. +- Read our [contributing guide](CONTRIBUTING.md) to get started. ### Development scripts @@ -164,16 +164,16 @@ We welcome contributions to Storybook! > boolean check if code conforms to linting rules - uses remark & eslint -- `yarn lint:js` - will check js -- `yarn lint:md` - will check markdown + code samples +- `yarn lint:js` - will check js +- `yarn lint:md` - will check markdown + code samples -- `yarn lint:js --fix` - will automatically fix js +- `yarn lint:js --fix` - will automatically fix js #### `yarn test` > boolean check if unit tests all pass - uses jest -- `yarn run test --core --watch` - will run core tests in watch-mode +- `yarn run test --core --watch` - will run core tests in watch-mode ### Sponsors diff --git a/docs/src/pages/basics/quick-start-guide/index.md b/docs/src/pages/basics/quick-start-guide/index.md index 05cd654ff880..43dcd059bc89 100644 --- a/docs/src/pages/basics/quick-start-guide/index.md +++ b/docs/src/pages/basics/quick-start-guide/index.md @@ -1,42 +1,45 @@ --- -id: 'quick-start-guide' -title: 'Quick Start Guide' +id: "quick-start-guide" +title: "Quick Start Guide" --- -Storybook supports many different frontend frameworks with more coming! +Storybook supports many different frontend view layers with more coming! React, Vue, Angular, Mithril, Marko, HTML and Svelte are currently supported. Follow these steps to get started with Storybook. Get started using the automated command line tool. This command adds a set of boilerplate files for Storybook in your project: + ```sh cd my-project-directory -npm i -g @storybook/cli -getstorybook +npx -p @storybook/cli sb init ``` -The `-g` global install is used to run our cli tool in your project directory to generate templates for existing projects. To avoid the global install and setup a project manually, take a look at the [Slow Start Guide](/basics/slow-start-guide/). -To install storybook for HTML, add `--html` argument: +The tool inspects your `package.json` to determine which view layer you're using. If you want to develop HTML snippets in storybook, we can't determine that automatically. So to install storybook for HTML, add the `--html` argument: + ``` -getstorybook --html +npx -p @storybook/cli sb init --html ``` +To setup a project manually, take a look at the [Slow Start Guide](/basics/slow-start-guide/). Start Storybook with: + ```sh npm run storybook ``` Storybook should now be available in the browser with a link provided in the console. -* * * +--- To learn more about what `getstorybook` command does, have a look at the slow start guides: -* [React](/basics/guide-react/) -* [Vue](/basics/guide-vue/) -* [Angular](/basics/guide-angular/) -* [Mithril](/basics/guide-mithril/) -* [Marko](/basics/guide-marko/) -* [HTML](/basics/guide-html/) -* [Svelte](/basics/guide-svelte/) -* [Ember](/basics/guide-ember/) + +- [React](/basics/guide-react/) +- [Vue](/basics/guide-vue/) +- [Angular](/basics/guide-angular/) +- [Mithril](/basics/guide-mithril/) +- [Marko](/basics/guide-marko/) +- [HTML](/basics/guide-html/) +- [Svelte](/basics/guide-svelte/) +- [Ember](/basics/guide-ember/) A tutorial is also available at [Learn Storybook](https://www.learnstorybook.com) for a step-by-step guide (only available for React). diff --git a/lib/cli/bin/generate.js b/lib/cli/bin/generate.js index f8596afa8d9f..8830077206fd 100644 --- a/lib/cli/bin/generate.js +++ b/lib/cli/bin/generate.js @@ -2,7 +2,6 @@ import program from 'commander'; import chalk from 'chalk'; import pkg from '../package.json'; import initiate from '../lib/initiate'; -import yarnSpawnSync from '../lib/yarn_spawn_sync'; import { codeLog } from '../lib/helpers'; const logger = console; @@ -10,7 +9,7 @@ const logger = console; if (process.argv[1].includes('getstorybook')) { logger.log(chalk.yellow('WARNING: getstorybook is deprecated.')); logger.log(chalk.yellow('The official command to install Storybook from now on is:\n')); - codeLog(['storybook init']); + codeLog(['sb init']); logger.log(); initiate({}, pkg).then(() => process.exit(0)); } else { @@ -24,18 +23,6 @@ if (process.argv[1].includes('getstorybook')) { .option('-h --html', 'Add storybook for HTML') .action(options => initiate(options, pkg)); - program - .command('start') - .description('Start the local Storybook server') - .option('-N --use-npm', 'Use NPM to start the Storybook server') - .action(options => yarnSpawnSync(options, ['run', 'storybook'])); - - program - .command('build') - .description('Build the Storybook static application') - .option('-N --use-npm', 'Use NPM to build the Storybook server') - .action(options => yarnSpawnSync(options, ['build', 'storybook'])); - program.command('*', { noHelp: true }).action(cmd => { logger.error('Invalid command: %s.\nSee --help for a list of available commands.', cmd); process.exit(1); diff --git a/lib/cli/lib/initiate.js b/lib/cli/lib/initiate.js index 88047bcb69ba..a3e8e633a1de 100644 --- a/lib/cli/lib/initiate.js +++ b/lib/cli/lib/initiate.js @@ -24,7 +24,7 @@ import riotGenerator from '../generators/RIOT'; const logger = console; export default function(options, pkg) { - const welcomeMessage = 'storybook init - the simplest way to add a storybook to your project.'; + const welcomeMessage = 'sb init - the simplest way to add a storybook to your project.'; logger.log(chalk.inverse(`\n ${welcomeMessage} \n`)); const useYarn = Boolean(options.useNpm !== true) && hasYarn(); @@ -33,7 +33,7 @@ export default function(options, pkg) { useYarn, }; - const runStorybookCommand = 'storybook start'; + const runStorybookCommand = useYarn ? 'yarn storybook' : 'npm run storybook'; // Update notify code. updateNotifier({ @@ -74,7 +74,7 @@ export default function(options, pkg) { logger.log(); paddedLog('There seems to be a storybook already available in this project.'); paddedLog('Apply following command to force:\n'); - codeLog(['storybook init -f']); + codeLog(['sb init -f']); // Add a new line for the clear visibility. logger.log(); @@ -179,10 +179,10 @@ export default function(options, pkg) { default: paddedLog(`We couldn't detect your project type. (code: ${projectType})`); paddedLog( - "Please make sure you are running the `storybook init` command in your project's root directory." + "Please make sure you are running the `sb init` command in your project's root directory." ); paddedLog( - 'You can also install storybook for plain HTML snippets with `storybook init --html` or follow some of the slow start guides: https://storybook.js.org/basics/slow-start-guide/' + 'You can also install storybook for plain HTML snippets with `sb init --html` or follow some of the slow start guides: https://storybook.js.org/basics/slow-start-guide/' ); // Add a new line for the clear visibility. diff --git a/lib/cli/lib/yarn_spawn_sync.js b/lib/cli/lib/yarn_spawn_sync.js deleted file mode 100644 index 31c3ebb06a4e..000000000000 --- a/lib/cli/lib/yarn_spawn_sync.js +++ /dev/null @@ -1,7 +0,0 @@ -import { spawn as spawnSync } from 'cross-spawn'; -import hasYarn from './has_yarn'; - -export default function yarnSpawnSync(options, args) { - const pkgmgr = Boolean(options.useNpm !== true) && hasYarn() ? 'yarn' : 'npm'; - spawnSync(pkgmgr, args, { stdio: 'inherit' }); -} diff --git a/lib/cli/package.json b/lib/cli/package.json index d7fd13f901a6..6480d44856a4 100644 --- a/lib/cli/package.json +++ b/lib/cli/package.json @@ -21,8 +21,8 @@ "license": "MIT", "author": "Storybook Team", "bin": { - "getstorybook": "./bin/index.js", - "storybook": "./bin/index.js" + "sb": "./bin/index.js", + "getstorybook": "./bin/index.js" }, "scripts": { "test": "cd test && ./run_tests.sh",