vite-plugin-auto-mpa-html
v1.4.1
Published
A file directory-based automated multi-page Vite plugin that supports HTML templates using Handlebars.
Readme
兼容性
当前版本支持 Node.js 20.19+ 或 22.12+ 环境中的 Vite 4.2 至 Vite 8。兼容性 CI 会将插件打包后安装到隔离项目,并针对每个受支持 Vite 主版本的最新版本验证生产构建和开发服务器。
快速使用
npm i vite-plugin-auto-mpa-html@latest -D # Or yarn/pnpm as you like安装完成后,在vite.config.(js/ts)里加入插件,
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import autoMpaHtmlPlugin from 'vite-plugin-auto-mpa-html'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react(), autoMpaHtmlPlugin({
entryName: "main.tsx",
sharedData: {},
enableDevDirectory: true, // 在dev环境下临时渲染一个目录页面
outputStructure: "page", // 可选:生产构建按页面目录组织资源
})],
})现在回到项目目录下,以下面这个项目结构为例:
这是一个基于官方模板生成的
react-ts项目,index和page2是两个需要独立生成的HTML入口
.
├── package.json
├── package-lock.json
├── public
│ └── vite.svg
├── src
│ ├── index
│ │ ├── App.css
│ │ ├── App.tsx
│ │ ├── assets
│ │ │ └── react.svg
│ │ ├── config.json
│ │ ├── index.css
│ │ ├── main.tsx
│ │ └── vite-env.d.ts
│ └── page2
│ ├── App.css
│ ├── App.tsx
│ ├── assets
│ │ └── react.svg
│ ├── config.json
│ ├── index.css
│ ├── main.tsx
│ └── vite-env.d.ts
├── templates
│ └── index.html
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts上面的文件树使用了
tree -I "node_modules|dist" > folders.txt命令。
在每个入口子文件夹下,创建一个 config.json 文件,内容可以参考下面:
{
"template": "../../templates/index.html", // 从v1版本开始,使用相对路径
"data": {
"title": "This is page 2",
"description": "page 22222222",
"keywords": "2"
}
}由于我们的项目文件是创建在了
src的子文件夹下,所以vite.config.(js/ts)需要一些额外的配置来进行适配:export default defineConfig({ root: "src", // 避免生成的入口目录中含有src层级 base: "", build: { outDir: "../dist", // outDir默认值是与root的相对路径,root改为子目录后,dist需要生成到根目录下,因此需要配置 emptyOutDir: true, } })
完成配置,现在运行 npm run build,输出目录下就是使用本插件的效果了
提示,本插件在构建过程中会生成一个临时的
index.html在各个入口处,请注意避免冲突!
按页面组织构建产物
默认的 outputStructure: "flat" 保持 Vite 原有的资源布局。如果希望按 src 内的页面目录组织生产构建产物,可以启用:
autoMpaHtmlPlugin({
entryName: "main.tsx",
outputStructure: "page",
sharedDir: "shared",
})例如 src/page-a/main.tsx 和 src/group/page-b/main.tsx 会生成类似以下结构:
dist/
├── page-a/
│ ├── index.html
│ └── assets/
│ └── page-a-[hash].js
├── group/page-b/
│ ├── index.html
│ └── assets/
│ └── page-b-[hash].js
└── shared/
├── vendor-[hash].js
└── style-[hash].css插件会将能唯一归属于某个页面的 chunk 和具有源文件信息的资源放入该页面的 assets 目录。被多个页面使用、仅来自依赖包或 Rollup/Vite 无法可靠判断页面归属的文件会进入 sharedDir,不会为每个页面重复复制。Vite publicDir 中的文件仍按 Vite 的规则复制到 outDir,不参与分包。
开启该模式后,插件会接管 Rollup 的 entryFileNames、chunkFileNames 和 assetFileNames。其他 rollupOptions.output 配置仍会保留;暂不支持同时配置多个 Rollup output。
插件选项
{
/**
* 当调试时,生成一个目录页来方便访问 (旧为`enableDirectoryPage`)
* @default true
*/
enableDevDirectory?: boolean
/**
* 开启 history API fallback,用于开发环境下的 SPA 路由。
* 开启后,对于不存在的路径请求,如果 Accept 头包含 "text/html",会自动回退到最近的入口 HTML。
* @default false
*/
historyApiFallback?: boolean
/**
* 生产资源输出结构。"flat" 保持 Vite 默认布局,"page" 按页面目录组织。
* @default "flat"
*/
outputStructure?: "flat" | "page"
/**
* `outputStructure: "page"` 时,无法唯一归属某个页面的公共资源目录。
* 必须是 build.outDir 内的相对目录。
* @default "shared"
*/
sharedDir?: string
/**
* 顶层配置的共享数据,在渲染模板时会添加到每个入口处。
* @default {}
*/
sharedData?: object
/**
* 自定义模板引擎实现。提供后将覆盖内置的 Handlebars 引擎。
* 需实现 `TemplateEngine` 接口:
* `{ render(templateStr: string, data?: object, context?: TemplateRenderContext): string | Promise<string> }`
* @default undefined(使用内置 HandlebarsEngine)
*/
templateEngine?: TemplateEngine
/**
* 内置 Handlebars 引擎选项。Handlebars 是稳定的默认模板引擎。
* 当提供 `templateEngine` 时会被忽略。
* @see {@link https://handlebarsjs.com/zh/api-reference/compilation.html}
* @default {}
*/
handlebars?: {
compileOptions?: CompileOptions
runtimeOptions?: RuntimeOptions
helpers?: Record<string, HelperDelegate>
partials?: Record<string, string>
}
/**
* @deprecated 请使用 `handlebars.compileOptions` 和 `handlebars.runtimeOptions`。
*/
renderEngineOption?: {
compileOptions?: CompileOptions
runtimeOptions?: RuntimeOptions
}
/**
* 注册自定义 Handlebars helper。仅对内置 Handlebars 引擎生效。
* @deprecated 请使用 `handlebars.helpers`。
* @example { eq: (a, b) => a === b, upper: (str) => str.toUpperCase() }
*/
handlebarsHelpers?: Record<string, HelperDelegate>
/**
* 注册自定义 Handlebars partial。仅对内置 Handlebars 引擎生效。
* @deprecated 请使用 `handlebars.partials`。
* @example { header: '<header>{{title}}</header>', footer: '<footer>© 2024</footer>' }
*/
handlebarsPartials?: Record<string, string>
/**
* 多页项目的每个入口文件名, 例如, Vue项目一般为`main.js`, React项目一般为`main.jsx`.
* @default "main.js"
*/
entryName: string
/**
* 配置文件名,在版本v1.1.0后,你可以使用js导出一个es module来配置页面,TS暂不支持.
* @default "config.json"
*/
configName?: string
/**
* 实验性功能,使用风险自负!
* 注意:experimental 选项将来会被弃用,请使用顶级选项替代。
*/
experimental?: {
/**
* 重命名生成的HTML文件,默认为`index.html`(便于各类静态文件服务),但是你也可以命名为其他名字。
* *特殊的,如果你在此配置`.html`,那么HTML文件会置于入口文件的父级,并以入口文件名来命名。但是这个选项不能在你配置的root目录下生效,因为这样做生成的HTMl文件会置于outDir外,进而产生污染。
*/
customTemplateName?: string
/**
* 由于根目录(vite.config.js内配置的root选项)无法自动获取入口名称,默认使用_root作为其module名,你也可以通过这个配置项来自定义。
*/
rootEntryDistName?: string
/**
* @deprecated 请使用顶级 `enableDevDirectory` 选项替代。
*/
enableDevDirectory?: boolean
/**
* @deprecated 请使用顶级 `historyApiFallback` 选项替代。
*/
historyApiFallback?: boolean
}
}自定义模板引擎
Handlebars 是稳定的默认模板引擎。你可以通过实现 TemplateEngine 接口来提供自定义模板引擎;提供 templateEngine 后,它会覆盖内置 Handlebars 引擎,并忽略所有 handlebars、renderEngineOption、handlebarsHelpers 和 handlebarsPartials 选项。
import autoMpaHtmlPlugin from 'vite-plugin-auto-mpa-html'
import type { TemplateEngine } from 'vite-plugin-auto-mpa-html'
// 示例:使用 EJS 作为自定义引擎
import ejs from 'ejs'
autoMpaHtmlPlugin({
entryName: "main.tsx",
templateEngine: {
render: async (templateStr, data, context) => {
return ejs.render(templateStr, {
...data,
templatePath: context?.templatePath,
}, { async: true })
}
}
})第三个 context 参数包含当前入口、页面配置、已合并的插件选项和模板路径:
import type { TemplateEngine } from 'vite-plugin-auto-mpa-html'
const templateEngine: TemplateEngine = {
async render(templateStr, data, context) {
console.log(context?.entry.value)
console.log(context?.pageConfig.template)
console.log(context?.templatePath)
return templateStr
}
}Handlebars Helpers 与 Partials
推荐通过新的 handlebars 选项对象注册 helper、partial 和渲染选项:
autoMpaHtmlPlugin({
entryName: "main.tsx",
handlebars: {
compileOptions: {
noEscape: false,
},
runtimeOptions: {
allowProtoPropertiesByDefault: false,
},
helpers: {
eq: (a, b) => a === b,
formatDate: (date) => new Date(date).toLocaleDateString(),
upper: (str) => String(str).toUpperCase(),
},
partials: {
header: '<header><h1>{{title}}</h1></header>',
footer: '<footer>{{copyright}}</footer>',
},
},
sharedData: {
copyright: '2024 My Company'
}
})在模板中使用:
{{> header}}
<main>{{#if (eq page "home")}}Welcome!{{/if}}</main>
<p>Published: {{formatDate publishDate}}</p>
{{> footer}}旧的 renderEngineOption、handlebarsHelpers 和 handlebarsPartials 仍然兼容。新项目建议使用 handlebars;当新旧选项同时存在时,handlebars 中的值优先生效。
页面配置选项
这个文件是放置在每个入口目录的config.json
{
/**
* 本页应用模板的*相对*路径
* @optional 如果不提供,将使用默认模板
*/
template?: string
/**
* 本页Handlebars模板使用的渲染数据,会与顶层配置的sharedData进行合并
* @default {}
*/
data?: object
}如果你需要根据一些外部变量动态控制每一页在编译时使用的页面配置,你也可以通过修改configName为.js文件,并在文件中导出一个默认配置
// After v1.1.0, you can use `pageConfigGenerator` to dynamically set page config.
import { pageConfigGenerator } from 'vite-plugin-auto-mpa-html'
// pageConfigGenerator accepts direct cofig object, function, and even Promise.
export default pageConfigGenerator({
"template": "../../template/index.html"
})条件页面配置
借助跨页面的选项 sharedData ,您可以注入所需的变量,然后在页面配置中读取它们(或直接在 Handlebars 模板中使用),例如:
import { pageConfigGenerator } from 'vite-plugin-auto-mpa-html'
// `pageConfigGenerator` is not required, but it can provide TypeScript reference.
export default pageConfigGenerator((opt) => {
console.log(opt.sharedData);
return {
"template": "../template/index.html",
data: {
isProd: opt.sharedData.isProd
}
}
})
// 如果你更喜欢使用JSDoc的方式,你也可以像下面一样引入类型,这样可以不导入`pageConfigGenerator`
/** @type {import('vite-plugin-auto-mpa-html').PageConfigGeneratorTypeExport} */
/** @param {import('vite-plugin-auto-mpa-html').PageConfigOption} opt */URL 匹配行为
插件支持不带 .html 后缀的 URL 自动匹配:
| URL 模式 | 普通模式 | 实验模式 (.html) |
|----------|---------|-------------------|
| /subdir | 返回 subdir/index.html | 返回 subdir.html |
| /subdir/nested | 返回 subdir/nested/index.html | 返回 subdir/nested.html |
| /subdir/page (不存在) | 当 historyApiFallback: true 时回退到 subdir/index.html | 当 historyApiFallback: true 时回退到 subdir.html |
| /nonexistent | 透传 (next()) | 透传 (next()) |
History API Fallback
当启用 historyApiFallback 时,插件会自动将不匹配任何入口的路径回退到最近的父级入口 HTML。这对于使用客户端路由的 SPA 应用非常有用(如 React Router、Vue Router)。
autoMpaHtmlPlugin({
entryName: "main.tsx",
historyApiFallback: true
})例如,如果你在 /subdir 有一个入口,访问 /subdir/any/nested/path 将返回 subdir/index.html(或实验模式下的 subdir.html)的渲染结果。
局限
多层级的多页应用从v1版本开始支持,但构建过程需要生成临时的HTML文件,请注意是否与目录结构有冲突。
ENV文件只支持项目根目录,每页单独的env文件 暂无计划支持。
当
experimental.customTemplateName配置为".html"时,即希望根据目录名称自动生成对应名称的html文件,此时如果根目录有符合条件的入口文件,构建将会失败,以避免生成到outDir目录外,污染其他项目。本插件原本不支持页面配置更改时自动重启的功能,但你可以使用由@antfu维护的vite-plugin-restart,并添加如下配置,
ViteRestart({
restart: [
'config.[jt]s', // your configuration file name
]
})Vite自身特性
- [x] 环境变量和模式(Vite v4.2+)
构建
git clone https://github.com/iamspark1e/vite-plugin-auto-mpa-html.git
cd vite-plugin-auto-mpa-html
npm install
# npm run test # 建议在发起合并前,先本地进行单元测试😊
npm run build类似功能的插件
这个插件在开发出发点是由于相关需求而来的,在开发前未曾了解过Vite插件开发。在此过程中阅读了一些相关功能插件的源码,从中学习了很多我能够借鉴的想法。下面这些插件同样能够完成多页应用的构建,如果我的插件不能够满足你的需求,你可以看看下面这些优秀的Vite插件,希望能帮助到你!
