vite-plugin-auto-mpa-html

English | 中文文档

基于文件目录的Vite自动化多页面构建插件，支持使用 Handlebars 的 HTML 模板。

快速使用

1npm i vite-plugin-auto-mpa-html@latest -D # Or yarn/pnpm as you like

安装完成后，在vite.config.(js/ts)里加入插件，

1import { defineConfig } from 'vite'
2import react from '@vitejs/plugin-react'
3import autoMpaHtmlPlugin from 'vite-plugin-auto-mpa-html'
4
5// https://vitejs.dev/config/
6export default defineConfig({
7  plugins: [react(), autoMpaHtmlPlugin({
8    entryName: "main.tsx",
9    sharedData: {},
10    enableDevDirectory: true, // 在dev环境下临时渲染一个目录页面
11    renderEngineOption: {}
12  })],
13})

现在回到项目目录下，以下面这个项目结构为例：

这是一个基于官方模板生成的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 文件，内容可以参考下面：

1{
2    "template": "../../templates/index.html", // 从v1版本开始，使用相对路径
3    "data": {
4        "title": "This is page 2",
5        "description": "page 22222222",
6        "keywords": "2"
7    }
8}

由于我们的项目文件是创建在了src的子文件夹下，所以vite.config.(js/ts)需要一些额外的配置来进行适配：

1export default defineConfig({
2  root: "src", // 避免生成的入口目录中含有src层级
3  base: "",
4  build: {
5    outDir: "../dist", // outDir默认值是与root的相对路径，root改为子目录后，dist需要生成到根目录下，因此需要配置
6    emptyOutDir: true,
7  }
8})

完成配置，现在运行 npm run build，输出目录下就是使用本插件的效果了

提示，本插件在构建过程中会生成一个临时的index.html在各个入口处，请注意避免冲突！

Plugin Options

1{
2  /**
3   * 当调试时，生成一个目录页来方便访问 (旧为`enableDirectoryPage`)
4   * @default true
5   */
6  enableDevDirectory?: boolean
7  /**
8   * 顶层配置的共享数据，在渲染Handlebars时会添加到每个入口处。
9   * @default {}
10   */
11  sharedData?: object
12  /**
13   * Handlebars的一些配置选项
14   * @see {@link https://handlebarsjs.com/zh/api-reference/compilation.html}
15   * @default {}
16   */
17  renderEngineOption?: object
18  /**
19   * 多页项目的每个入口文件名, 例如, Vue项目一般为`main.js`, React项目一般为`main.jsx`.
20   * @default "main.js"
21   */
22  entryName: string
23  /**
24   * 配置文件名，在版本v1.1.0后，你可以使用js导出一个es module来配置页面，TS暂不支持.
25   * @default "config.json"
26   */
27  configName?: string
28  /**
29   * 测试特性，键值可能会在版本更新时有改动，请注意！
30   */
31  experimental?: {
32    /**
33     * 重命名生成的HTML文件，默认为`index.html`(便于各类静态文件服务)，但是你也可以命名为其他名字。
34     * *特殊的，如果你在此配置`.html`，那么HTML文件会置于入口文件的父级，并以入口文件名来命名。但是这个选项不能在你配置的root目录下生效，因为这样做生成的HTMl文件会置于outDir外，进而产生污染。
35     */
36    customTemplateName?: string
37    /**
38     * 由于根目录(vite.config.js内配置的root选项)无法自动获取入口名称，默认使用_root作为其module名，你也可以通过这个配置项来自定义。
39     */
40    rootEntryDistName?: string
41  }
42}

每个入口页面的单独配置选项

这个文件是放置在每个入口目录的config.json

1{
2  /**
3   * 本页应用模板的*相对*路径
4   * @required
5   */
6  template: string
7  /**
8   * 本页Handlebars模板使用的渲染数据，会与顶层配置的sharedData进行合并
9   * @default {}
10   */
11  data?: object
12}

如果你需要根据一些外部变量动态控制每一页在编译时使用的页面配置，你也可以通过修改configName为.js文件，并在文件中导出一个默认配置

1// After v1.1.0, you can use `pageConfigGenerator` to dynamically set page config.
2import { pageConfigGenerator } from 'vite-plugin-auto-mpa-html'
3
4// pageConfigGenerator accepts direct cofig object, function, and even Promise.
5export default pageConfigGenerator({
6  "template": "../../template/index.html"
7})

条件页面配置

借助跨页面的选项 sharedData ，您可以注入所需的变量，然后在页面配置中读取它们（或直接在 Handlebars 模板中使用），例如：

1import { pageConfigGenerator } from 'vite-plugin-auto-mpa-html'
2
3// `pageConfigGenerator` is not required, but it can provide TypeScript reference.
4export default pageConfigGenerator((opt) => {
5  console.log(opt.sharedData);
6  return {
7    "template": "../template/index.html",
8    data: {
9      isProd: opt.sharedData.isProd
10    }
11  }
12})
13
14// 如果你更喜欢使用JSDoc的方式，你也可以像下面一样引入类型，这样可以不导入`pageConfigGenerator`
15/** @type {import('vite-plugin-auto-mpa-html').PageConfigGeneratorTypeExport} */
16/** @param {import('vite-plugin-auto-mpa-html').PageConfigOption} opt  */

局限

• 多层级的多页应用从v1版本开始支持，但构建过程需要生成临时的HTML文件，请注意是否与目录结构有冲突。

• ENV文件只支持项目根目录，每页单独的env文件 暂无计划支持。

• 当 experimental.customTemplateName 配置为 ".html" 时，即希望根据目录名称自动生成对应名称的html文件，此时如果根目录有符合条件的入口文件，构建将会失败，以避免生成到outDir目录外，污染其他项目。

Vite自身特性

• 环境变量和模式(Vite v4.2+)

构建

1git clone https://github.com/iamspark1e/vite-plugin-auto-mpa-html.git
2cd vite-plugin-auto-mpa-html
3npm install
4# npm run test # 建议在发起合并前，先本地进行单元测试😊
5npm run build

类似功能的插件

这个插件在开发出发点是由于相关需求而来的，在开发前未曾了解过Vite插件开发。在此过程中阅读了一些相关功能插件的源码，从中学习了很多我能够借鉴的想法。下面这些插件同样能够完成多页应用的构建，如果我的插件不能够满足你的需求，你可以看看下面这些优秀的Vite插件，希望能帮助到你！

• vite-plugin-mpa
• vite-plugin-mp
• vite-plugin-mpa-plus
• vite-plugin-html-template-mpa
• vite-plugin-virtual-mpa