Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sagold/handlebars-webpack-plugin

Renders your html-template at build time
https://github.com/sagold/handlebars-webpack-plugin

compile handlebars npm-package server-side webpack-plugin

Last synced: about 19 hours ago
JSON representation

Renders your html-template at build time

Awesome Lists containing this project

README 

        
handlebars webpack plugin



> Server-side template rendering using [Handlebars](http://handlebarsjs.com/).



`npm install handlebars-webpack-plugin --save-dev`



## Usage



In your webpack config register and setup the handlebars plugin



```javascript

const path = require("path");

const HandlebarsPlugin = require("handlebars-webpack-plugin");



const webpackConfig = {



  plugins: [



    new HandlebarsPlugin({

      // path to hbs entry file(s). Also supports nested directories if write path.join(process.cwd(), "app", "src", "**", "*.hbs"),

      entry: path.join(process.cwd(), "app", "src", "*.hbs"),

      // output path and filename(s). This should lie within the webpacks output-folder

      // if ommited, the input filepath stripped of its extension will be used

      output: path.join(process.cwd(), "build", "[name].html"),

      // you can also add a [path] variable, which will emit the files with their relative path, like

      // output: path.join(process.cwd(), "build", [path], "[name].html"),

      

      // data passed to main hbs template: `main-template(data)`

      data: require("./app/data/project.json"),

      // or add it as filepath to rebuild data on change using webpack-dev-server

      data: path.join(__dirname, "app/data/project.json"),



      // globbed path to partials, where folder/filename is unique

      partials: [

        path.join(process.cwd(), "app", "src", "components", "*", "*.hbs")

      ],



      // register custom helpers. May be either a function or a glob-pattern

      helpers: {

        nameOfHbsHelper: Function.prototype,

        projectHelpers: path.join(process.cwd(), "app", "helpers", "*.helper.js")

      },



      // hooks

      // getTargetFilepath: function (filepath, outputTemplate) {},

      // getPartialId: function (filePath) {}

      onBeforeSetup: function (Handlebars) {},

      onBeforeAddPartials: function (Handlebars, partialsMap) {},

      onBeforeCompile: function (Handlebars, templateContent) {},

      onBeforeRender: function (Handlebars, data, filename) {},

      onBeforeSave: function (Handlebars, resultHtml, filename) {},

      onDone: function (Handlebars, filename) {}

    })

  ]

};

```



Partial ids are registered by `parentFolder/filename` (without file extensions)



Use handlebars in your main and partials like, i.e.



```hbs



  {{> partialFolder/partialName}}



  {{> header/header title="page title"}}



  {{> partial/content}}



```



## Options



### target filepaths



Per default, the generated filepath of the html-results is defined by the `output`-property in the plugin-options. To changed the output folder and name, you can pass your custom filepath-helper to the plugin-options like



```javascript

{

    /**

     * Modify the default output path of each entry-template

     * @param {String} filepath     - the source of the template

     * @param {String} outputTemplate - the filepath template defined in `output`

     * @param {String} rootFolder   - the filepaths rootFolder

     * @return {String} final path, where the rendered html-file should be saved

     */

    getTargetFilepath: function getTargetFilepath(filepath, outputTemplate, rootFolder) {

        const fileName = path.basename(filepath).replace(path.extname(filepath), "");

        return outputTemplate.replace("[name]", fileName);

    };

}

```



You can find the default implementation in [utils/getTargetFilepath](./utils/getTargetFilepath.js).



### partial ids



Per default, partials are identified with `folder/filename` in a hbs-template. e.g. a file in `app/partials/page/header.hbs` will be registered under `page/header` and can be included with



```hbs

{{> page/header title="page title"}}

```



To change the partial's id you can pass a custom partial-generator to the plugin-options like



```javascript

{

    /**

     * Modify the hbs partial-id created for a loaded partial

     * @param {String} filePath   - filePath to the loaded partial

     * @return {String} hbs-partialId, per default folder/partialName is used

     */

    getPartialId: function (filePath) {

        return filePath.match(/\/([^/]+\/[^/]+)\.[^.]+$/).pop();

    }

}

```



### Html Webpack Plugin



> Use the [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) to generate partials, that are

> dynamically registered to the handlebars-webpack-plugin



- the `HtmlWebpackPlugin` should be placed before the HandlebarsWebpackPlugin

- multiple HtmlWebpackPlugins may be used

- per default, the partials get registered to `html/`, i.e. a filename `/dist/partials/head.hbs` will be registered as `html/head` to handlebars



```js

plugins: [

   new HtmlWebpackPlugin({

    title: "Generic Head Title",

    // the template you want to use

    template: path.join(__dirname, "src", "generatedpartial", "head.hbs"),

    // the output file name

    filename: path.join(__dirname, "dist", "partials", "head.hbs"),

    inject: "head"

  }),



  new HandlebarsWebpackPlugin({



    htmlWebpackPlugin: {

      enabled: true, // register all partials from html-webpack-plugin, defaults to `false`

      prefix: "html", // where to look for htmlWebpackPlugin output. default is "html"

      HtmlWebpackPlugin // optionally: pass in HtmlWebpackPlugin if it cannot be resolved

    },



    entry: path.join(process.cwd(), "src", "hbs", "*.hbs"),

    output: path.join(process.cwd(), "dist", "[name].html"),



    partials: [

      path.join(process.cwd(), "html",/* <-- this should match htmlWebpackPlugin.prefix */ "*", "*.hbs"),

      path.join(process.cwd(), "src", "hbs", "*", "*.hbs")

    ]

  })

]

```



## Utilities



### Merging input-data



In case you have several json-files that need to be passed to handlebars-compilation, you can build this within your webpack-configuration file. A simple helper can be found in [utils/mergeJSON.js](./utils/mergeJSON.js), 

which finds all json files and build a dataObject with `{ :  }`. Example:



```js

const mergeJSON = require('handlebars-webpack-plugin/utils/mergeJSON');

const projectData = mergeJSON(path.join(__dirname, "data/**/*.json"));

// ...

new HandlebarsPlugin({

    // ...

    data: projectData

});

```



For custom merge behaviour you can add your own merge-helper, following the implementation from [utils/mergeJSON.js](./utils/mergeJSON.js).



## Contributors