diff --git a/README.md b/README.md index dcef6305b33..fcec2aeb95b 100644 --- a/README.md +++ b/README.md @@ -1,143 +1,33 @@ -# React Storybook [![Build Status](https://travis-ci.org/kadirahq/react-storybook.svg?branch=master)](https://travis-ci.org/kadirahq/react-storybook) [![npm version](https://badge.fury.io/js/%40kadira%2Fstorybook.svg)](https://badge.fury.io/js/%40kadira%2Fstorybook) +# React Storybook [![Build Status](https://travis-ci.org/kadirahq/react-storybook.svg?branch=master)](https://travis-ci.org/kadirahq/react-storybook) [![npm version](https://badge.fury.io/js/%40kadira%2Fstorybook.svg)](https://badge.fury.io/js/%40kadira%2Fstorybook) [![Storybook Slack](https://storybooks-slackin.herokuapp.com/badge.svg)](https://storybooks-slackin.herokuapp.com/) -Now you can develop and design React UI components without running your app. +React Storybook is a UI development environment for your React components. With it, you can visualize different states of your UI components and develop them interactively. -![React Storybook Screenshot](docs/react_storybook_screenshot.png) +![React Storybook Screenshot](docs/demo.gif) -You just load your UI components into the React Storybook and start developing them. - -This functionality allows you to develop UI components rapidly without worrying about the app. It will improve your team’s collaboration and feedback loop. - -> Have a look at this article on [Introducing React Storybook](https://medium.com/@arunoda/ec27f28de1e2). - -## Features - -* Isolated environment for your components (with the use of various iframe tactics). -* Hot module reloading (even for functional stateless components). -* Works with any app (whether it's Redux, Relay or Meteor). -* Default webpack configuration similar to [Create React App](https://github.com/facebookincubator/create-react-app). -* Support for CSS (whether it's plain old CSS, CSS modules or something fancy). -* Clean and fast user interface. -* Runs inside your project (so, it uses your app's NPM modules and babel configurations out of the box). -* Serves static files (if you host static files inside your app). -* Deploy the whole storybook as a static app. -* Extendable as necessary (support for custom webpack loaders and plugins). - -## Demo - -Let's look at what React Storybook does. First clone the following repo: - -```sh -git clone https://github.com/kadira-samples/react-storybook-demo -``` - -> It's a Redux to-do app (taken from the Redux repo). - -Then apply the following commands: - -```sh -npm install -npm run storybook -``` - -This will start your Storybook in . Open that URL in your browser. You will see the React Storybook UI: - -![React Storybook in action](docs/react_storybook_demo.gif) - -Edit some of the components in the `components` directory and see how they reflect in the Storybook UI. We define stories inside the `components/stories` directory. Have a play with that as well. +React Storybook runs outside of your app. So you can develop UI components in isolation without worrying about app specific dependencies and requirements. ## Getting Started -Now let's add support for React Storybook to your app. First of all, add the `@kadira/storybook` NPM package to your app: - -```sh -npm i --save-dev @kadira/storybook -``` - -Then, add the following NPM script into your `package.json`: - ```js -{ - ... - "scripts": { - "storybook": "start-storybook -p 9001" - } - ... -} +npm i -g getstorybook +cd my-react-app +getstorybook ``` -Now you can run `npm run storybook` and start developing components. +For more information visit: https://getstorybook.io -**Wait... we are not there yet.** +--- -### Writing Stories +React Storybook also comes with a lot of [addons](https://getstorybook.io/docs/addons/introduction) and a great API to customize as you wish. You can also build a [static version](https://getstorybook.io/docs/basics/exporting-storybook) of your storybook and deploy it anywhere you want. -Now you need to write some stories, which is how you can see your components inside the Storybook UI. +Here are some featured storybooks that you can reference to see how Storybook works: -Basically, a story is a single view of a component. It's like a test case, but you can preview it (live) from the Storybook UI. + * [React Button](http://kadira-samples.github.io/react-button) - [source](https://github.com/kadira-samples/react-button) + * [Demo of React Dates](http://airbnb.io/react-dates/) - [source](https://github.com/airbnb/react-dates) + * [Demo of React Native Web](http://necolas.github.io/react-native-web/storybook/) - [source](https://github.com/necolas/react-native-web) -You can write your stories anywhere you want. But keeping them close to your components is a pretty good idea. +## Docs -Let's write some stories: - -```js -// components/stories/button.js - -import React from 'react'; -import { storiesOf, action } from '@kadira/storybook'; - -storiesOf('Button', module) - .add('with text', () => ( - - )) - .add('with no text', () => ( - - )); -``` - -Here, we simply have two stories for the built-in `button` component. But, you can import any of your components and write stories for them instead. - -### Configurations - -Now you need to tell Storybook where it should load the stories from. For that, you need to write a simple configuration file. Add the following content to `.storybook/config.js`: - -```js -import { configure } from '@kadira/storybook'; - -function loadStories() { - require('../components/stories/button'); - // require as many stories as you need. -} - -configure(loadStories, module); -``` - -That's it. Now simply run `npm run storybook` and start developing your components. - - -> Check this app to see it in action: https://github.com/kadira-samples/react-storybook-simple-demo - -## Learn More - -There are many things you can do with React Storybook. You can explore them with the following links: - -* [Writing Stories](docs/writing_stories.md) -* [Setting up for CSS](docs/setting_up_for_css.md) -* [Configuration APIs](docs/configure_storybook.md) -* [Extensions](docs/extensions.md) -* [Power Tools](https://voice.kadira.io/power-tools-for-react-storybook-d404d7b29b82#.4yodlbqi8) -* [How Storybook Works](docs/how_storybook_works.md) -* [Known Issues](docs/known_issues.md) -* [Storybooks.io](https://storybooks.io/?utm_source=github&utm_medium=link&utm_campaign=react-storybook) - -#### New: React Storybook meets GitHub - -[![Storybooks.io - UI Code Reviewing Done Right](docs/storybooks_io_logo.png)](https://storybooks.io/?utm_source=github&utm_medium=logo&utm_campaign=react-storybook) - -## Sample Apps - -React Storybook is very powerful and you can use it with any kind of app. Here's a list of sample apps configured for React Storybook: - -* [Very simple demo](https://github.com/kadira-samples/react-storybook-simple-demo) -* [Redux to-do app](https://github.com/kadira-samples/react-storybook-demo) -* [Meteor app (Mantra)](https://github.com/mantrajs/mantra-sample-blog-app) +* [Basics](https://getstorybook.io/docs/basics/introduction) +* [Configurations](https://getstorybook.io/docs/configurations/default-config) +* [Addons](https://getstorybook.io/docs/addons/introduction) diff --git a/docs/.DS_Store b/docs/.DS_Store index 5008ddfcf53..dcc732d74d6 100644 Binary files a/docs/.DS_Store and b/docs/.DS_Store differ diff --git a/docs/configure_storybook.md b/docs/configure_storybook.md deleted file mode 100644 index f4756e8daf5..00000000000 --- a/docs/configure_storybook.md +++ /dev/null @@ -1,203 +0,0 @@ -# Configure Storybook - -You can configure React Storybook in different ways. We'll discuss them here. - -## TOC - -* [Basic Configurations](#basic-configurations) - * [Loading Modules](#loading-modules) - * [Load Common CSS Files](#load-common-css-files) - * [Configure Modules for Testing](#configure-modules-for-testing) -* [Command Line API](#command-line-api) - * [Port](#port) - * [Static Directory](#static-directory) - * [Configuration Directory](#configuration-directory) - * [Static Builder](#static-builder) -* [Custom Webpack Configurations](#custom-webpack-configurations) - * [Add Custom CSS Loaders](#add-custom-css-loaders) - * [Other Configurations](#other-configurations) - * [Full Control](#full-control) -* [Load Custom HTML Head Content](#load-custom-html-head-content) - - -## Basic Configurations - -React Storybook uses a JavaScript file located at `.storybook/config.js` as the entry point. This is the file loaded by webpack when it's initializing. You can configure a few things inside it. - -### Loading Modules - -Loading modules is the main task of this configuration file. You can do so like this: - -```js -import { configure } from '@kadira/storybook'; - -function loadStories() { - require('../components/stories/button'); - // require as many stories as you need. -} - -configure(loadStories, module); -``` - -Or, if you prefer to keep your stories close to your components, and use a convention to name them (i.e. `buttonStory.js`), you can require them like this: - -```js -import { configure } from '@kadira/storybook'; - -const req = require.context('./', true, /Story\.js$/) - -function loadStories() { - req.keys().forEach(req) -} - -configure(loadStories, module); -``` - -### Load Common CSS Files - -Sometimes your app has some common CSS files, so this is the best place to load them. In our [Redux to-do example](https://github.com/kadira-samples/react-storybook-demo), we load todomvc CSS like this: - -```js -import { configure } from '@kadira/storybook'; -import 'todomvc-app-css/index.css' - -function loadStories() { - ... -} - -configure(loadStories, module); -``` - -### Configure Modules for Testing - -React Storybook is not your app. So, sometimes you won’t be able to use some of the APIs and functionalities inside it. So, you need to turn them off or do something else. - -Let's have a look at an example. - -In some of our apps we use [`react-komposer`](https://github.com/kadirahq/react-komposer) (especially in Mantra apps). So, if you use any container created by `react-komposer`, it usually throws an error since React Storybook does not initialize them properly. - -In such a scenario, you can disable `react-komposer` like this: - -```js -import { configure } from '@kadira/storybook'; -import { disable } from 'react-komposer'; - -disable(); - -function loadStories() { - ... -} - -configure(loadStories, module); -``` - -## Command Line API - -React Storybook comes with a command line API, which you usually use inside a NPM script. Here's the options it has: - -### Port - -You must set a port on which React Storybook starts its web server. Here's how to specify it: - -```sh -start-storybook -p 6977 -``` - -### Static Directory - -Sometimes, you ship your static files directly inside your project. In Meteor apps, this is done with the `public` directory in the app root. So, you can ask React Storybook to serve those static files. - -Here's how to tell React Storybook to use that directory to load static files: - -```sh -start-storybook -p 6977 -s ./public -``` - -> You can also specify multiple static directories like this: -> ```sh -> start-storybook -p 6977 -s ./public -> ``` - -### Configuration Directory - -React Storybook uses `.storybook` directory as a default location for its [basic](#basic-configurations) and [custom webpack](#custom-webpack-configurations) configuration. - -Here's how to tell React Storybook to use a custom directory to load your configuration files: - -```sh -start-storybook -p 6977 -s ./public -c ./storybook-config -``` - -### Static Builder - -With Static Builder, you could convert your whole Storybook into a static site. Then, you can deploy that into any static site hosting service including "GitHub Pages". - -Add following script as an NPM script: - -```sh -build-storybook -o storybook-build-dir -``` - -Then it'll build and save a set of static files into the `storybook-build-dir` directory. You can access them by running a following python static server: - -```python -python -m SimpleHTTPServer -``` - -For more information, run `build-storybook -h`. - -## Custom Webpack Configurations - -React Storybook is built on top of Webpack. If you need, you can customize the Webpack configurations used by React Storybook. - -To do so, you need to create a file at `.storybook/webpack.config.js` and export a module like this: - -```js -const path = require('path'); - -module.exports = { - plugins: [ - // your custom plugins - ], - module: { - loaders: [ - { - test: /\.css?$/, - loaders: [ 'style', 'raw' ], - include: path.resolve(__dirname, '../') - } - ] - } -} -``` - -### Add Custom CSS Loaders - -You can use this custom Webpack configurations to add css loaders. We've a [separate guide](/docs/setting_up_for_css.md) for that. - -### Other Configurations - -We allow you to use almost all [Webpack configurations](https://webpack.github.io/docs/configuration.html). So, you can customize as you wish. - -### Full Control - -For very custom configuration needs, or if you'd like to take full control over the webpack config, [see this guide](/docs/webpack_full_control_mode.md). - -## Custom Babel Config - -Storybook will first search for a `.babelrc` inside the storybook config directory, and then at your project's root. If it doesn't find either of these files, it will use its default configuration instead. - -## Load Custom HTML Head Content - -Sometimes, we need to load custom DOM nodes inside the HTML `` tag. For an example, this is how we can load TypeKit fonts with React Storybook. - -First create a file called `head.html` inside the storybook config directory. Then add following content: - -```js - - -``` - -Then run the `npm run storybook` command again. That's it. - -> Likewise, you can add anything into the HTML head. diff --git a/docs/demo.gif b/docs/demo.gif new file mode 100644 index 00000000000..c8366f8534a Binary files /dev/null and b/docs/demo.gif differ diff --git a/docs/extensions.md b/docs/extensions.md deleted file mode 100644 index b7946f40ad6..00000000000 --- a/docs/extensions.md +++ /dev/null @@ -1,100 +0,0 @@ -# React Storybook Extensions - -React Storybook comes with an extensions API to customize the storybook experience. Let's have a look at them. - -## TOC - -* [API](#api) - * [Decorators](#decorators) - * [Addons](#addons) -* [Available Extensions](#available-extensions) - -## API - -### Decorators - -A decorator is a way to wrap an story with a common set of component(s). Let's say you want to center all your stories. Then this is how we can do it with a decorator: - -```js -import React from 'react'; -import { storiesOf } from '@kadira/storybook'; -import MyComponent from '../my_component'; - -storiesOf('MyComponent', module) - .addDecorator((story) => ( -
- {story()} -
- )) - .add('without props', () => ()) - .add('with some props', () => ()); -``` - -Here we only add the decorator for the current set of stories for a given story kind. - -But, you can add a decorator **globally** and it'll be applied to all the stories you create. This is how to add a decorator like that. - -```js -import { configure, addDecorator } from '@kadira/storybook'; - -addDecorator((story) => ( -
- {story()} -
-)); - -configure(function () { - ... -}, module); -``` - -### Addons - -With an addon, you can introduce new methods to the story creation API. For an example, you can achieve the above centered component functionality with an addon like this: - -```js -import React from 'react'; -import { storiesOf } from '@kadira/storybook'; -import MyComponent from '../my_component'; - -storiesOf('MyComponent', module) - .addWithCentered('without props', () => ()) - .addWithCentered('with some props', () => ()); -``` -Here we are using a new API called `addWithCentered`. That's introduce by an addon. - -This is how we set that addon. - -```js -import { configure, setAddon } from '@kadira/storybook'; - -setAddon({ - addWithCentered(storyName, storyFn) { - // You can access the .add and other API added by addons in here. - this.add(storyName, (context) => ( -
- {storyFn(context)} -
- )); - } -}); - -configure(function () { - ... -}, module); -``` - -## Available Extensions - -Rather than creating extensions yourself, you can use extensions available below: - -* [Centered Decorator](https://github.com/kadirahq/react-storybook-decorator-centered) -* [Info addon for displaying propTypes, source and more info](https://github.com/kadirahq/react-storybook-addon-info) -* [Create Groups of stories, display all of them together](https://github.com/jurgob/react-storybook-addon-add-stories-group) -* [Display internationalized components in different locales](https://github.com/Tarabyte/react-storybook-addon-intl) -* [Handling stubbed relay data](https://github.com/orta/react-storybooks-relay-container) -* [Write tests directly inside stories](https://github.com/mthuret/storybook-addon-specifications) -* [Preview your components on different background colors](https://github.com/jakelazaroff/react-storybook-decorator-background) - -> Feel free to include your extension to the above list and share it with other.
-> Just make it available on NPM (and GitHub) and send a PR to this page. diff --git a/docs/how_storybook_works.md b/docs/how_storybook_works.md deleted file mode 100644 index 80cd7e50f7f..00000000000 --- a/docs/how_storybook_works.md +++ /dev/null @@ -1,56 +0,0 @@ -# How Storybook Works - -In this guide, we'll discuss how Storybook works internally. This document is useful if you are looking to add more features to storybook or trying to hack it. If you just looking to use Storybook, you don't need to familiar with this document. - -## TOC - -* [Major Components](#major-components) -* [Development Setup](#development-setup) - -## Major Components - -Storybook mainly comes with few different components. Here are they: - -1. Storybook Manager UI - That's the UI of the storybook where you interact with. -2. Storybook Preview - This is the iframe your components are rendered. -3. Webpack Dev Server - Storybook runs a Webpack Dev Server with [HMR](https://github.com/webpack/docs/wiki/hot-module-replacement-with-webpack) support. (usually, you invoke this with `npm run storybook`.) -4. Static Builder - Build the storybook into a set of static files. (usually, you invoke this with `npm run build-storybook`.) - -Let's have a look at each of these component with more information. - -### 1. Storybook Manager UI - -This is the core UI of the storybook. Visit [storybook UI](https://github.com/kadirahq/storybook-ui) repo to add UI related changes. - -### 2. Storybook Preview - -This is the place we render components related to stories. This has a live connection to the Webpack dev server and it support [HMR](https://github.com/webpack/docs/wiki/hot-module-replacement-with-webpack). This usually renders as an iframe inside the Manager UI. - -Once loaded, preview sends information like available stories, actions to the parent frame(Manager UI) via some iframe hacks. (using [page-bus](https://www.npmjs.com/package/page-bus) module). - -It also receives instructions from the parent window(Manager UI) to do certain tasks like switching stories. - -Source code for Storybook preview is located at `src/client/preview`. - -### 3. Webpack Dev Server - -This is script initialize the Webpack dev server. It loads both the Manager UI and the Storybook preview and starts a HTTP server in a given port. - -Source code for Webpack Dev Server is located at: `src/index.js`. - -### 4. Static Builder - -This is the static builder which creates a set of files which contains your Storybook. Then you can deploy this into GitHub pages or another static files hosting server (or service). -code - -## Development Setup - -When you are developing the Storybook follow these steps. - -* Run the development watcher with `npm run dev` inside the local repo. -* Link the local repo with `npm link` -* Then pick a [sample app](https://github.com/kadira-samples/react-storybook-demo) and link storybook into that with `npm link @kadira/storybook`. -* Then run the storybook with `npm run storybook`. -* Now change code as necessary and see changes. -* To reflect changes in the Manager UI, you need to reload the Storybook browser window. -* To reflect any changes done in the server code, you need to re-run the storybook command. (`npm run storybook`) diff --git a/docs/known_issues.md b/docs/known_issues.md deleted file mode 100644 index 3aba919d10e..00000000000 --- a/docs/known_issues.md +++ /dev/null @@ -1,26 +0,0 @@ -# Known Issues - -## NPM 404 Error - -This package is published as a NPM [scoped package](https://docs.npmjs.com/misc/scope). So, if you get a 404 error while doing `npm install`, that seems like you are using a different NPM registry (or a NPM proxy). - -**Try to use the default registry.** - -See more: https://github.com/kadirahq/react-storybook/issues/15 - -## Potential issues with NPM 2 - -If you are using NPM 2, you may got some weird [issues](https://github.com/kadirahq/react-storybook/issues/65). Try to use NPM 3. Here's how to do it: - -``` -npm i -g npm@3.8.5 -rm -rf node_modules -npm i -``` - -## Issues with Babel 5 - -If you are using Babel 5 inside your project, you will get some errors on parsing modules. -Try to [migrate your project](https://babeljs.io/blog/2015/10/31/setting-up-babel-6) to Babel 6. - -See more: https://github.com/kadirahq/react-storybook/issues/16 diff --git a/docs/logo.png b/docs/logo.png deleted file mode 100644 index a8a5e845cb8..00000000000 Binary files a/docs/logo.png and /dev/null differ diff --git a/docs/react_storybook_demo.gif b/docs/react_storybook_demo.gif deleted file mode 100644 index 2182e924253..00000000000 Binary files a/docs/react_storybook_demo.gif and /dev/null differ diff --git a/docs/setting_up_for_css.md b/docs/setting_up_for_css.md deleted file mode 100644 index 4a2e9ed881b..00000000000 --- a/docs/setting_up_for_css.md +++ /dev/null @@ -1,126 +0,0 @@ -# Setting Up for CSS - -CSS is a dark area of React. There are tons of ways to write CSS with React. - -> Arunoda wrote an [article](https://voice.kadira.io/state-of-react-and-css-501d179443d3) about that recently as well. Have a [look at it](https://voice.kadira.io/state-of-react-and-css-501d179443d3). - -By default we have a postcss based CSS loading system which is very similar to how [create-react-app](https://github.com/facebookincubator/create-react-app) handles CSS. However you can customize the CSS setup as you wish. - -## TOC - -* [CSS in JavaScript](#css-in-javascript) -* [CSS Webpack Loaders](#css-webpack-loaders) -* [CSS with Meteor](#css-with-meteor) - -## CSS in JavaScript - -By default, React Storybook doesn't come with any CSS setup. That's because there is no single default option everyone uses. But, if you write CSS using JavaScript, you can use Storybook without any configuration. - -This is also true if you use a UI framework like [Material UI](https://github.com/callemall/material-ui). - -## CSS Webpack Loaders - -Usually, we use CSS with the help of Webpack and we use CSS loaders inside our app. You can ask React Storybook to use the same loaders. It's pretty simple. - -Let's say you are using the style loader inside your app. Then, your Webpack config would usually look like this: - -```js -var path = require('path') -var webpack = require('webpack') - -module.exports = { - - ... - - module: { - loaders: [ - { - test: /\.js$/, - loaders: [ 'babel' ], - exclude: /node_modules/, - include: __dirname - }, - { - test: /\.css?$/, - loaders: [ 'style', 'raw' ], - include: __dirname - } - ] - } -} -``` - -Now, let's customize React Storybook to use these CSS modules. - -> By default, React Storybook uses the babel loader for JavaScript. So, you don't need to add it. - -Create a file `.storybook/webpack.config.js` with the following content: - -```js -const path = require('path'); - -module.exports = { - module: { - loaders: [ - { - test: /\.css?$/, - loaders: [ 'style', 'raw' ], - include: path.resolve(__dirname, '../') - } - ] - } -} -``` - - -It's exactly similar to what we had before, but we have simply chosen to include the parent directory. That's because we are inside the `.storybook` directory. - -**That's it.** - -Now you can work with CSS files. Just follow these simple steps: - - -* If your app has a root CSS file(s), simply import it into `.storybook/config.js`. -* If you've imported CSS files directly into a component, you don't have to do anything. -* Just like this, you can use any CSS loader you want, whether it's CSS Modules, SCSS, Less or anything. - -> [Refer to this project for more information](https://github.com/kadira-samples/react-storybook-demo). - -## CSS with Meteor - -Meteor will automatically import any CSS files into your app. You can also use Less, SCSS or other preprocessors via build-time packages. - -React Storybook cannot import CSS automatically. But instead, you can do this: - -* You can configure React Storybook to use a CSS loader. -* Then import the main CSS file(s) into `.storybook/config.js` file. -* Then import component-specific CSS file(s) right into your story files. - -**Let's configure React Storybook to use the style loader inside a Meteor app.** - -* Make sure you've added React Storybook properly inside the app. -* Then install style loader with `npm install --save-dev style-loader raw-loader`. -* Then create a file called `.storybook/webpack.config.js` with the following content: - -```js -const path = require('path'); - -module.exports = { - module: { - loaders: [ - { - test: /\.css?$/, - loaders: [ 'style', 'raw' ], - include: path.resolve(__dirname, '../') - } - ] - } -} -``` - -> Click [here](https://github.com/mantrajs/mantra-sample-blog-app) to see a complete example. - -Refer following links to learn more about Meteor specific CSS configurations: - -* [#96](https://github.com/kadirahq/react-storybook/issues/96#issuecomment-211928389) -* [#20](https://github.com/kadirahq/react-storybook/issues/20) diff --git a/docs/webpack_full_control_mode.md b/docs/webpack_full_control_mode.md deleted file mode 100644 index aa34a0ef94f..00000000000 --- a/docs/webpack_full_control_mode.md +++ /dev/null @@ -1,42 +0,0 @@ -# Taking Full Control of the Webpack Config - -There are so many configuration options. We give a sane config by default, but sometimes you just need to take the wheel. - -> Beware: You will be in full control of the webpack config and could easily break storybook. We have the important bits listed below. - -## Full Control Mode - -You'll need to add a `webpack.config.js` file to your config folder (`.storybook/` by default. - -In the `webpack.config.js`, return a **Function** instead of an object. The function will receive our base config. You can make modifications to it or create a brand new one. The function just needs to return a valid webpack config. - -Example: - - ```js -// .storybook/webpack.config.js - -// Export a function. Accept the base config as the only param. -module.exports = (storybookBaseConfig, configType) => { - // configType has a value of 'DEVELOPMENT' or 'PRODUCTION' - // You can change the configuration based on that. - // 'PRODUCTION' is used when building the static version of storybook. - - // Make whatever fine-grained changes you need - storybookBaseConfig.module = { ... } - - // Return the altered config - return storybookBaseConfig; -}; - ``` - -Pretty straightforward :) - -## Important Parts - -The following sections of the config could break storybook if deleted: - -- `config.entry` -- `config.output` -- `config.plugins[new webpack.HotModuleReplacementPlugin()]` - -You've been warned. diff --git a/docs/writing_stories.md b/docs/writing_stories.md deleted file mode 100644 index f3e916aa170..00000000000 --- a/docs/writing_stories.md +++ /dev/null @@ -1,116 +0,0 @@ -# Writing Stories - -## TOC - -* [Basic API](#basic-api) -* [Creating Actions](#creating-actions) -* [Linking Stories](#linking-stories) -* [Use Extensions](#use-extensions) - -You need to write stories to show your components inside React Storybook. We've a set of APIs allows you to write stories and do more with them: - -## Basic API - -This is how you can create stories: - -```js -import React from 'react'; -import { storiesOf } from '@kadira/storybook'; - -storiesOf('Button', module) - .add('with a text', () => ( - - )) - .add('with no text', () => ( - - )); -``` - -When you are writing stories, you can follow these guidelines to write great stories. - -* Write UI components by passing data via props. In this way, you can isolate UI components easily. (Maybe you can follow a pattern like [Mantra](https://voice.kadira.io/sneak-peek-mantra-7161624acaa7).) -* Do not write app-specific code inside your UI components. -* Write your stories close to your UI components. A directory called `stories` inside your components directory is a good idea. -* In Meteor, you may need to use a directory name with `.stories` or create it inside the `tests` directory. Otherwise, these story files will be loaded by Meteor. -* In a single story module, create stories for a single component. -* Prefix story names with a dot (`.`). For example: - -```js -storiesOf('core.Button', module) -``` - -## Creating Actions - -Usually our components accept event handlers. Actions help us to debug those event handlers. These actions are logged in the `Action Logger` info window in React Storybook. - -This is how we can create an action: - -```js -import React from 'react'; -import { storiesOf, action } from '@kadira/storybook'; - -storiesOf('Button', module) - .add('with a text', () => ( - - )); -``` - -Here we create an action named `click the button`. It gives a function to the `onClick` prop in our button. - -Then, when you click on the button, it will log something like this into the Action Logger: - -```js -{ - "name": "click the button", - "args": [ - "[SyntheticEvent]", - ".1", - { - "isTrusted": false - } - ] -} -``` - -Here we can see the name we've mentioned when creating the action. After that, we can see the arguments passed to the `onClick` event handler. In this case, we've three arguments. `[SyntheticEvent]` is the actual event object passed by React and you can use that to get more details. - -> For simplicity, React Storybook does not show the actual object. Instead it will show `[SyntheticEvent]`. - -## Linking Stories - -Sometimes, we may need to link stories. With that, we could use Storybook as a prototype builder. (like [InVision](https://www.invisionapp.com/), [Framer.js](http://framerjs.com/)). Here's how to do that. - -Let's say, we've a Toggle button and we need to change the story as we click the button. This is how we do it: - -```js -import { linkTo } from @kadira/storybook - -storiesOf('Toggle', module) - .add('on', () => { - return - }) - .add('off', () => { - return - }); -``` - -Have a look at the `linkTo` function: - -```js -linkTo('Toggle', 'off') -``` - -With that, you can link an event prop to any story in the Storybook. - -* First parameter is the the story kind name (what you named with `storiesOf`). -* Second parameter is the story name (what you named with `.add`). - -> You can also pass a function instead for any of above parameter. That function accepts arguments emitted by the event and it should return a string. - -Have a look at [PR86](https://github.com/kadirahq/react-storybook/pull/86) for more information. - -## Use Extensions - -You can use [React Storybook Extensions](extensions.md) to group common functionalities and reduce the amount of code you need to write. You can also [re-use extensions](extensions.md#available-extensions) created by others. - -Have a look at [React Storybook Extensions](extensions.md) for more information.