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.
Installs: 17
Dependents: 0
Suggesters: 0
Security: 0
Stars: 54
Watchers: 5
Forks: 93
Language:HTML
Type:project
Requires
- craftcms/cms: ^3.0.0
- vlucas/phpdotenv: ^2.4.0
- dev-master
- v1.1.1
- v1.1.0
- 1.0.43.2
- 1.0.43.1
- 1.0.43
- 1.0.42.15
- 1.0.42.1
- 1.0.42
- 1.0.41
- 1.0.40
- 1.0.39
- 1.0.38
- 1.0.37
- 1.0.36
- 1.0.35
- 1.0.34
- 1.0.33
- 1.0.32
- 1.0.31
- 1.0.30
- 1.0.29
- 1.0.28
- 1.0.27
- 1.0.26.1
- 1.0.26
- 1.0.25.1
- 1.0.25
- 1.0.24
- 1.0.23
- 1.0.22
- 1.0.21
- 1.0.20
- 1.0.19.1
- 1.0.19
- 1.0.18.1
- 1.0.18
- 1.0.17.2
- 1.0.17.1
- 1.0.17
- 1.0.16
- 1.0.15
- 1.0.14
- 1.0.13
- 1.0.12
- 1.0.11
- 1.0.10
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- dev-dependabot/npm_and_yarn/tar-6.1.3
- dev-dependabot/npm_and_yarn/postcss-7.0.36
- dev-dependabot/npm_and_yarn/locutus-2.0.15
- dev-dependabot/npm_and_yarn/hosted-git-info-2.8.9
- dev-dependabot/npm_and_yarn/ssri-6.0.2
This package is auto-updated.
Last update: 2025-03-01 00:26:48 UTC
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
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.