https://github.com/yoichiro/vite-plugin-handlebars
This is a plugin that provides convenient features for using Handlebars with Vite.
https://github.com/yoichiro/vite-plugin-handlebars
Last synced: 4 months ago
JSON representation
This is a plugin that provides convenient features for using Handlebars with Vite.
- Host: GitHub
- URL: https://github.com/yoichiro/vite-plugin-handlebars
- Owner: yoichiro
- License: mit
- Created: 2024-06-28T02:30:27.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-09-30T11:14:24.000Z (7 months ago)
- Last Synced: 2024-11-19T03:07:16.710Z (5 months ago)
- Language: TypeScript
- Homepage:
- Size: 48.8 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-vite - @yoichiro/vite-plugin-handlebars - Import of Handlebars templates `.hbs` as ES Modules. (Plugins / Framework-agnostic Plugins)
- trackawesomelist - @yoichiro/vite-plugin-handlebars (⭐1) - Import of Handlebars templates `.hbs` as ES Modules. (Recently Updated / [Sep 04, 2024](/content/2024/09/04/README.md))
- fucking-awesome-vite - @yoichiro/vite-plugin-handlebars - Import of Handlebars templates `.hbs` as ES Modules. (Plugins / Framework-agnostic Plugins)
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`):
```html
{{ message }}
```
With this plugin, you can import and use `card.hbs` as follows:
```javascript
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`):
```html
```
Then, include it in the `card.hbs` file as follows:
```html
{{ message }}
{{> footer}}
```
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`):
```html
...
{{ upper-case message }}
{{> footer}}
```
Also, suppose you have the following partial file (`partials/footer.hbs`):
```html
```
Next, create the following `vite.config.js` file:
```javascript
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:
```html
...
HELLO, WORLD!
```
# Installation
```shell
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:
```javascript
// 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.
```javascript
// 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](https://handlebarsjs.com/api-reference/compilation.html#handlebars-compile-template-options).
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.
```javascript
// 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.
```javascript
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:
```sh
$ 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](https://github.com/yoichiro/vite-plugin-handlebars-import/blob/main/LICENSE) file.