Twig-html-loader NPM

twig-html-loader

A loader for webpack that allows compiling twig templates into html string.

Getting Started

To begin, you'll need to install twig-html-loader:

npm install twig-html-loader --save-dev

Add twig template to your sources:

var html = require('./index.twig');

Then add the loader to your webpack config. For example:

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

Using with html-webpack-plugin

Install plugin:

npm install html-webpack-plugin --save-dev

Improve your config:

const HtmlWebpackPlugin = require('html-webpack-plugin');
// ...
module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        'twig-html-loader'
      ]
    }
    // ...
  ],
  plugins: [
    // ...
    new HtmlWebpackPlugin({
      template: 'index.twig'
    })
  ]
};

Options

Name	Type	Default	Description
cache	boolean	false	Enables the Twigjs cache
data	object or function(context)	{}	The data that is exposed in the templates. Function should return an object
debug	boolean	false	Enables debug info logging
trace	boolean	false	Enables tracing info logging
namespaces	object	undefined	Add special template path notation (ex.: `@namespace_name/template_path`)
functions	object	undefined	Extends Twig with custom functions
filters	object	undefined	Extends Twig with custom filters
tests	object	undefined	Extends Twig with custom tests
extend	function(Twig)	undefined	Extends Twig with custom tags and more

Watch data from files

module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        {
          loader: 'twig-html-loader',
          options: {
            data: (context) => {
              const data = path.join(__dirname, 'data.json');
              context.addDependency(data); // Force webpack to watch file
              return context.fs.readJsonSync(data, { throws: false }) || {};
            }
          }
        }
      ]
    }
    // ...
  ]
};

Do not use require function due to file caching.

Namespaces

If the application defines lots of templates and stores them in deep nested directories, you may consider using namespaces, which create shortcuts to template directories. The registered namespace should be defined with @ prefix or :: postfix when using it in templates.

module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        {
          loader: 'twig-html-loader',
          options: {
            namespaces: {
              'layouts': 'path/to/layouts',
              'components': 'path/to/components',
            }
          }
        }
      ]
    }
    // ...
  ]
};

{# path/to/layouts/common.twig #}
<h1>{% block title %}{% endblock %}</h1>

{# path/to/components/greeting.twig #}
Hello, John Doe!

{# your-template.twig #}
{% extends "layouts::common.twig" %}
{% block title %}
  {{ include('@components/greeting.twig') }}
{% endblock %}

Custom functions, filters, tests and tags

You can use functions, filters, tests and extend options to extend Twig. See here for adding custom functions, filters and tests, and here for adding custom tags.

module.exports = {
  // ...
  rules: [
    // ...
    {
      test: /\.twig$/,
      use: [
        'raw-loader',
        {
          loader: 'twig-html-loader',
          options: {
            functions: {
              repeat(value, times) {
                return new Array(times + 1).join(value);
              }
            },
            filters: {
              backwords(value) {
                return value.split(' ').reverse().join(' ');
              }
            },
            tests: {
              theAnswer(value) {
                return value === 42;
              }
            },
            extend(Twig) {
              Twig.exports.extendTag({
                type: 'echo',
                regex: /^echo\s+(.+)$/,
                next: [],
                open: true,
                compile: function (token) {
                  var expression = token.match[1];

                  token.stack = Twig.expression.compile.apply(this, [{
                    type: Twig.expression.type.expression,
                    value: expression
                  }]).stack;

                  delete token.match;
                  return token;
                },
                parse: function (token, context, chain) {
                  return {
                    chain: false,
                    output: Twig.expression.parse.apply(this, [token.stack, context])
                  };
                }
              });
            }
          }
        }
      ]
    }
    // ...
  ]
};

{{ repeat('_.', 10) }}
{# output: _._._._._._._._._._. #}

{{ 'a quick brown fox'|backwords }}
{# output: fox brown quick a #}

{% if 42 is theAnswer %}42{% endif %}
{# output: 42 #}

{% echo 'hello world' %}
{# output: hello world #}