This is a plugin that provides convenient features for using Handlebars with Vite.
With this plugin, the following features are enabled in projects using Vite:
- Handlebars template files can be imported within
.tsor.jsfiles, 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).
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.
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>npm install @yoichiro/vite-plugin-handlebars --save-devTo 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()
]
});This plugin can be configured with the following options:
templateFileExtension(string) - Specifies the extension of Handlebars template files. Defaults tohbsif 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 whenpartialsDirectoryPathis 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'),
},
},
},
});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-previewAfter the development server starts, please access http://localhost:5173 in your web browser.
If you would like to contribute to this plugin, please follow these steps:
- Register an issue and describe what you would like to contribute.
- When you want to contribute by sending code, fork this repository, create a new branch, make your code changes, and submit a pull request.
For the license of this plugin, please refer to the LICENSE file.