ben-rogerson/craft-storybook-starter

This starter sets up everything for you to be productive in Storybook and Craft and makes it easy to produce a living styleguide for your site or app.


README

Craft CMS

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:

  1. Grab the repository:
    git clone https://github.com/ben-rogerson/craft-storybook-starter.git
  2. Copy these folders into your project:
    .storybook
    stories
    templates/components
    
  3. 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
  4. Add these script definitions into your package.json:
    "scripts": {
        "storybook": "start-storybook",
        "build-storybook": "build-storybook -c .storybook -o build"
    },
  5. Start Storybook with: npm run storybook

Working with Storybook

  1. Create a normal Twig file somewhere in your templates folder:
    Eg: /templates/components/[component].twig
  2. Add a matching story in the stories folder:
    Eg: /stories/[component].stories.js
  3. 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.

Links