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 #}

Alternatives

twig-loader

License

MIT (http://www.opensource.org/licenses/mit-license.php)