{"id":13417352,"url":"https://github.com/alexlafroscia/vite-plugin-handlebars","last_synced_at":"2025-03-31T11:05:52.360Z","repository":{"id":37097419,"uuid":"335656903","full_name":"alexlafroscia/vite-plugin-handlebars","owner":"alexlafroscia","description":"Vite support for Handlebars","archived":false,"fork":false,"pushed_at":"2024-02-19T20:12:16.000Z","size":1563,"stargazers_count":190,"open_issues_count":21,"forks_count":22,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-24T05:39:38.017Z","etag":null,"topics":["handlebars","vite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexlafroscia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-03T14:47:39.000Z","updated_at":"2025-03-07T10:48:20.000Z","dependencies_parsed_at":"2024-09-24T15:40:32.067Z","dependency_job_id":"8d15024f-d63f-4364-a4b8-ee5a00b3d363","html_url":"https://github.com/alexlafroscia/vite-plugin-handlebars","commit_stats":{"total_commits":213,"total_committers":5,"mean_commits":42.6,"dds":0.323943661971831,"last_synced_commit":"e53a7b5b1f398cf265b7f31d5b7da9e3c5383f5d"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexlafroscia%2Fvite-plugin-handlebars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexlafroscia%2Fvite-plugin-handlebars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexlafroscia%2Fvite-plugin-handlebars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexlafroscia%2Fvite-plugin-handlebars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexlafroscia","download_url":"https://codeload.github.com/alexlafroscia/vite-plugin-handlebars/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246457968,"owners_count":20780676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["handlebars","vite"],"created_at":"2024-07-30T22:00:35.666Z","updated_at":"2025-03-31T11:05:52.338Z","avatar_url":"https://github.com/alexlafroscia.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Plugins"],"sub_categories":["Framework-agnostic Plugins"],"readme":"# `vite-plugin-handlebars`\n\n\u003e Vite support for Handlebars\n\n## Why?\n\nI really like Vite as a simple static site bundler. It can handle bundling multiple HTML files, which is great, but lacks the ability out-of-the-box to share parts of those HTML files.\n\nWhile a JS framework like React or Vue could be used to solve this problem, this is heavy-handed for a simple site that could be completely pre-rendered without a JS run-time of any kind.\n\nHandlebars provides what we need to be able to stitch together multiple HTML files, interpolate variables, etc.\n\n## Installation\n\nStart by installing the package like you would any other\n\n```\nyarn add -D vite-plugin-handlebars\n```\n\nIt can then be added to your Vite configuration as a plugin:\n\n```javascript\n// vite.config.js\nimport handlebars from 'vite-plugin-handlebars';\n\nexport default {\n  plugins: [handlebars()],\n};\n```\n\nConfiguring the plugin is covered later in this guide.\n\n### Requirements\n\n- This plugin is intended to work with Vite 2\n- This plugin requires Node 14 or higher (due to usage of `fs/promises`)\n\n## Configuration\n\n### Defining Context\n\nIf you want to make use of [Handlebars Context](https://handlebarsjs.com/guide/#simple-expressions) to inject variables into your HTML file, you'll need to define their values in the `context` object passed to the `handlebars` plugin:\n\n```html\n\u003c!-- index.html --\u003e\n\u003ch1\u003e{{title}}\u003c/h1\u003e\n```\n\n```javascript\n// vite.config.js\nimport handlebars from 'vite-plugin-handlebars';\n\nexport default {\n  plugins: [\n    handlebars({\n      context: {\n        title: 'Hello, world!',\n      },\n    }),\n  ],\n};\n```\n\nThis will result in `\u003ch1\u003eHello, world!\u003c/h1\u003e` in your output HTML file.\n\nYou can also provide a (asynchronous) function, either as the `context` key or any of the keys within the object, which will be evaluated to create the value that will be made available inside your page. This function is called with an identifier parameter based on the HTML file path which makes it possible to provide unique data to each HTML page in a multipage application setup.\n\n```javascript\n// vite.config.js\nimport handlebars from 'vite-plugin-handlebars';\n\nconst pageData = {\n  '/index.html': {\n    title: 'Main Page',\n  },\n  '/nested/subpage.html': {\n    title: 'Sub Page',\n  },\n};\n\nexport default {\n  plugins: [\n    handlebars({\n      context(pagePath) {\n        return pageData[pagePath];\n      },\n    }),\n  ],\n};\n```\n\n### Partials\n\nIf you want to make use of [partials](https://handlebarsjs.com/guide/partials.html#basic-partials) in your HTML files, you _must_ define the `partialDirectory` option for the `handlebars` plugin.\n\n```javascript\n// vite.config.js\nimport { resolve } from 'path';\nimport handlebars from 'vite-plugin-handlebars';\n\nexport default {\n  plugins: [\n    handlebars({\n      partialDirectory: resolve(__dirname, 'partials'),\n    }),\n  ],\n};\n```\n\nIf you want to use multiple partial folders, an array can be submitted.\n\nEach file in these directories (`.html` or `.hbs`) will become registered as a partial. The name of the file is used to invoke it. So, with the above configuration and the following files:\n\n```html\n\u003c!-- partials/header.hbs --\u003e\n\u003cheader\u003e\u003ca href=\"/\"\u003eMy Website\u003c/a\u003e\u003c/header\u003e\n```\n\n```html\n\u003c!-- index.html --\u003e\n{{\u003e header }}\n\n\u003ch1\u003eThe Main Page\u003c/h1\u003e\n```\n\nYour output website content would become:\n\n```html\n\u003cheader\u003e\u003ca href=\"/\"\u003eMy Website\u003c/a\u003e\u003c/header\u003e\n\n\u003ch1\u003eThe Main Page\u003c/h1\u003e\n```\n\nMake sure to review the [quirks section](#quirks) for information on potentially-unexpected behavior.\n\n### Helpers\n\nCustom helpers can be registered using the `helpers` configuration option:\n\n```js\n// vite.config.js\nimport { resolve } from 'path';\nimport handlebars from 'vite-plugin-handlebars';\n\nexport default {\n  plugins: [\n    handlebars({\n      helpers: {\n        capitalize: (value) =\u003e value.toUpperCase(),\n      },\n    }),\n  ],\n};\n```\n\nFor more information on helpers, see [the Handlebars documentation](https://handlebarsjs.com/api-reference/helpers.html).\n\n### Other Handlebars Options\n\nAll other Handlebars configuration options can also be passed through.\n\n- [`compileOptions`](https://handlebarsjs.com/api-reference/compilation.html#pre-compilation) can be used to alter the compilation step\n- [`runtimeOptions`](https://handlebarsjs.com/api-reference/runtime-options.html#options-to-control-prototype-access) can be used to alter the rendering step\n\nEach of these can also be passed through to the `handlebars` plugin:\n\n```javascript\n// vite.config.js\nimport handlebars from 'vite-plugin-handlebars';\n\nexport default {\n  plugins: [\n    handlebars({\n      compileOptions: {\n        // Example config option: avoid auto-indenting partials\n        preventIndent: true,\n      },\n      runtimeOptions: {\n        // Example config option: define custom private @variables\n        data: {\n          foo: 'bar',\n        },\n      },\n    }),\n  ],\n};\n```\n\n### Disabling Browser Refresh on Partial Change\n\nBy default, any time a partial changes, your browser window will be full reloaded. If you want to disable this behavior, you can set `reloadOnPartialChange` to `false`:\n\n```javascript\n// vite.config.js\nimport handlebars from 'vite-plugin-handlebars';\n\nexport default {\n  plugins: [\n    handlebars({\n      reloadOnPartialChange: false,\n    }),\n  ],\n};\n```\n\n## Built-In Helpers\n\n### `resolve-from-root`\n\nYou can resolve a file path relative to the Vite root using the `resolve-from-root` helper. This assists with injecting other files, like linking to a CSS file, within a partial.\n\n```hbs\n\u003c!-- partials/head.hbs --\u003e\n\u003clink rel='stylesheet' href='{{resolve-from-root \"css/global.css\"}}' /\u003e\n```\n\n## Quirks\n\n- Assets included in a partial using a relative path will _probably_ not work how you would first expect; the relative path is left alone, making it relative to the _output_ file, not the partial itself. It's recommended that you use the `resolve-from-root` helper to ensure paths are resolved from the project root, rather than relative to a particular file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexlafroscia%2Fvite-plugin-handlebars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexlafroscia%2Fvite-plugin-handlebars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexlafroscia%2Fvite-plugin-handlebars/lists"}