{"id":13607918,"url":"https://github.com/larowlan/vite-plugin-twig-drupal","last_synced_at":"2025-04-09T10:06:56.218Z","repository":{"id":200251956,"uuid":"705405829","full_name":"larowlan/vite-plugin-twig-drupal","owner":"larowlan","description":"Provides a vite plugin for rendering Drupal flavoured twig files with Storybook","archived":false,"fork":false,"pushed_at":"2025-02-17T23:04:44.000Z","size":49,"stargazers_count":23,"open_issues_count":2,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-06T06:08:21.909Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/larowlan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-15T23:26:27.000Z","updated_at":"2025-04-02T20:45:00.000Z","dependencies_parsed_at":"2025-01-17T05:07:02.558Z","dependency_job_id":"eb81278e-4440-4853-84bc-5a28e6693a03","html_url":"https://github.com/larowlan/vite-plugin-twig-drupal","commit_stats":{"total_commits":29,"total_committers":5,"mean_commits":5.8,"dds":"0.24137931034482762","last_synced_commit":"3ce085c6cef3b4a4080e921314a2679c5fa85f5c"},"previous_names":["larowlan/vite-plugin-twig-drupal"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larowlan%2Fvite-plugin-twig-drupal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larowlan%2Fvite-plugin-twig-drupal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larowlan%2Fvite-plugin-twig-drupal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larowlan%2Fvite-plugin-twig-drupal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/larowlan","download_url":"https://codeload.github.com/larowlan/vite-plugin-twig-drupal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018060,"owners_count":21034048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T19:01:22.764Z","updated_at":"2025-04-09T10:06:56.180Z","avatar_url":"https://github.com/larowlan.png","language":"JavaScript","funding_links":[],"categories":["Integrations with Backends"],"sub_categories":["Drupal"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1\u003eVite Plugin Twig Drupal\u003c/h1\u003e\n\n  \u003cimg\n    height=\"143\"\n    width=\"200\"\n    alt=\"goat\"\n    src=\"https://twig.symfony.com/images/logo.png\"\n  /\u003e\n\n\n\u003cp\u003eA Vite plugin that handles transforming twig files into a Javascript function that can be used with Storybook.\u003c/p\u003e\n\n\u003cbr /\u003e\n\u003c/div\u003e\n\n\u003chr /\u003e\n\n\u003c!-- prettier-ignore-start --\u003e\n[![Build status](https://github.com/larowlan/vite-plugin-twigdrupal/actions/workflows/node.js.yml/badge.svg)](https://github.com/larowlan/vite-plugin-twig-drupal/actions/workflows/node.js.yml)\n[![version][version-badge]][package] [![downloads][downloads-badge]][npmtrends]\n[![MIT License][license-badge]][license]\n[![PRs Welcome][prs-badge]][prs] \n\n[![Watch on GitHub][github-watch-badge]][github-watch]\n[![Star on GitHub][github-star-badge]][github-star]\n[![Tweet][twitter-badge]][twitter]\n\u003c!-- prettier-ignore-end --\u003e\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [The problem](#the-problem)\n- [This solution](#this-solution)\n- [Installation](#installation)\n- [Examples](#examples)\n- [Usage with React](#usage-with-react)\n- [Issues](#issues)\n  - [🐛 Bugs](#-bugs)\n  - [💡 Feature Requests](#-feature-requests)\n  - [❓ Questions](#-questions)\n- [LICENSE](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## The problem\n\nYou are working with Twig in a styleguide-driven-development process. You are writing isolated components\nthat consist of css, twig and Javascript.\nYou want to be able to use twig to render your components for [Storybook](https://storybook.js.org).\nYou want fast refresh with Vite.\nYou want Twig embeds, includes and extends to work.\nYou want to use Drupal specific twig features like create_attributes etc. \n\n## This solution\n\nThe `Vite plugin Twig Drupal` is a Vite plugin based on [Twig JS](https://github.com/twigjs/twig.js) for\ncompiling Twig-based components into a Javascript function so that they can be used as components with Storybook.\nIt allows you to import twig files into your story as though they are Javascript files.\n\n### Comparison to other solutions.\n\n* [Vite plugin twig loader](https://github.com/dark-kitt/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\n* [Components library server](https://www.drupal.org/project/cl_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](https://www.drupal.org/project/cl_components) or a similar Drupal module like [UI patterns](https://www.drupal.org/project/ui_patterns) then this may be a better option for you.\n\n## Installation\n\nThis module is distributed via [npm][npm] which is bundled with [node][node] and\nshould be installed as one of your project's `devDependencies`:\n\n```\nnpm install --save-dev vite-plugin-twig-drupal\n```\n\nYou then need to configure your vite.config.js.\n\n```javascript\nimport { defineConfig } from \"vite\"\nimport twig from 'vite-plugin-twig-drupal';\nimport { join } from \"node:path\"\n\nexport default defineConfig({\n  plugins: [\n    // Other vite plugins.\n    twig({\n      namespaces: {\n        components: join(__dirname, \"/path/to/your/components\"),\n        // Other namespaces as required.\n      },\n      // Optional if you are using React storybook renderer. The default is 'html' and works with storybook's html\n      // renderer.\n      // framework: 'react'\n      functions: {\n        // You can add custom functions - each is a function that is passed the active Twig instance and should call\n        // e.g. extendFunction to register a function\n        reverse: (twigInstance) =\u003e twigInstance.extendFunction(\"reverse\", () =\u003e (text) =\u003e text.split(' ').reverse().join(' ')),\n        // e.g. extendFilter to register a filter\n        clean_unique_id: (twigInstance) =\u003e twigInstance.extendFilter(\"clean_unique_id\", () =\u003e (text) =\u003e text.split(' ').reverse().join(' ')),\n      },\n      globalContext: {\n        // Global variables that should be present in all templates.\n        active_theme: 'my_super_theme',\n        is_front_page: false,\n      },\n    }),\n    // Other vite plugins.\n  ],\n})\n```\n\nWith this config in place you should be able to import twig files into your story files.\n\n## Examples\n\n```javascript\n// stories/Button.stories.js\n\n// Button will be a Javascript function that accepts variables for the twig template.\nimport Button from './button.twig';\n\n// Import stylesheets, this could be a sass or postcss file too.\nimport './path/to/button.css';\n// You may also have JavaScript for the component.\nimport './path/to/some/javascript/button.js';\n\nexport default {\n  title: 'Components/Button',\n  tags: ['autodocs'],\n  argTypes: {\n    title: {\n      control: { type: 'text' },\n    },\n    modifier: {\n      control: { type: 'select' },\n      options: ['primary', 'secondary', 'tertiary'],\n    },\n  },\n  // Just pass along the imported variable.\n  component: Button,\n};\n\n// Set default variables in the story.\nexport const Default = {\n  args: { title: 'Click me' },\n};\n\nexport const Primary = {\n  args: { title: 'Click me', modifier: 'primary' },\n};\n\n// Advanced example.\nexport const ButtonStrip = {\n  name: 'Button group',\n  render: () =\u003e `\n    ${Button({title: 'Button 1', modifier: 'primary'})} \n    ${Button({title: 'Button 2', modifier: 'secondary'})}\n  `\n}\n```\n\n## Usage with React\n\nWhen adding `framework: 'react'` to vite.config.js twig files will output React JSX functions\nthat can be used inside a React Storybook instance.\n\nThis way Twig components can be rendered alongside React components.\n\nHowever, you will need to revert to a straight TwigJS function import so you can nest Twig components\ninside other Twig components. In these instances append `?twig` to your component import. This will return a JavaScript function instead of a React component.\nWhen nesting \nTwig components inside React components this is not needed. Nesting React components inside Twig components\ndoes not work currently.\n\n```javascript\nimport Button from './button.twig';\nimport OtherComponent from ../other-component.twig?twig\n\nexport default {\n  title: 'Components/Button',\n  tags: ['autodocs'],\n  args: {\n    // Render by calling the component as a function.\n    // You can pass any variables down as an object.\n    otherComponent: OtherComponent(),\n  },\n  component: Button,\n};\n\n```\n\n## Issues\n\n### 🐛 Bugs\n\nPlease file an issue for bugs, missing documentation, or unexpected behavior.\n\n[**See Bugs**][bugs]\n\n### 💡 Feature Requests\n\nPlease file an issue to suggest new features. Vote on feature requests by adding\na 👍. This helps maintainers prioritize what to work on.\n\n[**See Feature Requests**][requests]\n\n### ❓ Questions\n\nFor questions related to using the library, please visit a support community\ninstead of filing an issue on GitHub.\n\n- [Drupal Slack #frontend channel](https://drupal.org/slack)\n\n## LICENSE\n\n[MIT](LICENSE)\n\n\u003c!-- prettier-ignore-start --\u003e\n\n[npm]: https://www.npmjs.com/\n[node]: https://nodejs.org\n[version-badge]: https://img.shields.io/npm/v/vite-plugin-twig-drupal.svg?style=flat-square\n[package]: https://www.npmjs.com/package/vite-plugin-twig-drupal\n[downloads-badge]: https://img.shields.io/npm/dm/vite-plugin-twig-drupal.svg?style=flat-square\n[npmtrends]: http://www.npmtrends.com/vite-plugin-twig-drupal\n[license-badge]: https://img.shields.io/npm/l/vite-plugin-twig-drupal.svg?style=flat-square\n[license]: https://github.com/larowlan/vite-plugin-twig-drupal/blob/master/LICENSE\n[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[prs]: http://makeapullrequest.com\n[github-watch-badge]: https://img.shields.io/github/watchers/larowlan/vite-plugin-twig-drupal.svg?style=social\n[github-watch]: https://github.com/larowlan/vite-plugin-twig-drupal/watchers\n[github-star-badge]: https://img.shields.io/github/stars/larowlan/vite-plugin-twig-drupal.svg?style=social\n[github-star]: https://github.com/larowlan/vite-plugin-twig-drupal/stargazers\n[twitter]: https://twitter.com/intent/tweet?text=Check%20out%20vite-plugin-twig-drupal%20by%20%40larowlan%20https%3A%2F%2Fgithub.com%2Flarowlan%2Fvite-plugin-twig-drupal%20%F0%9F%91%8D\n[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/larowlan/vite-plugin-twig-drupal.svg?style=social\n[bugs]: https://github.com/larowlan/vite-plugin-twig-drupal/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc\n[requests]: https://github.com/larowlan/vite-plugin-twig-drupal/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen\n[good-first-issue]: https://github.com/larowlan/vite-plugin-twig-drupal/issues?utf8=✓\u0026q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A\"good+first+issue\"+\n\n\u003c!-- prettier-ignore-end --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarowlan%2Fvite-plugin-twig-drupal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flarowlan%2Fvite-plugin-twig-drupal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarowlan%2Fvite-plugin-twig-drupal/lists"}