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.

Links

Twig 'include' in variable throws "Unable to find template file"

Unable to find template file

I came across this error while experimenting with your awesome craft/storybook setup. I already found a workaround: I use Twig macro.

Craft uses /templates as base dir for twig-template-files so I use . as base path for my twig-files in /templates/**/*.twig. But I guess webpack does not think like that so we got a problem here...

If you have any further questions, just comment below, thanks in advance!

After git clone I added the following files:

stories/a.stories.js
stories/b.stories.js
templates/components/a.twig
templates/components/b.twig

Works with Storybook but not with Craft

stories/a.stories.js

// Import: Twig
import component from 'components/a.twig';

// Component name
export default { title: 'Test/A' };

export const Simple = () => {
  return component();
};

stories/b.stories.js

// Import: Twig
import component from 'components/b.twig';

// Component name
export default { title: 'Test/B' };

export const Simple = () => {
  return component();
};

templates/components/a.twig

A

{% set content %}
{% include "templates/components/b.twig" %}
{% endset %}

{{ content }}

templates/components/b.twig

Output in Storybook:

A B

Works with Craft but not with Storybook

templates/components/a.twig

A

{% set content %}
{% include "./b.twig" %}
{% endset %}

{{ content }}

Output in Storybook:

Unable to find template file ./b.twig

Workaround with macro

templates/components/a.twig

A

{% import "./b.twig" as b %}

{% set content %}
{{ b.render() }}
{% endset %}

{{ content }}

templates/components/b.twig

{% macro render() %}
  B
{% endmacro %}

Output in Storybook:

A B

ben-rogerson / craft-storybook-starter Goto Github PK