Awesome
Storybook Boilerplate
<img src="doc/logos/Storybook.png" alt="Storybook" title="Storybook" height="60"> <img src="doc/logos/NodeJS.png" alt="NodeJS" title="NodeJS" height="60"> <img src="doc/logos/webpack.png" alt="Webpack" title="Webpack" height="60"> <img src="doc/logos/react.png" alt="React" title="React" height="60"> <img src="doc/logos/eslint.png" alt="ESLint" title="ESLint" height="60"> <img src="doc/logos/Jest.png" alt="Jest" title="Snapshot Testing" height="60"> <img src="doc/logos/mocha.png" alt="Mocha" title="MochaJS" height="60"> <img src="doc/logos/chai.png" alt="Chai" title="ChaiJS" height="60"> <img src="doc/logos/Material-UI.png" alt="Material-UI" title="Material-UI" height="60">
At the heart of this project the desire to collect the best practices of application development via React-Storybook environment. This project is transparent and friendly for developers. You do not need to eject anything. Therefore you can easily add your own configuration and extend it using any packages.
It contains the fully-charged setup of the Storybook with pre-installed plugins, configuration, quick examples, and tips. Inspired by Create React App and React CDK.
--
Features
We mark with <img src="doc/msm.png" alt="Milestone" width="22"> icon features that not implemented yet. See our further plans in the roadmap section.
-
React Storybook Addons:
🔋 React Storybook Info Addon - show additional <b>information</b> for your stories
🔋 Storybook Addon Notes - allows you to write <b>notes</b> for your stories
🔋 Storybook Addon Actions (included by default) - the <b>Action Logger</b> addon can be used to display data received by event handlers
🔋 Storybook Addon Knobs - allows you to <b>edit</b> React props dynamically
🔋 Storybook Addon Material-UI - provides live <b>theme</b> creating environment to React Storybook
-
Testing:
<img src="doc/msm.png" alt="Milestone" width="22"> StoryShots - provides Snapshot Testing for React Storybook
-
React ecosystem:
🔋 Material-UI - via Storybook Addon Material-UI
🔋 React Theme Provider
-
Workflow (via NPM scripts command):
🔋 Support for Linux, macOS, and Windows
<img src="doc/msm.png" alt="Milestone" width="22"> Build your App with Webpack and Babel
🔋 Publish transpiled code into NPM
🔋 Run tests
🔋 ESLint with the Airbnb style guide
🔋 Deploy your storybook to GitHub Pages
--
Roadmap
<img src="doc/msm.png" alt="Milestone" width="22"> Add support for Storybook 3 features
<img src="doc/msm.png" alt="Milestone" width="22"> Add Styled Components support
<img src="doc/msm.png" alt="Milestone" width="22"> Deploy your App to GitHub Pages
<img src="doc/msm.png" alt="Milestone" width="22"> storybook-addon-comments - allows you to add comments for your stories
<img src="doc/msm.png" alt="Milestone" width="22"> storybook-addon-options - set configure the Storybook UI
<img src="doc/msm.png" alt="Milestone" width="22"> Short tutorial for using this tools
<img src="doc/msm.png" alt="Milestone" width="22"> Suggest your feature which you'd like to see here!
--
Quick start
Install the project
tip: you can skip this step if you only want to look at this project. Just open live demo page and continue from here
git clone https://github.com/sm-react/storybook-boilerplate.git
cd storybook-boilerplate
npm i
npm start
Open http://localhost:9001/ in your browser.
You will see the demo page provided by React Storybook.
Press Ctrl-Shft-F
to exit from Full screen
mode.
Two panel will appear. You will see the list of stories
at the left panel and the bottom panel for working with themes.
Let's select another theme for this page. Do it via drop-down list at the bottom panel. Out of the box there are three themes: 'Light', 'Dark' and 'Gray'. Check out them.
<img src="doc/left-pane.png" align="left" width="180" title="Left Storybook panel"/>
Note the text field with the full theme data. You can change any property and instantly see how the result will affect the appearance of the page. But the best way to edit theme is to use Theme Editor
.
Click to Show Theme Editor
. It'll open a panel with a list of all theme props at the right. Click to any colored box in this list to open the color picker tool, for example on textColor
. Now you can move your mouse over the color swatches and see how the color of text is changing.
When you feel enough to edit your theme, you can save it for future use. Press <img src="doc/save-btn.png" width="20"/> to create a JSON file with your theme. Put it to src/themes/
folder in your project to include it to your theme list automatically. Note: you don't need to restart your app after adding a new theme-file to this folder, just refresh your browser. Roadmap: we are working to eliminate even this need to refresh the page after adding a file.
<img src="doc/bottom-pane.png" align="right" width="500" title="Bottom theming panel"/>
Okay, now let's look at the panel on the left. In fact, our application consists of two components: src/Header.jsx
and src/Intro.jsx
. Selecting the appropriate items in the left-side list you switch to an isolated view of the component. It's how React Storybook
works - allows you 'step-by-step' to create and works with React components. You can improve the quality of development by applying different addons to Storybook. Most of them is already pre-installed in this project. You will find excellent documentation and examples on the React Storybook website.
Scripts
All scripts are avalible via npm run <script_name>
. Mostly executable scripts are located in the '.scripts' folder of your project. In oder to keep it "transparent and friendly" we display a full CLI command which will be executed.
You can list all scripts by npm run
This project uses ESLint with the Airbnb style guide. It has some minor overrides as well. I'll find all ESLint settings in .eslintrc
file located in the root of your project.
<img src="doc/npm-lint.png" align="right" class="logo" width="486" title="linting"/>
This linting scripts will check your code in *.js
and *.jsx
files within the src
folder.
If your IDE supports the linting settings from .eslintrc
you'll be able to see same issues bouth from IDE and CLI.
Note: Some files in src
use the comments to suppress linting errors. It's up to you to continue using them or remove and change code style appropriately.
--
<details> <summary> <b>Publish to NPM</b> <br> `npm publish` - publish your code to NPM<br> </summary>The publish script first transpille your code to ES5 and put it to dist
folder, which is cleared before each transpillation.
<img src="doc/npm-publish.png" align="right" class="logo" width="560" title="publish to NPM"/>
This project uses Babel for transpilling your code with following presets:
be careful with stage-0 features because they are far from the final stage!
It's setted up to transpille all *.js
and *.jsx
files in your src
folder, exept test
and stories
folders and *.story.jsx
files.
You'll find your transpillation settings in the .babelrc
file located in the root of your project.
In some cases you need only transpille your code, not publish. So use npm run prepublish
and get you ES5 code in the dist
folder.
Transplling your code to ES5 helps to use it in any other projects without warring about babel settings of these projects.
Note: you need to set at least your own name and version in package.json
before publishing. You might want to set other fields as well.
--
<details> <summary> <b>Deploy Storybook</b> <br> `npm run deploy` - deploys your storybook to Github Pages<br> </summary>Now it supports only Github Pages.
<img src="doc/npm-deploy.png" align="right" class="logo" width="646" title="deploy to Github"/>
This script uses your git
remote origin
url to get your repo. You can check it out by git remote get-url origin
.
Note if you get this project by git clone
command, you need to remove current git settings and add your own repo. If you've already created your Github repo you could setup git this way:
rm -rf .git
git init
git remote add origin https://github.com/UserName/RepoName.git
You'll find your repo's adress pressing Clone or download
button at your github repo page.
--
<details> <summary> <b>Test</b> <br> `npm run testonly` - runs mocha tests<br> `npm run test-watch` - runs tests continuously<br> </summary>It will find tests
folder within src
and run them once.
<img src="doc/npm-testonly.png" align="right" class="logo" width="613" title="run tests"/>
Note: we have a svg
file imported in <Header />
component. This script is setted up to ignore images with such extensions.
npm run test-watch
- starts to monitor changes in your js
, jsx
and json
files
--
<details> <summary> <b>Info</b> <br> `npm run status` - displays summary information about NPM package, linting errors and mocha tests </summary><img src="doc/npm-status.png" align="right" class="logo" width="764" title="run status"/>
</details>Contribute
We'll appreciate any help, ideas, issues and feedback!