Extends Twig with new "stories" and "story" tags for easily writing Storybook stories using Twig templates.
GPL-2.0 License
Twig Storybook is a Composer package that enhances the Twig templating language by introducing two new Twig tags: stories
and story
. With Twig Storybook, you can easily create and manage Storybook stories directly in your Twig templates, making it a powerful tool for documenting and showcasing your frontend components.
You can install Twig Storybook via Composer:
composer require e0ipso/twig-storybook
You don't need to use this package directly, use the Storybook drupal module instead. This library is compatible with Drupal 10, and later.
After installing the package, you need to register the Twig tags in your Twig environment. Here's how you can do it:
use Twig\Environment;
use Twig\Loader\FilesystemLoader;
use E0ipso\TwigStorybook\Twig\StorybookExtension;
// Initialize the Twig environment
$loader = new FilesystemLoader('path/to/your/templates');
$twig = new Environment($loader);
// Register the Storybook extension
$twig->addExtension(new \TwigStorybook\Twig\TwigExtension());
Once the Twig Storybook extension is registered, you can start creating stories within your Twig templates. We recommend
writing the stories in a file with name <file-name>.stories.twig
.
{% stories %}
tag to define a group of stories.{% story %}
tag to define an individual story.Here's an example:
{% stories my_card with {
title: 'Components/Examples/Card',
argTypes: {
iconType: {
options: { Power: 'power', Like: 'like', External: 'external' },
control: 'radio'
}
}
} %}
{% story default with {
name: '1. Default',
args: { header: 'I am a header!', text: 'Learn more', iconType: 'power' }
} %}
{% embed '@examples/my-card' with { header } %}
{% block card_body %}
<p>I am the <em>card</em> contents.</p>
{% include '@examples/my-button' with { text, iconType } %}
{% endblock %}
{% endembed %}
{% endstory %}
{% endstories %}
This will render as:
Install Storybook as usual:
# Make use of modern versions of yarn.
yarn set version berry
# Avoid pnp.
echo 'nodeLinker: node-modules' >> .yarnrc.yml
# Install and configure stock Storybook.
yarn dlx sb init --builder webpack5 --type server
Then update .storybook/main.js
to scan for stories where your application stores them.
The Storybook application will does not understand stories in Twig format. It will fail to render them. You need to
compile them into a *.stories.json
. To do so, you can leverage the
StoryRenderer::generateStoriesJsonFile($template_path, $url)
method. Where the $template_path
is the location of the
*.stories.twig
template, and the $url
is the base URL in your application that will render the story.
Storybook will make a request to "$url . '/' . $hash"
, so make sure your application handles that route (see below).
The Drupal module implementation includes a console command to find all
*.stories.twig
and compile them into *.stories.json
.
See the implementation.
To render the Storybook stories, you can use the StoryRenderer
service. Every framework handles routes differently,
but we recommend using the story renderer inside your controller.
public function renderStoryControllerHandler(string $hash, Request $request): array {
$data = $this->storyRenderer->renderStory($hash, $request);
return new Response($data);
}
To use this service, wire the services to the container. The Twig Storybook Drupal module does it like this:
services:
logger.channel.twig_storybook:
parent: logger.channel_base
arguments: ['twig_storybook']
TwigStorybook\Service\StoryCollector: {}
TwigStorybook\Service\StoryRenderer:
arguments:
- '@TwigStorybook\Service\StoryCollector'
- '@logger.channel.twig_storybook'
- '%app.root%'
calls:
- ['setTwigEnvironment', ['@twig']]
TwigStorybook\Twig\TwigExtension:
arguments:
- '@TwigStorybook\Service\StoryCollector'
- '%app.root%'
tags:
- { name: twig.extension }
We welcome contributions from the community. If you want to contribute to Twig Storybook, please follow these guidelines:
Make sure to follow the code of conduct when interacting with this community.
Twig Storybook is open-source software licensed under the GPL-2 License.