feat: files and fragments filtering helpers + config refactoring

fiadone · Aug 6, 2022 · 4f5c377 · 4f5c377
1 parent f0a4659
commit 4f5c377
Show file tree

Hide file tree

Showing 9 changed files with 260 additions and 106 deletions.
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -50,28 +50,52 @@ with this:
 ```
 
 
-### 3. [New feature] __Multiple *script* tags are now supported within the same *.html* file and can live together with standard *HTML* code.__
+### 3. [Breaking change] __*Twig*'s extensions are now wrapped in the *extensions* property within the configuration.__
 
-```html
-<html>
-  <body>
-
-    <!-- other html contents -->
+Replace this:
+```js
+/* vite.config.js */
+import { defineConfig } from 'vite'
+import twig from 'vite-plugin-twig'
 
-    <script type="application/json" data-template="path/to/fragment-a.twig">
-      {
-        "foo": "bar"
+export default defineConfig({
+  // ...
+  plugins: [
+    twig({
+      // ...
+      filters: {
+        // ...
+      },
+      functions: {
+        // ...
       }
-    </script>
-
-    <!-- other html contents -->
+    })
+  ]
+})
+```
 
-    <script type="application/json" data-template="path/to/fragment-b.twig"></script>
+with this:
+```js
+/* vite.config.js */
+import { defineConfig } from 'vite'
+import twig from 'vite-plugin-twig'
 
-    <!-- other html contents -->
-
-  </body>
-</html>
+export default defineConfig({
+  // ...
+  plugins: [
+    twig({
+      // ...
+      extensions: {
+        filters: {
+          // ...
+        },
+        functions: {
+          // ...
+        }
+      }
+    })
+  ]
+})
 ```
 
 
@@ -93,11 +117,74 @@ export default defineConfig({
 })
 
 ```
-or
+
+
+### 5. [New option] __Via the *fileFilter* option, now the plugin provides a custom way to determine if the current transforming .html file should be processed/ignored or not__
+
 ```js
-/* twig.config.js */
-module.exports = {
+/* vite.config.js */
+import { defineConfig } from 'vite'
+import twig from 'vite-plugin-twig'
+
+export default defineConfig({
   // ...
-  cache: true
-}
+  plugins: [
+    twig({
+      // ...
+      fileFilter: filename => {
+        // your custom logic
+        return true // or false
+      }
+    })
+  ]
+})
+
 ```
+
+
+### 6. [New option] __Via the *fragmentFilter* option, now the plugin provides a custom way to determine if a matched fragment should be processed/ignored or not__
+
+```js
+/* vite.config.js */
+import { defineConfig } from 'vite'
+import twig from 'vite-plugin-twig'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    twig({
+      // ...
+      fragmentFilter: (fragment, template, data) => {
+        // your custom logic
+        return true // or false
+      }
+    })
+  ]
+})
+
+```
+
+
+### 7. [New feature] __Multiple *script* tags are now supported within the same *.html* file and can live together with standard *HTML* code.__
+
+```html
+<html>
+  <body>
+
+    <!-- other html contents -->
+
+    <script type="application/json" data-template="path/to/fragment-a.twig">
+      {
+        "foo": "bar"
+      }
+    </script>
+
+    <!-- other html contents -->
+
+    <script type="application/json" data-template="path/to/fragment-b.twig"></script>
+
+    <!-- other html contents -->
+
+  </body>
+</html>
+```
diff --git a/README.md b/README.md
@@ -24,50 +24,94 @@ import twig from 'vite-plugin-twig'
 export default defineConfig({
   // ...
   plugins: [
-    twig()
+    twig({ /* ...options */ })
   ]
 })
 ```
 
 ### Options
-The plugin can be configured both via the *twig.config.js* file from the project root or by passing a configuration object directly as argument to the function above (in this last case, the configuration file will be ignored).
+The plugin can be configured both directly with the options parameter shown above or via the dedicated *twig.config.(js|ts)* file, like following:
+
+```js
+/* twig.config.js */
+import { defineConfig } from 'vite-plugin-twig'
+
+export default defineConfig({
+  // ...
+})
+```
+
+> ℹ️ *defineConfig* is a bypass function with type hints, which means you can also omit it if you don't need the autocompletion/typecheck.
 
 Here below the list of the supported options.
 
 #### `cache`
-__type__ `Boolean`
+__type:__ `boolean`
 
-__default__ `false`
+__default:__ `false`
 
 If *true*, it enables internal *Twig*'s template caching.
 
