bnomei / kirby3-storybook
Kirby 3 Plugin to generate Storybook stories from snippets and templates
Installs: 46
Dependents: 0
Suggesters: 0
Security: 0
Stars: 19
Watchers: 2
Forks: 1
Open Issues: 3
Type:kirby-plugin
Requires
- php: >=8.0
- getkirby/composer-installer: ^1.2
- symfony/deprecation-contracts: ^3.0.1
- symfony/finder: ^6.0
Requires (Dev)
- getkirby/cli: ^1.1.0
- getkirby/cms: ^3.9.0-rc.1
- php-coveralls/php-coveralls: ^2.4
- phpunit/phpunit: ^9.5
README
Kirby Plugin to generate Storybook stories from snippets and templates.
Install
Plugin
Using composer:
composer global require getkirby/cli composer require bnomei/kirby3-storybook --dev
You need to install the CLI with composer since this plugin depends on the CLI to be available either globally or locally.
Storybook
Please refer to the official docs on how to install Storybook if in doubt.
npm install storybook --sav-dev
TIP: I used storybook@^7.0.0-beta.12 for my tests.
npx storybook init --type vue3
TIP: I used vue3 for my tests, but you can stick to vue if you want to keep it consistent to other Kirby components.
Usage
Creating stories
The plugin can load data for your Snippet/Template files. You can use three different ways for Snippets and two for Templates. Check out the tests in this repository to see some examples.
Snippet stories
Let's assume a snippet named example.php
in either site/snippets
or registered via a plugin extension. Add any of these files into the same folder as the snippet.
example.stories.yml
containing an array with a key-value pair for each PHP variable you need.example.stories.json
containing a KQL Query you want to be extracted into the snippet.- or add the
extract(storybook($YOUR_DATA_ARRAY), EXTR_SKIP);
call to the head of your snippet.
Template stories
Let's assume a template named blog.php
in either site/templates
or registered via a plugin extension. Add any of these files into the same folder as the template.
blog.stories.yml
containing either anid
key with the id of a page to load as value or an array calledvirtual
with all data needed for aPage::factory()
call.blog.stories.json
containing a KQL Query you want to be extracted into the template.
Storybook and the plugins file watcher
You need to run two tasks. First start Storybook.
npm run storybook
TIP: Make sure you can run storybook after installation at least once without errors. Then remove the demo files or copy them to a different location in case you need them for reference (like I usually do).
In a different shell run the file watcher.
kirby storybook:watch
The file watcher provided by this plugin needs the Kirby CLI and has various options for interval, displaying errors, running only once and a file pattern match. See help for details.
Some examples:
kirby storybook:watch --help
kirby storybook:watch --errors --once
kirby storybook:watch --interval 5000
kirby storybook:watch --pattern article
kirby storybook:watch --pattern '/.*blocks\/.*/'
Generated Files
The plugin will use the file watcher to monitor your Snippet/Template files and their story config files (aka *.stories.yml|json
). If any of these files changes it will generate or overwrite the corresponding files in your Storybook stories
folder. Creating subfolders as needed to match Kirbys extension registry (like snippets/blocks
). It will NOT remove any files. There are three files created for each story.
Example.html
contains the rendered HTML and will be overwritten on changes to the source files.Example.stories.js
defines details about your story for Storybook, like title or variants. It will only be created if missing. You can edit it as you like.Example.vue
standard Vue SFC. It references to the HTML file. This file allows you to add custom js/css or when the source is finalized remove the reference, copy the HTML into the vue-file and add support for variants etc.
Adding your CSS and JS assets
You could add the reference your a single css file manually with <style src="./../../app.css"></style>
and import all your scripts to each vue SFC. But my suggested method out of 6 would be to import your assets in the ./storybook/preview.js
and/or .storybook/main.js
that storybook created. See example below:
./storybook/preview.js
+ import './../assets/css/app.css' + import "./../assets/js/alpine.min" export const parameters = { actions: { argTypesRegex: "^on[A-Z].*" }, controls: { matchers: { color: /(background|color)$/i, date: /Date$/, }, }, }
./storybook/main.js
... "docs": { "docsPage": true }, + "previewHead": (head) => (` + <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@splidejs/splide@4.1.4/dist/css/splide.min.css" /> + <script src="https://cdn.jsdelivr.net/npm/@splidejs/splide@4.1.4/dist/js/splide.min.js"></script> + ${head} + `),
Settings
Dependencies
Disclaimer
This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.
License
It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.