Storybook

✨ The integration between Drupal and Storybook ✨

The Storybook Drupal module enhances the Twig templating language by introducing two new Twig tags: stories and story, so you can write Storybook stories in Twig. With this module, you can easily create and manage Storybook stories directly in your Twig templates, making it a powerful tool for documenting and showcasing your frontend templates.

📖 Read the article about the module

Watch the video tutorial

5 min 📹 The full set up on both apps, Drupal and Storybook

Watch the video tutorial

5 min 📹 Single Directory Components and Storybook.

Creating Stories

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.

• Use the {% stories %} tag to define a group of stories.
• Use the {% story %} tag to define an individual story.

Here's an example:

{# some/path/in/your/code/base/my-card.stories.twig #}
{% stories my_card with { title: 'Components/Examples/Card' } %}

  {% story default with {
    name: '1. Default',
    args: { cardHeader: 'I am a header!', buttonText: 'Learn more', buttonIconType: 'power' }
  } %}
    {# Write any Twig for the "default" story. The `args` above will be #}
    {# made available as variables for the template 👇 #}
    {% embed '../examples/my-card.html.twig' with { header: cardHeader } %}
      {% block card_body %}
        <p>I am the <em>card</em> contents.</p>
        {# You can use *any* valid Twig here, including SDCs #}
        {{ include('my-theme:my-button', { text: buttonText, iconType: buttonIconType }) }}
      {% endblock %}
    {% endembed %}
  {% endstory %}

{% endstories %}

This will render as:

Drupal setup

In development.services.yml you want to add some configuration for Twig, so you don't need to clear caches so often, and to enable development mode.

You also need to enable CORS, so the Storybook application can talk to your Drupal site. You want this CORS configuration to be in development.services.yml so it does not get changed in your production environment.

Make sure to grant permission to Render Storybook stories for anonymous users. Keep this permission disabled in production.

drush role:perm:add anonymous 'render storybook stories'

The configuration you want looks like this:

parameters:
  # ...
  # Remember to disable development mode in production!
  storybook.development: true
  cors.config:
    enabled: true
    allowedHeaders: ['*']
    allowedMethods: ['*']
    allowedOrigins: ['*']
    exposedHeaders: false
    maxAge: false
    supportsCredentials: true
services:
  # ...

Disable render cache and twig cache:

drush state:set twig_debug 1
drush state:set twig_cache_disable 1
drush state:set disable_rendered_output_cache_bins 1

Storybook setup

No necessary extra steps are required, but check out this section in the README.md for some optional improvements.

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 JSON stories where your application stores them.

Troubleshooting

If you use a self-signed certificate in your local, for instance using ddev, you will need to accept the browser exception for Storybook to work. Open the Drupal site in your browser, and accept the exception. Then Storybook should work.

Compiling Twig stories into JSON

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 run:

drush storybook:generate-all-stories

If you want to monitor story changes to compile Twig stories into JSON, execute it with watch. Like so:

watch --color drush storybook:generate-all-stories

In this case the watch command may not be installed. Use homebrew to install it.

brew install watch