-#### `filters`
-__type__ `{ [key: String]: (...args: Any[]) => Any }`
+#### `extensions`
+__type:__ `{ filters: TwigExtensions, functions: TwigExtensions }`
+
+__default:__ `undefined`
+
+A collection of custom filters and functions to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.
+
+#### `fileFilter`
+__type:__ `(filename: string) => boolean`
+
+__default:__ `undefined`
+
+A custom filter to determine if the current transforming *.html* file should be processed/ignored or not (useful for improving compatibility with other plugins).
 
-__default__ `{}`
+Example:
+```js
+/* twig.config.js */
+import { defineConfig } from 'vite-plugin-twig'
 
-A collection of custom filters to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.
+export default defineConfig({
+  // ...
+  fileFilter: filename => filename.endsWith('.twig.html')
+})
+```
+
+#### `fragmentFilter`
+__type:__ `TwigFragmentFilter`
 
-#### `functions`
-__type__ `{ [key: String]: (...args: Any[]) => Any }`
+__default:__ `undefined`
 
-__default__ `{}`
+A custom filter to determine if the current matched fragment should be processed/ignored or not (useful for improving compatibility with other plugins).
 
-A collection of custom functions to extend *Twig*. Look at [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/Extending-twig.js) to learn more.
+Example:
+```js
+/* twig.config.js */
+import { defineConfig } from 'vite-plugin-twig'
+
+export default defineConfig({
+  // ...
+  fragmentFilter: (fragment, template, data) => {
+    return fragment.indexOf('data-engine="twig"') > -1
+    // or  template.endsWith('.twig')
+    // or  data.engine === 'twig'
+  }
+})
+```
 
 #### `globals`
-__type__ `{ [key: String]: Any }`
+__type:__ `{ [key: string]: any }`
 
-__default__ `{}`
+__default:__ `undefined`
 
 The global variables to be injected in each template.
 
 #### `settings`
-__type__ `{ [key: String]: Any }`
+__type:__ `{ views: any, 'twig options': any }`
 
-__default__ `{}`
+__default:__ `undefined`
 
-The *Twig* settings. Please refer to [*twig.js* documentation](https://github.com/twigjs/twig.js/wiki/) to learn more.
+The *Twig* settings. Please refer to *twig.js* [documentation](https://github.com/twigjs/twig.js/wiki/) and [types](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/twig/index.d.ts) to learn more.
 
 
 ### Templates

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-twig",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "license": "MIT",
   "keywords": [
     "vite-plugin",

diff --git a/playground/vite.config.js b/playground/vite.config.js
@@ -1,5 +1,5 @@
 import { defineConfig } from 'vite'
-import twig from '../src'
+import twig from 'vite-plugin-twig'
 
 export default defineConfig({
   plugins: [

diff --git a/src/config.ts b/src/config.ts
@@ -0,0 +1,5 @@
+import type { PluginOptions } from '../types'
+
+export function defineConfig(options: PluginOptions) {
+  return options
+}
diff --git a/src/index.ts b/src/index.ts
@@ -1,3 +1,3 @@
-import { viteTwigPlugin } from './plugin'
+export { defineConfig } from './config'
+export { viteTwigPlugin as default } from './plugin'
 
-export default viteTwigPlugin
diff --git a/src/plugin.ts b/src/plugin.ts
@@ -1,18 +1,21 @@
-import path from 'path'
+import path from 'node:path'
 import type { Plugin } from 'vite'
-import type { TwigOptions } from '../types'
-import { retrieveOptionsFromConfigFile, configureTwig, parseHTML } from './tasks'
+import type { PluginOptions } from '../types'
+import { configureTwig, parseHTML, retrieveConfigFromFile } from './tasks'
 
-export function viteTwigPlugin(options: TwigOptions): Plugin {
-  const { cache, filters, functions, globals, settings } = options || retrieveOptionsFromConfigFile()
+export async function viteTwigPlugin(options: PluginOptions): Promise<Plugin> {
 
-  configureTwig({ cache, filters, functions })
+  const config = options || await retrieveConfigFromFile()
+
+  configureTwig(config)
 
   return {
     name: 'vite-plugin-twig',
     transformIndexHtml: {
       enforce: 'pre',
-      transform: html => parseHTML(html, { globals, settings })
+      transform: async (html, ctx) => {
+        return await parseHTML(html, ctx, config)
+      }
     },
     handleHotUpdate({ file, server }) {
       if (path.extname(file) === '.twig') {