storybook-addon-twig

Twig source and code highlighting for Storybook.

storybook-addon-twig registers Twig syntax with Storybook's native Docs code blocks and adds a Twig panel for story-level source.

Install

bun add -d storybook-addon-twig

[!NOTE] This package is designed for Storybook 10.

Register the addon:

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  addons: [
    {
      name: 'storybook-addon-twig',
      options: {
        copy: true,
        docsCodeBlocks: true,
        showLineNumbers: true,
      },
    },
  ],
};

export default config;

Add source to a story:

export const Default = {
  parameters: {
    twig: {
      fileName: 'button.html.twig',
      source: "{% include 'button.html.twig' with { label: 'Save' } %}",
    },
  },
};

[!TIP] source is displayed exactly as provided. Pass formatted Twig when you want the panel and Docs output to preserve project formatting.

Options

Option	Default	Purpose
docsCodeBlocks	true	Register Twig syntax for Storybook Docs and MDX code blocks
panel	true	Register the dedicated Twig addon panel
copy	true	Show the Copy action in the Twig panel toolbar
showLineNumbers	true	Show line numbers in the Twig panel
wrapLines	true	Wrap long lines in the Twig panel

The addon uses Storybook's native Docs code blocks for Twig highlighting. The optional manager panel renders story-level Twig source in the addon panel.

Behavior Notes

• The Twig addon panel and Docs code blocks are independent. You can disable the panel with panel: false and keep docs highlighting with docsCodeBlocks: true.
• Storybook's Source block inside Canvas is rendered in dark mode by Storybook itself. This addon does not force a dark theme.
• The sync icon in the panel toolbar triggers a Storybook FORCE_RE_RENDER refresh for the current story.

Migration Notes

• patchDocsCodeBlocks is removed. Use docsCodeBlocks.
• theme is not part of this addon's API.

Troubleshooting

If Storybook fails after upgrading this addon, clear optimize-deps/cache artifacts and restart:

rm -rf node_modules/.cache/storybook node_modules/.vite

Development

This repo is Bun-first:

bun install
bun run build
bun run check:package
bun run coverage
bun run lint
bun run format:check
cd sandbox && bun run build-storybook
bun run storybook

The sandbox Storybook lives in sandbox/ and resolves the parent addon package directly from its Storybook config.

Documentation

Topic	Page
Configuration	docs/configuration.md
Architecture	docs/architecture.md
Sandbox	docs/sandbox.md
Testing	docs/testing.md
Release process	docs/release.md
Contributing	CONTRIBUTING.md

License

MIT