npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@yoichiro/vite-plugin-handlebars

v1.4.0

Published

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

Downloads

989

Readme

@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:

  • Handlebars template files can be imported within .ts or .js files, which is particularly useful in SPA (Single Page Architecture).
  • During the build process, index files is processed as a Handlebars template file. This feature is especially useful in MPA (Multi Page Architecture).

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:

  • templateFileExtension (string) - Specifies the extension of Handlebars template files. Defaults to hbs if omitted.
  • partialDirectoryPath (string) - Specifies the path to the directory containing partial template files to be included in Handlebars template files. If omitted, partial template files are not registered.
  • optimizePartialRegistration (boolean) - Set to true to optimize the partial registration. This option is effective only when partialsDirectoryPath is set. If omitted, the plugin does not optimize the partial registration. If true, the plugin does not register the partials that are already registered.
  • compileOptions (object) - Specifies the options to be passed to the Handlebars compiler. If omitted, the default options are used.
  • transformIndexHtmlOptions (object) - This is an option to specify when treating the index file as a Handlebars template file during the Vite build process. If this option is not specified, the index file will not be transformed.

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:

  • context (object or function) - Specifies the context object to be passed to the Handlebars template file. If a function is specified, the function is called and the return value is used as the context object.
  • helpers (object) - Specifies the helper functions to be passed to the Handlebars template file.

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.