A Vite plugin that handles transforming twig files into a Javascript function that can be used with Storybook.
You are working with Twig in a styleguide-driven-development process. You are writing isolated components that consist of css, twig and Javascript. You want to be able to use twig to render your components for Storybook. You want fast refresh with Vite. You want Twig embeds, includes and extends to work. You want to use Drupal specific twig features like create_attributes etc.
The Vite plugin Twig Drupal is a Vite plugin based on Twig JS for
compiling Twig-based components into a Javascript function so that they can be used as components with Storybook.
It allows you to import twig files into your story as though they are Javascript files.
- Vite plugin twig loader Doesn't handle nested includes/embeds/extends. These are a fairly crucial feature of twig when building a component library as they allow re-use and DRY principles
- Components library server Requires you to have a running Drupal site. Whilst this ensures your twig output is identical to that of Drupal (because Drupal is doing the rendering), it is a bit more involved to setup. If you're going to use single directory components or a similar Drupal module like UI patterns then this may be a better option for you.
This module is distributed via npm which is bundled with node and
should be installed as one of your project's devDependencies:
npm install --save-dev vite-plugin-twig-drupal
You then need to configure your vite.config.js.
import { defineConfig } from "vite"
import twig from 'vite-plugin-twig-drupal';
import { join } from "node:path"
export default defineConfig({
plugins: [
// Other vite plugins.
twig({
namespaces: {
components: join(__dirname, "/path/to/your/components"),
// Other namespaces as required.
},
// Optional if you are using React storybook renderer. The default is 'html' and works with storybook's html
// renderer.
// framework: 'react'
functions: {
// You can add custom functions - each is a function that is passed the active Twig instance and should call
// e.g. extendFunction to register a function
reverse: (twigInstance) => twigInstance.extendFunction("reverse", () => (text) => text.split(' ').reverse().join(' ')),
// e.g. extendFilter to register a filter
clean_unique_id: (twigInstance) => twigInstance.extendFilter("clean_unique_id", () => (text) => text.split(' ').reverse().join(' ')),
},
globalContext: {
// Global variables that should be present in all templates.
active_theme: 'my_super_theme',
is_front_page: false,
},
}),
// Other vite plugins.
],
})With this config in place you should be able to import twig files into your story files.
// stories/Button.stories.js
// Button will be a Javascript function that accepts variables for the twig template.
import Button from './button.twig';
// Import stylesheets, this could be a sass or postcss file too.
import './path/to/button.css';
// You may also have JavaScript for the component.
import './path/to/some/javascript/button.js';
export default {
title: 'Components/Button',
tags: ['autodocs'],
argTypes: {
title: {
control: { type: 'text' },
},
modifier: {
control: { type: 'select' },
options: ['primary', 'secondary', 'tertiary'],
},
},
// Just pass along the imported variable.
component: Button,
};
// Set default variables in the story.
export const Default = {
args: { title: 'Click me' },
};
export const Primary = {
args: { title: 'Click me', modifier: 'primary' },
};
// Advanced example.
export const ButtonStrip = {
name: 'Button group',
render: () => `
${Button({title: 'Button 1', modifier: 'primary'})}
${Button({title: 'Button 2', modifier: 'secondary'})}
`
}When adding framework: 'react' to vite.config.js twig files will output React JSX functions
that can be used inside a React Storybook instance.
This way Twig components can be rendered alongside React components.
However, you will need to revert to a straight TwigJS function import so you can nest Twig components
inside other Twig components. In these instances append ?twig to your component import. This will return a JavaScript function instead of a React component.
When nesting
Twig components inside React components this is not needed. Nesting React components inside Twig components
does not work currently.
import Button from './button.twig';
import OtherComponent from ../other-component.twig?twig
export default {
title: 'Components/Button',
tags: ['autodocs'],
args: {
// Render by calling the component as a function.
// You can pass any variables down as an object.
otherComponent: OtherComponent(),
},
component: Button,
};Please file an issue for bugs, missing documentation, or unexpected behavior.
Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.
For questions related to using the library, please visit a support community instead of filing an issue on GitHub.