Skip to content

Latest commit

 

History

History
190 lines (151 loc) · 3.28 KB

MIGRATION.md

File metadata and controls

190 lines (151 loc) · 3.28 KB

Migration guide

From v1.x to v2.x

1. [Breaking change] The template path has been moved to the script tag's data-template attribute.

Replace this:

<script type="application/json">
  {
    "template": "path/to/template.twig",
    "data": {
      "foo": "bar"
    }
  }
</script>

with this:

<script type="application/json" data-template="path/to/template.twig">
  {
    "foo": "bar"
  }
</script>

ℹ️ The data property is no longer required in the JSON schema.

2. [Breaking change] Plain text content is no longer supported within .html files.

Replace this:

{
  "template": "path/to/template.twig",
  "data": {
    "foo": "bar"
  }
}

with this:

<script type="application/json" data-template="path/to/template.twig">
  {
    "foo": "bar"
  }
</script>

3. [Breaking change] Twig's extensions are now wrapped in the extensions property within the configuration.

Replace this:

/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

export default defineConfig({
  // ...
  plugins: [
    twig({
      // ...
      filters: {
        // ...
      },
      functions: {
        // ...
      }
    })
  ]
})

with this:

/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

export default defineConfig({
  // ...
  plugins: [
    twig({
      // ...
      extensions: {
        filters: {
          // ...
        },
        functions: {
          // ...
        }
      }
    })
  ]
})

4. [New option] Twig's internal template caching is now configurable.

/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

export default defineConfig({
  // ...
  plugins: [
    twig({
      // ...
      cache: true
    })
  ]
})

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

/* vite.config.js */
import { defineConfig } from 'vite'
import twig from 'vite-plugin-twig'

export default defineConfig({
  // ...
  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

/* 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>
  <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>