@mediamonks/twing-loader

twing-loader

Webpack loader for Twig templates, based on Twing.

Modified for usage in Muban, to work with a more modern webpack and project setup (mostly ES Modules).

Prerequisites

• Webpack 4
• Twing 5.0.2

Installation

npm install -D twing-loader

Usage

twing-loader comes with two available behaviors. Depending on your need, you can use one or the other by setting the renderContext or environmentModulePathContent option accordingly.

Render at runtime

By default, twing-loader transforms a Twig template to a function that, when called with some optional data, renders the template:

_{webpack.config.js}

module.exports = {
    entry: 'index.js',
    // ...
    module: {
        rules: [
            {
                test: /\.twig$/,
                use: [
                    {
                        loader: 'twing-loader',
                        options: {
                            // must be commonjs to allow the webpack require chain to work
                            environmentModulePathLoader: require.resolve('./environment.cjs'),
                            // should probably be a ES module when used in modern projects, is injected in the bundled code
                            // only needed when not providing a renderContext
                            environmentModulePathContent: require.resolve('./environment.js')
                        }
                    }
                ]
            }
        ]
    }
}

_{environment.js}

const {TwingEnvironment, TwingLoaderRelativeFilesystem} = require("twing");

module.exports = new TwingEnvironment(
    new TwingLoaderRelativeFilesystem()
);

_index.twig

{{ foo }}

_index.js

let template = require('./index.twig');

template({
    foo: 'bar'
}).then((renderedTemplate) => {
    // "bar" 
});

This behavior, known as render at runtime, comes at the cost of having Twing as part of the bundle.

Render at compile time

When renderContext is defined, twing-loader transforms a Twig template to the result of the template rendering:

_{webpack.config.js}

module.exports = {
    entry: 'index.js',
    // ...
    module: {
        rules: [
            {
                test: /\.twig$/,
                use: [
                    {
                        loader: 'twing-loader',
                        options: {
                            environmentModulePathLoader: require.resolve('./environment.js'),
                            // when passing a renderContext, it renders everything in node
                            // it doesn't generate any runtime template code, so `environmentModulePathContent` is not needed
                            renderContext: {
                                foo: 'bar'
                            }
                        }
                    }
                ]
            }
        ]
    }
}

_{environment.js}

const {TwingEnvironment, TwingLoaderRelativeFilesystem} = require("twing");

module.exports = new TwingEnvironment(
    new TwingLoaderRelativeFilesystem()
);

_index.twig

{{ foo }}

_index.js

require('./index.twig').then((renderedTemplate) => {
    // "bar"
});

This second behavior, known as render at compile time, comes with the benefit of not having Twing as part of the bundle.

Options

Name	Required	Type	Default	Description
environmentModulePathLoader	true	string	undefined	The absolute path or the identifier to the module that exports the TwingEnvironment instance that will be used by the loader to compile the templates at compile time.
environmentModulePathContent	false	string	undefined	The absolute path or the identifier to the module that exports the TwingEnvironment instance that will be used by the loader to compile the templates in the bundle to render them at runtime. Only optional when passing a renderContext, otherwise it's required.
renderContext	false	any	undefined	If different from undefined, enables the render at compile time behavior and serves as context for the rendering of the templates.