twig-loader

0.5.5 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader for pre-compiling Twig.js templates. Current stable version is 0.5.5. It compiles .twig files into JavaScript functions and automatically includes Twig.js runtime. Key differentiators: supports all Twig inheritance features (import, include, extends, embed) and resolves template dependencies statically. It is maintained by the community but has seen infrequent updates, with the last release in 2018. Requires webpack and the 'twig' package as peer dependency (~1.10.5).

Common errors

error Module not found: Error: Can't resolve 'twig' in '/path/to/project' ↓

cause The peer dependency 'twig' is not installed.

fix

Run: npm install twig@~1.10.5

error TypeError: template is not a function ↓

cause Twig template is required but not compiled correctly, or the loader is not applied.

fix

Ensure webpack rule matches .twig files and twig-loader is installed. Check that the loader is in the rules array.

error Cannot find module './partial.twig' (while resolving 'template.twig') ↓

cause Relative path in include/extends cannot be resolved by webpack.

fix

Double-check path relative to the template file. Use absolute path with webpack's context or register template at runtime.

Warnings

breaking Peer dependency 'twig' version ~1.10.5 may cause compatibility issues with newer Twig.js versions. Using a different version may break template compilation. ↓

fix Install twig@~1.10.5 explicitly: npm install twig@~1.10.5

gotcha Dynamic template imports (e.g., include(variable)) are not resolved by webpack and require manual runtime registration. ↓

fix Use require.context to preload dynamic templates and register them via twig() with the tokens property.

gotcha In Webpack 4+, setting node: { fs: 'empty' } is deprecated. Use resolve.fallback instead. ↓

fix Use resolve.fallback: { fs: false } in webpack config for Webpack 4+.

deprecated Security fix in 0.5.2 addressed a vulnerability in mocha dev dependency. However, no CVEs were reported for the loader itself. ↓

fix Upgrade to 0.5.2 or later.

gotcha The loader uses webpack's 'require' to resolve template dependencies. Ensure relative paths in templates are correct relative to the template file. ↓

fix Use absolute paths or paths relative to the template file for include/extends/import.

Install

npm install twig-loader

yarn add twig-loader

pnpm add twig-loader

Imports

twig-loader (default)

wrong

module.exports = { module: { loaders: [ { test: /\.twig$/, loader: 'twig-loader' } ] } }

correct

module.exports = { module: { rules: [ { test: /\.twig$/, use: { loader: 'twig-loader' } } ] } }

Webpack 1 uses 'loaders' array and 'loader' string property; Webpack 2+ uses 'rules' array and 'use' object. For old Webpack 1 config, use the wrong pattern.

template (compiled module)

wrong

var html = require('./dialog.html.twig')({title: 'dialog title'});

correct

var template = require('./dialog.html.twig');
var html = template({title: 'dialog title'});

The required module returns a function directly, not the rendered output. You must call it with context.

twig function (runtime registration)
wrong
```
var twig = require('twig').twig;
twig({ id: 'my-template', data: template });
```
correct
```
var twig = require('twig').twig;
twig({ id: 'my-template', data: template.tokens });
```
When registering dynamic templates at runtime, use the exported 'tokens' property on the compiled template function, not the function itself.

Quickstart

Shows Webpack configuration with twig-loader and usage in JavaScript: require a .twig file, call it with context to render HTML.

// webpack.config.js
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.twig$/,
        use: {
          loader: 'twig-loader',
          options: {
            twigOptions: { autoescape: true }
          }
        }
      }
    ]
  },
  node: {
    fs: 'empty'
  }
};

// src/index.js
var template = require('./template.html.twig');
var html = template({ title: 'Hello' });
document.body.innerHTML = html;

// src/template.html.twig
// <p>{{title}}</p>