Storybook SDC Addon Documentation

This Storybook addon streamlines the integration of Drupal Single Directory Components(SDC) defined in YAML files (specifically *.component.yml) as stories.

Overview:

This Storybook addon streamlines the integration of Drupal Single Directory Components (SDC) into Storybook. It leverages YAML configurations and Twig templates to dynamically load components and generate stories with minimal configuration.

Why Choose SDC Storybook Over Alternatives?

While solutions like SDC Styleguide and Drupal Storybook offer useful tools, using SDC with Storybook addon has clear advantages. Here’s why:

1. Component Independence and Modularity

• Following the BEM (Block Element Modifier) methodology, a component should work independently across environments.
• The functionality of your component must not depend on the Drupal version, or the active Drupal theme — it should be portable to any system.

2. No Complex Drupal Setup Required

• You don't need to install and configure Drupal with extra dependencies just to develop or test components.
• Frontend development becomes faster by working in Storybook, without the need to run heavy Drupal environments locally.

3. Simplifies DevOps and CI/CD Pipelines

• Since components are isolated, testing and deployments are simplified.
• You can avoid Drupal-specific configuration in CI pipelines, leading to more efficient and maintainable workflows.

4. Scalability and Flexibility with Faker.js and JSON Schema

• Storybook allows the use of tools like Faker.js to generate fake data for components. This makes it easy to test different scenarios without needing real content.
• With JSON Schema, components can be defined consistently, ensuring data integrity and clear documentation for developers.

5. Industry-Standard Tool for Frontend Development

• Storybook is a de facto standard for frontend development, making it easier for developers — even those unfamiliar with Drupal — to contribute to the project.
• JSON Schema allows developers to work on components without needing to understand Drupal’s internals, broadening participation in the project.

6. Drupal-Specific Behavior Embedded in Components

• With SDC Storybook, you can embed Drupal behaviors like Drupal.attachBehaviors() directly into the component preview. This ensures the component behaves the same way as it would on the actual site.
• Support for drupalSettings and once.js within Storybook ensures components behave identically during testing as they will on the Drupal site.

7. Twig.js vs Drupal Twig

While using Drupal to render components offers tighter integration, there are strong reasons to continue using Twig.js in many scenarios:

• Many Components Don’t Need Full Drupal Logic. Basic components (buttons, cards, lists) rely on simple HTML and CSS, not on complex template logic. For such components, Twig.js provides sufficient rendering without the need for full Drupal preprocessing.
• Twig.js Works Well for Frontend-Focused Use Cases.
• Styling and Behavior Mismatches Can Be Managed Separately in Drupal implelentation phase.

The addon includes:

• A Vite plugin to load YAML-based SDC configurations.
• Dynamic path resolution based on namespaces for component discovery.
• A story generator to create component stories from YAML files.
• Support for JSON schema-based props and Drupal behaviors.

This addon uses:

• https://github.com/larowlan/vite-plugin-twig-drupal for loads Twig with Drupal functions.
• https://github.com/json-schema-faker/json-schema-faker for generation missed props and slots.

Installation:

In @storybook/html-vite: https://storybook.js.org/docs/builders/vite

npm i storybook-addon-sdc

Configuration:

.storybook/main.js

const config = {
  stories: ["../components/**/*.component.yml"], // Your components directory.
  addons: [
    {
      name: "storybook-addon-sdc",
      options: {
        sdcStorybookOptions: {
          namespace: "umami", // Your namespace.
        },
        vitePluginTwigDrupalOptions: {}, // vite-plugin-twig-drupal options.
        jsonSchemaFakerOptions: {}, // json-schema-faker options
      }
    },
    "@storybook/addon-essentials", // Other addons.
  ],
  framework: {
    name: "@storybook/html-vite",
    options: {},
  },
};
export default config;

Default values

json-schema-faker not always generate good data. For optimal results, use default or examples for SDC schema:

props:
  type: object
  properties:
    html_tag:
      type: string
      enum:
        - article
        - div
      default: article
slots:
  content:
    title: Content
    examples:
      - Hello! I'm card content

• https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/annotated-example-componentyml
• https://json-schema.org/understanding-json-schema/reference/annotations

Experimental stories:

By default addon generates only Basic story for every component.

To create new stories you may use thirdPartySettings in SDC yaml:

$schema: https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/schemas/v1/metadata.schema.json

name: Card
status: experimental
props:
  type: object
  properties:
    html_tag:
      type: string
      title: HTML tag for wrapper
      enum:
        - article
        - div
      default: article

slots:
  content:
    title: Content
    required: true
    description: The card content.
    examples:
      - Hello! I'm card content

thirdPartySettings:
  sdcStorybook:
    stories:
      preview:
        title: Preview
        props:
          html_tag: "div"
        slots:
          content:
            - type: component
              component: "umami:title"
              props:
                label: test
            - type: component
              component: "umami:read-more"
              slots:
                text: test
      preview2:
        title: Preview2
        props:
          html_tag: "div"
        slots:
          content:
            - type: component
              component: "umami:title"
              props:
                label: test2

Or you can import yaml in regular storybook *.stories.js

Why stories experimental?

The community will have to decide what format the YAML stories should be.

Known issues:

• UI Patterns stories format not yet supported.
• Same problem will be with $ref: json-schema-definitions:// for SDC from Experience Builder.
• Plugin uses Experimental indexers