vite-plugin-twig-drupal 1.0.0

package/.github/workflows/node.js.yml

@@ -0,0 +1,73 @@
+name: validate
+on:
+  push:
+    branches:
+      - 'master'
+      - 'beta'
+  pull_request: {}
+jobs:
+  main:
+    strategy:
+      matrix:
+        node: [16, 18]
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🛑 Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.9.0
+
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: 📥 Download deps
+        uses: bahmutov/npm-install@v1
+        with:
+          useLockFile: false
+
+      - name: 🧹 Linting
+        run: npm run lint
+
+      - name: ✅ Tests
+        run: npm run test
+
+  release:
+    needs: main
+    runs-on: ubuntu-latest
+    if:
+      ${{ github.repository == 'larowlan/vite-plugin-twig-drupal' &&
+      contains('refs/heads/master',github.ref) && github.event_name == 'push' }}
+    steps:
+      - name: 🛑 Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.9.0
+
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@v2
+        with:
+          node-version: 18
+
+      - name: 📥 Download deps
+        uses: bahmutov/npm-install@v1
+        with:
+          useLockFile: false
+
+      - name: 🏗 Run build script
+        run: npm run build
+
+      - name: 🚀 Release
+        uses: cycjimmy/semantic-release-action@v4
+        with:
+          semantic_version: 22
+          branches: |
+            [
+              'master'
+            ]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "endOfLine": "lf",
+  "semi": false,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "bracketSpacing": true
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Lee Rowlands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+<div align="center">
+<h1>Vite Plugin Twig Drupal</h1>
+
+  <img
+    height="143"
+    width="200"
+    alt="goat"
+    src="https://twig.symfony.com/images/logo.png"
+  />
+
+
+<p>A Vite plugin that handles transforming twig files into a Javascript function that can be used with Storybook.</p>
+
+<br />
+</div>
+
+<hr />
+
+<!-- prettier-ignore-start -->
+[![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)
+[![version][version-badge]][package] [![downloads][downloads-badge]][npmtrends]
+[![MIT License][license-badge]][license]
+[![PRs Welcome][prs-badge]][prs] 
+
+[![Watch on GitHub][github-watch-badge]][github-watch]
+[![Star on GitHub][github-star-badge]][github-star]
+[![Tweet][twitter-badge]][twitter]
+<!-- prettier-ignore-end -->
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [The problem](#the-problem)
+- [This solution](#this-solution)
+- [Installation](#installation)
+- [Examples](#examples)
+- [Issues](#issues)
+  - [🐛 Bugs](#-bugs)
+  - [💡 Feature Requests](#-feature-requests)
+  - [❓ Questions](#-questions)
+- [LICENSE](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## The problem
+
+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](https://storybook.js.org).
+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. 
+
+## This solution
+
+The `Vite plugin Twig Drupal` is a Vite plugin based on [Twig JS](https://github.com/twigjs/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.
+
+### Comparison to other solutions.
+
+* [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
+* [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.
+
+## Installation
+
+This module is distributed via [npm][npm] which is bundled with [node][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.
+
+```javascript
+import { defineConfig } from "vite"
+import twig from "./src/index.js"
+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' 
+    }),
+    // Other vite plugins.
+  ],
+})
+```
+
+With this config in place you should be able to import twig files into your story files.
+
+## Examples
+
+```javascript
+// stories/Button.stories.js
+
+// Button will be a Javascript function that excepts 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'})}
+  `
+}
+
+
+
+```
+- Refer to the [Dom testing library docs](https://testing-library.com/docs/dom-testing-library/example-intro), we're really just adding the ability to render twig templates on top of that.
+
+## Issues
+
+### 🐛 Bugs
+
+Please file an issue for bugs, missing documentation, or unexpected behavior.
+
+[**See Bugs**][bugs]
+
+### 💡 Feature Requests
+
+Please file an issue to suggest new features. Vote on feature requests by adding
+a 👍. This helps maintainers prioritize what to work on.
+
+[**See Feature Requests**][requests]
+
+### ❓ Questions
+
+For questions related to using the library, please visit a support community
+instead of filing an issue on GitHub.
+
+- [Drupal Slack #frontend channel](https://drupal.org/slack)
+
+## LICENSE
+
+[MIT](LICENSE)
+
+<!-- prettier-ignore-start -->
+
+[npm]: https://www.npmjs.com/
+[node]: https://nodejs.org
+[version-badge]: https://img.shields.io/npm/v/vite-plugin-twig-drupal.svg?style=flat-square
+[package]: https://www.npmjs.com/package/vite-plugin-twig-drupal
+[downloads-badge]: https://img.shields.io/npm/dm/vite-plugin-twig-drupal.svg?style=flat-square
+[npmtrends]: http://www.npmtrends.com/vite-plugin-twig-drupal
+[license-badge]: https://img.shields.io/npm/l/vite-plugin-twig-drupal.svg?style=flat-square
+[license]: https://github.com/larowlan/vite-plugin-twig-drupal/blob/master/LICENSE
+[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
+[prs]: http://makeapullrequest.com
+[github-watch-badge]: https://img.shields.io/github/watchers/larowlan/vite-plugin-twig-drupal.svg?style=social
+[github-watch]: https://github.com/larowlan/vite-plugin-twig-drupal/watchers
+[github-star-badge]: https://img.shields.io/github/stars/larowlan/vite-plugin-twig-drupal.svg?style=social
+[github-star]: https://github.com/larowlan/vite-plugin-twig-drupal/stargazers
+[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
+[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/larowlan/vite-plugin-twig-drupal.svg?style=social
+[bugs]: https://github.com/larowlan/vite-plugin-twig-drupal/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc
+[requests]: https://github.com/larowlan/vite-plugin-twig-drupal/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen
+[good-first-issue]: https://github.com/larowlan/vite-plugin-twig-drupal/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+
+
+<!-- prettier-ignore-end -->

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "vite-plugin-twig-drupal",
+  "version": "1.0.0",
+  "description": "Provides a ⚡️ Vite plugin to transform 🌱 Twig into HTML with a 💧 Drupal flavour",
+  "keywords": [
+    "Vite",
+    "Vite plugin",
+    "Twig",
+    "Storybook",
+    "Drupal"
+  ],
+  "author": "larowlan <23667-larowlan@users.noreply.drupalcode.org>",
+  "license": "GPL-2.0-or-later",
+  "main": "./src/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "rm -rf dist && vite build",
+    "format": "prettier --write \"{test,src}/**/*.js\"",
+    "lint": "prettier --check \"{test,src}/**/*.js\"",
+    "test": "vitest run",
+    "pretest": "npm run-script build",
+    "semantic-release": "semantic-release"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/larowlan/vite-plugin-twig-drupal.git"
+  },
+  "dependencies": {
+    "drupal-attribute": "^1.0.2",
+    "drupal-twig-extensions": "^1.0.0-beta.5",
+    "twig": "^1.16.0"
+  },
+  "peerDependencies": {
+    "vite": "^4.4.11"
+  },
+  "devDependencies": {
+    "prettier": "^3.0.3",
+    "semantic-release": "^22.0.5",
+    "vite": "^4.4.11",
+    "vitest": "^0.34.6"
+  }
+}

package/src/index.js

@@ -0,0 +1,183 @@
+import Twig from "twig"
+const { twig } = Twig
+import { resolve } from "node:path"
+
+const FRAMEWORK_REACT = "react"
+const FRAMEWORK_HTML = "html"
+
+const defaultOptions = {
+  namespaces: {},
+  filters: {},
+  functions: {},
+  framework: FRAMEWORK_HTML,
+  pattern: /\.(twig)(\?.*)?$/,
+}
+Twig.cache(false)
+
+const includeTokenTypes = [
+  "Twig.logic.type.embed",
+  "Twig.logic.type.include",
+  "Twig.logic.type.extends",
+]
+
+const pluckIncludes = (tokens) => {
+  return [
+    ...tokens
+      .filter((token) => includeTokenTypes.includes(token.token?.type))
+      .reduce(
+        (carry, token) => [
+          ...carry,
+          ...token.token.stack.map((stack) => stack.value),
+        ],
+        []
+      ),
+    ...tokens.reduce(
+      (carry, token) => [...carry, ...pluckIncludes(token.token?.output || [])],
+      []
+    ),
+  ].filter((value, index, array) => {
+    return array.indexOf(value) === index
+  })
+}
+
+const compileTemplate = (id, file, { namespaces }) => {
+  return new Promise((resolve, reject) => {
+    const options = { namespaces, rethrow: true, allowInlineIncludes: true }
+    twig({
+      id,
+      path: file,
+      error: reject,
+      allowInlineIncludes: true,
+      load(template) {
+        if (typeof template.tokens === "undefined") {
+          reject("Error compiling twig file")
+          return
+        }
+        resolve({
+          includes: pluckIncludes(template.tokens),
+          code: template.compile(options),
+        })
+      },
+    })
+  })
+}
+
+Twig.cache(false)
+
+const errorHandler = (id) => (e) => ({
+  code: `export default () => 'An error occurred whilst rendering ${id}: ${e.toString()}';`,
+  map: null,
+})
+
+const plugin = (options = {}) => {
+  options = { ...defaultOptions, ...options }
+  return {
+    name: "vite-plugin-twig-drupal",
+    config: ({ root }) => {
+      if (!options.root) {
+        options.root = root
+      }
+    },
+    async shouldTransformCachedModule(src, id) {
+      return options.pattern.test(id)
+    },
+    async transform(src, id) {
+      if (options.pattern.test(id)) {
+        let frameworkInclude = ""
+        let frameworkTransform = "const frameworkTransform = (html) => html;"
+        if (options.framework === FRAMEWORK_REACT) {
+          frameworkInclude = `import React from 'react'`
+          frameworkTransform = `const frameworkTransform = (html) => React.createElement('div', {dangerouslySetInnerHTML: {'__html': html}});;`
+        }
+        let embed,
+          embeddedIncludes,
+          code,
+          includes,
+          seen = []
+        try {
+          const result = await compileTemplate(id, id, options).catch(
+            errorHandler(id)
+          )
+          if ("map" in result) {
+            // An error occurred.
+            return result
+          }
+          code = result.code
+          includes = result.includes
+          const includePromises = []
+          const processIncludes = (template) => {
+            const file = Twig.path.expandNamespace(options.namespaces, template)
+            if (!seen.includes(file)) {
+              includePromises.push(
+                new Promise(async (resolve) => {
+                  const { includes, code } = await compileTemplate(
+                    template,
+                    file,
+                    options
+                  )
+                  includes.forEach(processIncludes)
+                  resolve(code)
+                })
+              )
+              seen.push(file)
+            }
+          }
+          includes.forEach(processIncludes)
+          embed = includes
+            .map(
+              (template) =>
+                `import '${resolve(
+                  Twig.path.expandNamespace(options.namespaces, template)
+                )}';`
+            )
+            .join("\n")
+          const includeResult = await Promise.all(includePromises).catch(
+            errorHandler(id)
+          )
+          if (!Array.isArray(includeResult) && "map" in includeResult) {
+            // An error occurred.
+            return includeResult
+          }
+          embeddedIncludes = includeResult.reverse().join("\n")
+        } catch (e) {
+          return errorHandler(id)(e)
+        }
+        const output = `
+        import Twig, { twig } from 'twig';
+        import DrupalAttribute from 'drupal-attribute';
+        import { addDrupalExtensions } from 'drupal-twig-extensions/twig';
+        ${frameworkInclude}
+        
+        ${embed}
+
+        addDrupalExtensions(Twig);
+        // Disable caching.
+        Twig.cache(false);
+
+
+        ${embeddedIncludes};
+        ${frameworkTransform};
+        export default (context = {}) => {
+          const component = ${code}
+          ${includes ? `component.options.allowInlineIncludes = true;` : ""}
+          try {
+            return frameworkTransform(component.render({
+            attributes: new DrupalAttribute(),
+              ...context
+            }));
+          }
+          catch (e) {
+            return frameworkTransform('An error occurred whilst rendering ${id}: ' + e.toString());
+          }
+        }`
+        return {
+          code: output,
+          map: null,
+          dependencies: seen,
+        }
+      }
+    },
+  }
+}
+
+export default plugin

package/tests/__snapshots__/smoke.test.js.snap

@@ -0,0 +1,47 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Basic smoke test > Should support includes 1`] = `
+"<section>
+  <h1>Include</h1>
+  <article>
+          Lorem ipsum dolor sit amet, consectetur adipisicing elit. At dignissimos fugiat inventore laborum maiores molestiae neque quia quo unde veniam?
+      </article>
+</section>
+<section>
+  <h1>Embed</h1>
+  <article>
+        Lorem ipsum dolor sit amet.
+    <button class=\\"button--primary\\">Nested include</button>
+    </article>
+</section>
+<section>
+  <h1></h1>
+  <article>
+          Lorem ipsum dolor sit amet, consectetur adipisicing elit. At dignissimos fugiat inventore laborum maiores molestiae neque quia quo unde veniam?
+      </article>
+</section>
+"
+`;
+
+exports[`Basic smoke test > Should support variables 1`] = `
+"<section>
+  <h1>Include</h1>
+  <article>
+          Lorem ipsum dolor sit amet, consectetur adipisicing elit. At dignissimos fugiat inventore laborum maiores molestiae neque quia quo unde veniam?
+      </article>
+</section>
+<section>
+  <h1>Embed</h1>
+  <article>
+        Lorem ipsum dolor sit amet.
+    <button class=\\"button--primary\\">Nested include</button>
+    </article>
+</section>
+<section>
+  <h1>Pickle Fixie</h1>
+  <article>
+          Lorem ipsum dolor sit amet, consectetur adipisicing elit. At dignissimos fugiat inventore laborum maiores molestiae neque quia quo unde veniam?
+      </article>
+</section>
+"
+`;

package/tests/fixtures/button.twig

@@ -0,0 +1 @@
+<button class="{{ modifier_class|default('button--primary') }}">{{ text|default('Click me!') }}</button>

package/tests/fixtures/error.twig

@@ -0,0 +1,3 @@
+{% if true %}
+  Yep this is broken
+{% endblock %}

package/tests/fixtures/mockup.twig

@@ -0,0 +1,8 @@
+{% include "@tests/section.twig" with {title: 'Include'} %}
+{% embed "@tests/section.twig" with {title: 'Embed'} %}
+  {% block content %}
+    Lorem ipsum dolor sit amet.
+    {% include "@tests/button.twig" with {text: 'Nested include'} %}
+  {% endblock %}
+{% endembed %}
+{% include "@tests/section.twig" %}

package/tests/fixtures/section.twig

@@ -0,0 +1,8 @@
+<section>
+  <h1>{{ title }}</h1>
+  <article>
+    {% block content %}
+      Lorem ipsum dolor sit amet, consectetur adipisicing elit. At dignissimos fugiat inventore laborum maiores molestiae neque quia quo unde veniam?
+    {% endblock %}
+  </article>
+</section>

package/tests/smoke.test.js

@@ -0,0 +1,20 @@
+import Markup from "../dist/test.js"
+import Error from "../dist/error.js"
+import { describe, expect, it } from "vitest"
+
+describe("Basic smoke test", () => {
+  it("Should support includes", () => {
+    const markup = Markup()
+    expect(markup).toMatchSnapshot()
+    expect(markup).toContain("Nested include")
+  })
+  it("Should support variables", () => {
+    const markup = Markup({ title: "Pickle Fixie" })
+    expect(markup).toMatchSnapshot()
+    expect(markup).toContain("Pickle Fixie")
+  })
+  it("Should recover from errors", () => {
+    const error = Error()
+    expect(error).toContain("An error occurred")
+  })
+})

package/vite.config.js

@@ -0,0 +1,27 @@
+import { defineConfig } from "vite"
+import twig from "./src/index.js"
+import { join, resolve } from "node:path"
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  build: {
+    lib: {
+      entry: {
+        test: resolve(__dirname, "tests/fixtures/mockup.twig"),
+        error: resolve(__dirname, "tests/fixtures/error.twig"),
+      },
+      name: "vite-plugin-twig-drupal",
+      fileName: (_, entry) => `${entry}.js`,
+    },
+  },
+  plugins: [
+    twig({
+      namespaces: {
+        tests: join(__dirname, "/tests/fixtures"),
+      },
+    }),
+  ],
+  resolve: {
+    preserveSymlinks: true,
+  },
+})