README

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.

Installation
Usage
Contributing
License

Installation

You can install Twig Storybook via Composer:

composer require e0ipso/twig-storybook

Usage

With Drupal

You don't need to use this package directly, use the Storybook drupal module instead.

Adding Twig Tags

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());

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:

{% 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:

Storybook setup

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.

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 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.

Rendering Stories

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 }

Contributing

We welcome contributions from the community. If you want to contribute to Twig Storybook, please follow these guidelines:

Fork the repository.
Create a new branch for your feature or bug fix.
Make your changes and ensure all tests pass.
Submit a pull request with a clear description of your changes.

Make sure to follow the code of conduct when interacting with this community.

License

Twig Storybook is open-source software licensed under the GPL-2 License.

e0ipso / twig-storybook

Maintainers

Details