Home

Awesome

@yoichiro/vite-plugin-handlebars

This is a plugin that provides convenient features for using Handlebars with Vite.

Features

With this plugin, the following features are enabled in projects using Vite:

Example of SPA

As an example of SPA, suppose you have the following Handlebars template file (templates/card.hbs):

<div class="card">
  <p>{{ message }}</p>
</div>

With this plugin, you can import and use card.hbs as follows:

import template from 'templates/card.hbs';

const card = template({ message: 'Hello, world!' });
const elem = document.getElementById('target');
elem.innerHTML = card;

Also, suppose you have the following partial file (templates/partials/footer.hbs):

<div class="footer">
  <p>Powered by Vite and Handlebars.</p>
</div>

Then, include it in the card.hbs file as follows:

<div class="card">
  <p>{{ message }}</p>
  {{> footer}}
</div>

This plugin automatically loads the footer.hbs file and includes it in the card.hbs file.

Example of MPA

As an example of MPA, suppose you have the following index file (index.html):

<!DOCTYPE html>
<html lang="en">
<head>...</head>
<body>
    <p>{{ upper-case message }}</p>
    {{> footer}}
</body>
</html>

Also, suppose you have the following partial file (partials/footer.hbs):

<div class="footer">
  <p>Powered by Vite and Handlebars.</p>
</div>

Next, create the following vite.config.js file:

import { defineConfig } from 'vite';
import handlebarsPlugin from '@yoichiro/vite-plugin-handlebars';
import path from 'path';

export default defineConfig({
  plugins: [
    handlebarsPlugin({
      partialDirectoryPath: path.resolve(__dirname, 'partials'),
      transformIndexHtmlOptions: {
        context: () => {
          message: 'Hello, world!'
        },
        helpers: {
          'upper-case': (str: string) => str.toUpperCase(),
        },
      },
    })
  ]
});

As a result, the index.html file generated by running vite build will be as follows:

<!DOCTYPE html>
<html lang="en">
<head>...</head>
<body>
    <p>HELLO, WORLD!</p>
    <div class="footer">
      <p>Powered by Vite and Handlebars.</p>
    </div>
</body>
</html>

Installation

npm install @yoichiro/vite-plugin-handlebars --save-dev

Usage

To use this plugin in your Vite project, modify your vite.config.js or vite.config.ts file as follows:

// vite.config.js
import { defineConfig } from 'vite';
import handlebarsPlugin from '@yoichiro/vite-plugin-handlebars';

export default defineConfig({
  plugins: [
    handlebarsPlugin()
  ]
});

Options

This plugin can be configured with the following options:

These options can be specified as arguments to the handlebarsPlugin function. Below is an example that specifies handlebars as the template file extension and templates/partials as the directory containing partial template files.

// vite.config.js
import { defineConfig } from 'vite';
import handlebarsPlugin from '@yoichiro/vite-plugin-handlebars';
import path from 'path';

export default defineConfig({
  plugins: [
    handlebarsPlugin({
      templateFileExtension: 'handlebars',
      partialDirectoryPath: path.resolve(__dirname, 'templates', 'partials'),
      optimizePartialRegistration: true,
    })
  ]
});

The compileOptions are the various options applied when compiling template files in Handlebars. For details on each option, please refer to the Handlebars documentation.

When building with the Vite build or preview command, if you want to treat the index file (typically the index.html file) as a Handlebars template file and perform a transformation, specify the transformIndexHtmlOptions option. This option is an object that can contain the following properties:

If you want to transform the index file as a Handlebars template file without registering any context or helpers, specify an empty object as shown below.

// vite.config.js
import { defineConfig } from 'vite';
import handlebarsPlugin from '@yoichiro/vite-plugin-handlebars';
import path from 'path';

export default defineConfig({
  plugins: [
    handlebarsPlugin({
      templateFileExtension: 'handlebars',
      partialDirectoryPath: path.resolve(__dirname, 'templates', 'partials'),
      transformIndexHtmlOptions: {},
    })
  ]
});

Please note that the context option and helpers option specified in the transformIndexHtmlOptions are only applied during Vite's build process. They are not applied when importing Handlebars template files using import in .ts or .js files.

Additionally, when there are multiple index files in an MPA, use rollupOptions as shown below.

export default defineConfig({
  ...
  build: {
    rollupOptions: {
      input: {
        index: resolve(__dirname, 'index.html'),
        alternative: resolve(__dirname, 'alternative.html'),
      },
    },
  },
});

Samples

The integration directory contains a sample Vite project using this plugin. You can start this sample project by following these steps:

$ git clone https://github.com/yoichiro/vite-plugin-handlebars.git
$ cd vite-plugin-handlebars
$ npm install
$ npm run integration-preview

After the development server starts, please access http://localhost:5173 in your web browser.

Contributing

If you would like to contribute to this plugin, please follow these steps:

  1. Register an issue and describe what you would like to contribute.
  2. When you want to contribute by sending code, fork this repository, create a new branch, make your code changes, and submit a pull request.

License

For the license of this plugin, please refer to the LICENSE file.