{"id":13605319,"url":"https://github.com/iamspark1e/vite-plugin-auto-mpa-html","last_synced_at":"2025-07-25T05:30:28.250Z","repository":{"id":94185039,"uuid":"607816367","full_name":"iamspark1e/vite-plugin-auto-mpa-html","owner":"iamspark1e","description":"A file directory-based automated multi-page build plugin that supports HTML templates using Handlebars. 基于文件目录的Vite自动化多页面构建插件，支持使用 Handlebars 的 HTML 模板。","archived":false,"fork":false,"pushed_at":"2025-07-22T10:56:27.000Z","size":649,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-22T12:31:07.523Z","etag":null,"topics":["handlebars","handlebarsjs","mpa","react","vite","vite-plugin","vue"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamspark1e.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2023-02-28T18:28:19.000Z","updated_at":"2025-07-22T10:56:26.000Z","dependencies_parsed_at":"2024-03-08T10:49:43.216Z","dependency_job_id":"5970a362-58f8-46af-988a-9c00e47dfafc","html_url":"https://github.com/iamspark1e/vite-plugin-auto-mpa-html","commit_stats":{"total_commits":143,"total_committers":3,"mean_commits":"47.666666666666664","dds":"0.43356643356643354","last_synced_commit":"e35897ac43c3c19e9847420a079d5773d95fdc23"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/iamspark1e/vite-plugin-auto-mpa-html","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamspark1e%2Fvite-plugin-auto-mpa-html","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamspark1e%2Fvite-plugin-auto-mpa-html/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamspark1e%2Fvite-plugin-auto-mpa-html/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamspark1e%2Fvite-plugin-auto-mpa-html/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamspark1e","download_url":"https://codeload.github.com/iamspark1e/vite-plugin-auto-mpa-html/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamspark1e%2Fvite-plugin-auto-mpa-html/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266516331,"owners_count":23941397,"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","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","handlebarsjs","mpa","react","vite","vite-plugin","vue"],"created_at":"2024-08-01T19:00:57.324Z","updated_at":"2025-07-25T05:30:27.662Z","avatar_url":"https://github.com/iamspark1e.png","language":"TypeScript","funding_links":[],"categories":["Plugins"],"sub_categories":["Framework-agnostic Plugins"],"readme":"\u003ch1 align='center'\u003evite-plugin-auto-mpa-html\u003c/h1\u003e\n\n\u003cp align='center'\u003e\n  \u003ca href=\"https://codecov.io/gh/iamspark1e/vite-plugin-auto-mpa-html\" \u003e\u003cimg src=\"https://codecov.io/gh/iamspark1e/vite-plugin-auto-mpa-html/branch/main/graph/badge.svg?token=xW4J4R4P7b\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/vite-plugin-auto-mpa-html\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/vite-plugin-auto-mpa-html\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/vite-plugin-auto-mpa-html\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/vite-plugin-auto-mpa-html\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Vite-%5E2.9.15%7C%5E3.2.3%7C4%7C5-brightgreen\" /\u003e\n\u003c/p\u003e\n\n\u003cp align='center'\u003eEnglish | \u003ca href=\"./README.zh.md\"\u003e中文文档\u003c/a\u003e\u003c/p\u003e\n\u003cbr /\u003e\n\u003cp align='center'\u003eA file directory-based automated multi-page Vite plugin that supports HTML templates using Handlebars.\u003c/p\u003e\n\u003cp align='center'\u003e基于文件目录的Vite自动化多页面构建插件，支持使用 Handlebars 的 HTML 模板。\u003c/p\u003e\n\u003cbr /\u003e\n\n## Quick Start\n\n```bash\nnpm i vite-plugin-auto-mpa-html@latest -D # Or yarn/pnpm as you like\n```\n\nThen, add plugin to your `vite.config.(js/ts)`, like this,\n\n```javascript\nimport { defineConfig } from 'vite'\nimport react from '@vitejs/plugin-react'\nimport autoMpaHtmlPlugin from 'vite-plugin-auto-mpa-html'\n\n// https://vitejs.dev/config/\nexport default defineConfig({\n  plugins: [react(), autoMpaHtmlPlugin({\n    entryName: \"main.tsx\",\n    sharedData: {},\n    enableDevDirectory: true, // enable directory page will render an directory page at \"http://localhost:5173/\", if you have an index, it will not be affect.\n    renderEngineOption: {}\n  })],\n})\n```\n\nNow, focus on your __PAGES__, for example, a project like this,\n\n\u003e Using the official template of `react-ts`, copied page's assets to 2 pages, the \"index\" and the \"page2\"\n\n```\n.\n├── package.json\n├── package-lock.json\n├── public\n│   └── vite.svg\n├── src\n│   ├── index\n│   │   ├── App.css\n│   │   ├── App.tsx\n│   │   ├── assets\n│   │   │   └── react.svg\n│   │   ├── config.json\n│   │   ├── index.css\n│   │   ├── main.tsx\n│   │   └── vite-env.d.ts\n│   └── page2\n│       ├── App.css\n│       ├── App.tsx\n│       ├── assets\n│       │   └── react.svg\n│       ├── config.json\n│       ├── index.css\n│       ├── main.tsx\n│       └── vite-env.d.ts\n├── templates\n│   └── index.html\n├── tsconfig.json\n├── tsconfig.node.json\n└── vite.config.ts\n```\n\n\u003e How to generate a beautiful tree like this? Run `tree -I \"node_modules|dist\" \u003e folders.txt` with tree package!\n\nManually create a `config.json` in the subdirectory of the page, with these content,\n\n```json\n{\n    \"template\": \"../../templates/index.html\", // Using relative path from v1\n    \"data\": {\n        \"title\": \"This is page 2\",\n        \"description\": \"page 22222222\",\n        \"keywords\": \"2\"\n    }\n}\n```\n\n\u003e We put all pages into different folders under `src`, some additional config should be put into `vite.config.js`\n\u003e\n\u003e ```javascript\n\u003e export default defineConfig({\n\u003e   root: \"src\",\n\u003e   base: \"\",\n\u003e   build: {\n\u003e     outDir: \"../dist\",\n\u003e     emptyOutDir: true,\n\u003e   }\n\u003e })\n\u003e ```\n\nFinished, everything is ready, run `npm run build` to see what is built with `vite-plugin-auto-mpa-html`.\n\n\u003e A temporary `index.html` will be generated to every entry, just beside your entry file, such as `main.jsx` or `main.js`, PLEASE take care!\n\n## Plugin Options\n\n```typescript\n{\n  /**\n   * Render a directory page in development (as the old key `enableDirectoryPage`)\n   * @default true\n   */\n  enableDevDirectory?: boolean\n  /**\n   * Top-level data, which will be shared to every entry during Handlebars render.\n   * @default {}\n   */\n  sharedData?: object\n  /**\n   * Render engine options, currently using Handlebars\n   * @see {@link https://handlebarsjs.com/api-reference/compilation.html}\n   * @default {}\n   */\n  renderEngineOption?: object\n  /**\n   * Entries of your multi-entry application, for example, `main.js` for Vue, and `main.jsx` for React.\n   * @default \"main.js\"\n   */\n  entryName: string\n  /**\n   * Config file name, after v1.1.0 you can use an ESM style exported config module, .ts is not supported yet.\n   * @default \"config.json\"\n   */\n  configName?: string\n  /**\n   * Experimental features for plugin, using at your own risk!\n   */\n  experimental?: {\n    /**\n     * Re-define template name, if you want to put the HTML to the parent folder of \"entry\", you can use `.html` to directly use entry path as HTML path.\n     * [NOTICE] When `customTemplateName` equals \".html\" (which means you want to reduce folder levels), it's NOT allowed to put entry files directly under root folder.\n     */\n    customTemplateName?: string\n    /**\n     * Config the asset name of root's entry file, default value is \"_root\"\n     */\n    rootEntryDistName?: string\n  }\n}\n```\n\n## Page Config Option\n\n```typescript\n{\n  /**\n   * The RELATIVE path of your template\n   * @required\n   */\n  template: string\n  /**\n   * Handlebars render data in this entry, which will be assigned with global `sharedData`\n   * @default {}\n   */\n  data?: object\n}\n```\n\nIf you need to dynamically control the page configuration used during compilation for each page based on some external variables, you can also modify the `configName` to a \".js\" file and export a default configuration in the file.\n\n```javascript\n// After v1.1.0, you can use `pageConfigGenerator` to dynamically set page config.\nimport { pageConfigGenerator } from 'vite-plugin-auto-mpa-html'\n\n// pageConfigGenerator accepts direct cofig object, function, and even Promise.\nexport default pageConfigGenerator({\n  \"template\": \"../../template/index.html\"\n})\n```\n\n### Conditional page configuration\n\nWe have an option called `sharedData` cross pages, so you can inject the variables you need, then read them in page's config (or directly use in Handlebars templates), like this,\n\n```javascript\nimport { pageConfigGenerator } from 'vite-plugin-auto-mpa-html'\n\n// `pageConfigGenerator` is not required, but it can provide TypeScript reference.\nexport default pageConfigGenerator((opt) =\u003e {\n  console.log(opt.sharedData);\n  return {\n    \"template\": \"../template/index.html\",\n    data: {\n      isProd: opt.sharedData.isProd\n    }\n  }\n})\n\n// If you prefer to use JSDoc, you can also introduce types as shown below.\n/** @type {import('vite-plugin-auto-mpa-html').PageConfigGeneratorTypeExport} */\n/** @param {import('vite-plugin-auto-mpa-html').PageConfigOption} opt  */\n```\n\n## Limitation\n\n- Nested folder is __SUPPORTED__ from v1, but will generate a temporary `index.html` besides your entry file.\n\n- Env files is only supported in root folder (same level as `vite.config.js`), env-per-entry is __NOT SUPPORTED__.\n\n- When `experimental.customTemplateName` equals \".html\" (which means you want to reduce folder levels), it's NOT allowed to put entry files directly under root folder.\n\n- Auto restart when page's config changed is not originally supported by this plugin, but you can use [vite-plugin-restart]() which is maintained by @antfu, and add config like this,\n\n```javascript\nViteRestart({\n  restart: [\n    'config.[jt]s', // your configuration file name\n  ]\n})\n```\n\n## Vite native features\n\n- [x] v4.2+ HTML Env Replacement\n\n## Build Setup\n\n```bash\n# It's simple, just clone, install, and build!\ngit clone https://github.com/iamspark1e/vite-plugin-auto-mpa-html.git\ncd vite-plugin-auto-mpa-html\nnpm install # or any node package manager you like\n# npm run test # I'd suggest to run a fully test before commit.\nnpm run build\n```\n\n## Similar function plug-ins\n\nI'm not familar with vite plugin development, so I've read some plugins' awesome code. Some ideas and my needs was added during development. There are some other plugins may solve your problems or meet your needs, I also suggest these,\n\n- [vite-plugin-mpa](https://github.com/IndexXuan/vite-plugin-mpa)\n- [vite-plugin-mp](https://github.com/zhuweiyou/vite-plugin-mp)\n- [vite-plugin-mpa-plus](https://github.com/yzydeveloper/vite-plugin-mpa-plus)\n- [vite-plugin-html-template-mpa](https://github.com/Miofly/vite-plugin-html-template-mpa)\n- [vite-plugin-virtual-mpa](https://github.com/emosheeep/vite-plugin-virtual-mpa)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamspark1e%2Fvite-plugin-auto-mpa-html","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamspark1e%2Fvite-plugin-auto-mpa-html","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamspark1e%2Fvite-plugin-auto-mpa-html/lists"}