Html-webpack-partials-injector-plugin NPM

html-webpack-partials-injector-plugin

Why use it?

This plugin is meant to be used in conjunction with the html-webpack-plugin and custom templates. It modifies the template configured under html-webpack-plugin options to make dynamic partial injections possible.

You would use it, if you want to dynamically inject partials in your custom template configured under html-webpack-plugin options. For example you have a template.html which serves as the base for all the pages in your website. The template contains only stuff that stays the same on every page, like header, sidebar, footer, etc.

Then you want to include content in every page that differs between pages, usually the body part. You can now specify the respective content and include it as a partial.

Requirements

html-webpack-plugin v3.2

Getting Started

To begin, you'll need to install html-webpack-partials-injector-plugin:

npm  install html-webpack-partials-injector-plugin --save-dev
yarn add html-webpack-partials-injector-plugin --dev

Then add the plugin to your webpack config.

The plugin has to be added once before all html-webpack-plugin's.

For example:

webpack.config.js

The plugin has to be added once before all html-webpack-plugin's.

const HtmlWebpackPartialsInjectorPlugin = require('html-webpack-partials-injector-plugin')

module.exports = {
  plugins: [
      new HtmlWebpackPartialsInjectorPlugin(), // <-- has to be added once before all html-webpack-plugin(s)
      new HtmlWebpackPlugin({
          template: './src/pages/layout/layout.ejs',
          'title': 'Index-Page',
          partials: [{
              path: path.resolve('./src/partials/index/index-body.html'),
              location: 'main'
          }],
          inject: true,
          chunks: ['index'],
          filename: 'index.html'
      }),
  ]
}

Configure your partials first and run webpack via your preferred method.

Attention!

This plugin creates temporary files because it creates a modified copy of the template, specified in the options object of each html-webpack-plugin and only for those which have partials defined, others stay untouched.

The temporary template files get deleted at the end of the build, but if you stop the build in your IDE before the build completes, for example by pressing "Stop debugging" or ctrl + c the files will be presisted in your project folder where the original template resides!

The files will get deleted on next build.

As a precaution, to not check-in these temporary files, you can add *partials-injector-for-page* to your .gitignore file, just in case of.

Options

No options are required for the html-webpack-partials-injector-plugin itself.

Configuration

Reference a custom template under html-webpack-plugin options. You have to configure the partials you want to inject in the respective html-webpack-plugin options object. Therefore you add a partials property to the options object.

new HtmlWebpackPlugin({
    ...
    template: './src/pages/layout/layout.ejs', 
    partials: [{ // you can configure multiple partials here
        path: path.resolve('./src/partials/index/index-body.html'), 
        location: 'main',
        priority: 'high|low'  // (optional, default: low)
    }],
   inject: true,
   chunks: ['index'],
   filename: 'index.html'
}),

The partials property is an array of objects which must have a path and a location property. The priority property is optional.

path is the path to the partial you want to inject. location is the html-tag you want the partial to inject to, i.e. body,head, main, aside

priority: high|low high means, you want to inject the partial right after the opening tag. low (default) means, you want to inject the partial right before the closing tag.

Feature

By default you can inject parameters into the template by using the html-webpack-plugin. The html-webpack-partials-injector also enables you to use template parameters inside of your partials.

example-partial.html:

<p> I am a partial with a parameter: <%= htmlWebpackPlugin.options.yourparam %> </p>

and then in your html-webpack-plugin:

 new HtmlWebpackPlugin({
    template: './src/pages/layout/layout.ejs',
    title: 'YourTitleGoesHere', 
    yourparam : 'somevalue', <-- here you define your template|partial parameter as usual
    partials:[
       path: path.resolve('path/to/partial/example-partial.html'), <-- your partial 
       location: 'body' 
    ]
    ...

Examples

Also checkout the examples folder in this repository, which includes one example showing one way of using it.

webpack.config.js

...
entry: {
  index: './src/scripts/index-entry.js',
  about: './src/scripts/about-entry.js'
},
output: {
  filename: '[name].bundle.js',
  path: path.resolve(__dirname, 'dist'),
  chunkFilename: 'chunkFilename.[name].bundle.js'
},
plugins: [
  new HtmlWebpackPartialsInjectorPlugin(),
  new HtmlWebpackPlugin({
      template: './src/pages/layout/layout.ejs',
      'title': 'Index-Page',
      partials: [{
          path: path.resolve('./src/partials/index/index-body.html'),
          location: 'main'
      },
      {
          path: path.resolve('./src/partials/another-partial.html'),
          location: 'head',
          priority:'high'
      }],
      inject: true,
      chunks: ['index'],
      filename: 'index.html'
  }),
  new HtmlWebpackPlugin({
      template: './src/pages/layout/layout.ejs',
      title: 'YourTitleGoesHere',
      partials: [{
          path: path.resolve('./src/partials/about/about-body.html'),
          location: 'main'
      }],
      inject: true,
      chunks: ['about'],
      filename: 'about.html'
  }),
...

and the template file, in this example: layout.ejs:

<!DOCTYPE html>
<html lang="en" class="custom-theme">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title><%= htmlWebpackPlugin.options.title %></title>     
    <meta name="theme-color" content="#26C6DA" />
    <link rel="apple-touch-icon" href="${require('../../icons/icon.png').default}">
</head>

<body>
    <div class="main">
        <header>
            ${require('../../partials/header.html')}
        </header>
        <aside>
            ${require('../../partials/nav.html')}
        </aside>
        <div class="content-page">
            <main>
                <!-- body gets injected by the html-webpack.partials-injector-plugin -->
            </main>
        </div>
    </div>
    ${require('../../partials/settings.html')}

</body>

</html>