File Include Webpack Plugin

A webpack plugin to include files using @@include syntax in html files, like gulp-file-include.

Installation

npm install --save-dev file-include-webpack-plugin

Note: This plugin requires Webpack 4.0.0 and above.

Usage

Webpack Config

Update plugins array in webpack.config.js

// import the plugin
const FileIncludeWebpackPlugin = require('file-include-webpack-plugin')

module.exports = {
  plugins: [
    new FileIncludeWebpackPlugin(
      {
        source: './src/templates', // relative path to your templates
        replace: [{
          regex: /\[\[FILE_VERSION]]/, // additional things to replace
          to: 'v=1.0.0',
        }],
      },
    )
  ]
}

How to pass html beautifier options

This plugin uses js-beautify for html beautification.

Use the config htmlBeautifyOptions to pass custom beautifier options. Refer to the package js-beautify to know more about the possible options.

Example config -

module.exports = {
  plugins: [
    new FileIncludeWebpackPlugin(
      {
        source: './src/templates',
        htmlBeautifyOptions: {
          'indent_size': 2
        }
      },
    )
  ]
}

How to change the output destination?

destination is an optional configuration, which is relative to output.path in webpack configuration.

module.exports = {
  plugins: [
    new FileIncludeWebpackPlugin(
      {
        source: './src/templates',
        destination: '../html',
      },
    )
  ]
}

Template Syntax

Add templates using @@ as shown below

@@inlude('../partials/header.html')   //relative path to partials from parent html

Include partials inside partials

With release v1.3.5, you can now include partials inside other partials. Use relative path w.r.t. including parent.

Passing arguments to partials

file-include-webpack-plugin allows passing substitutable arguments as a key-value JSON to the included files.

@@inlude('../partials/header.html', {
  "arg1": "value1",
  "arg2": "value2",
  "arg3": {
    "arg3a": "value3a",
    "arg3b": "value3b",
  },
  ...
})

Access the arguments in partials as @@arg1, @@arg2, @@arg3.arg3a, and so on. Refer example for complete reference.

Note:

• Currently, only supports value substitution. Passing an array or an object as value, may not give intended output.
• Please raise an issue for any new requirements.

Working with example

Switch to example directory and run npm install. Running npm run build post installation will now generate a directory dist with all the partials included in templates.

Run npm run watch to run webpack in watch mode, to continue developing and re-compiling webpack on every change.

Or, run npm run dev to launch webpack dev server.