README

Craft Storybook Starter

Storybook is an open source tool for developing UI components in isolation.
It makes building stunning UIs organized and efficient.

🎉 Storybook runs outside Craft in JavaScript and doesn't require a Craft plugin
🎉 Storybook works with the same Twig files from your project with some differences

This starter sets up everything for you to be productive in Storybook.
Use Storybook to create a living styleguide from your existing site/app.
Take advantage of the excellent Webpack dev server to create solid components with mock data.

Storybook Features

This starter has many modern features including:

👍 Hot module reloading
👍 Automatic accessibility tests
👍 Color accessibility tests
👍 Fake data generator (Faker)
👍 Sass support
👍 Device previews
👍 Extendable Webpack config
👍 Static site generator

View the Storybook demo 👉

Getting Started

Create a new project

Create a new project based on this template using degit:

npx degit ben-rogerson/craft-storybook-starter craft-storybook && cd $_ && npm install

Start Storybook with:

npm run storybook

Start Craft CMS setup:

composer install && ./craft setup

Bring into an existing project

Adding Storybook into your project is a quick process:

Grab the repository:

git clone https://github.com/ben-rogerson/craft-storybook-starter.git

Copy these folders into your project:

.storybook
stories
templates/components

Install the Storybook devDependencies:

npm i -D @babel/core @babel/preset-env @storybook/addon-a11y @storybook/addon-knobs @storybook/addon-viewport @storybook/html faker babel-loader css-loader node-sass sass-loader style-loader twig twigjs-loader babel-plugin-module-resolver webpack-cli

Add these script definitions into your package.json:

"scripts": {
    "storybook": "start-storybook",
    "build-storybook": "build-storybook -c .storybook -o build"
},

Start Storybook with: npm run storybook

Working with Storybook

Create a normal Twig file somewhere in your templates folder:
Eg: /templates/components/[component].twig
Add a matching story in the stories folder:
Eg: /stories/[component].stories.js
Start Storybook with: npm run storybook

Hosting your Storybook

Storybook builds static file previews for your components. This means you can leverage easy (and free) hosting services like Netlify.

Configure it to run npm run build-storybook and serve from the /build folder.

You could also use Github pages to host your storybook.

A heads up: Storybook Twig != Craft Twig

Storybook uses a JavaScript implementation of Twig and you may come across some of its limitations.

Any Craft or Craft Plugin functions, or Twig tags or filters will throw an error
String interpolation isn’t supported
~~Importing components within components isn't supported (perhaps fixable with Webpack adjustments)~~
Importing now works correctly

While I agree that this isn’t ideal, there is an upside to it. It forces small and basic components. You see this same technique constantly in modern JavaScript apps and it’s a good thing! It’s a technique you can also bring to many of your Craft Components. If you’re interested in the concept check out Atomic design.

If you’re bringing components into Storybook and you’re having compatibility issues you may need to break it up into a presentational and logic component. The presentational component would have the basic component html and wouldn’t contain the incompatible Twig code. This would be the component you’d display in Storybook.

ben-rogerson / craft-storybook-starter

Maintainers

Details