English | 中文文档

A file directory-based automated multi-page Vite plugin that supports HTML templates using EJS.

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

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

Then, add plugin to your vite.config.(js/ts), like this,

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, // enable directory page will render an directory page at "http://localhost:5173/", if you have an index, it will not be affect.
    ejsOption: {}
  })],
})

Now, focus on your PAGES, for example, a project like this,

Using the official template of react-ts, copied page's assets to 2 pages, the "index" and the "page2"

.
├── 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

How to generate a beautiful tree like this? Run tree -I "node_modules|dist" > folders.txt with tree package!

Manually create a config.json in the subdirectory of the page, with these content,

{
    "template": "../../templates/index.html", // Using relative path from v1
    "data": {
        "title": "This is page 2",
        "description": "page 22222222",
        "keywords": "2"
    }
}

We put all pages into different folders under src, some additional config should be put into vite.config.js

export default defineConfig({
  root: "src",
  base: "",
  build: {
    outDir: "../dist",
    emptyOutDir: true,
  }
})

Finished, everything is ready, run npm run build to see what is built with vite-plugin-auto-mpa-html.

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!

{
  /**
   * Render a directory page in development (as the old key `enableDirectoryPage`)
   * @default true
   */
  enableDevDirectory?: boolean
  /**
   * Top-level data, which will be shared to every entry during EJS render.
   * @default {}
   */
  sharedData?: object
  /**
   * EJS render options
   * @see {@link https://github.com/mde/ejs#options}
   * @default {}
   */
  ejsOption?: object
  /**
   * Entries of your multi-entry application, for example, `main.js` for Vue, and `main.jsx` for React.
   * @default "main.js"
   */
  entryName: string
  /**
   * Config file name, after v1.1.0 you can use an ESM style exported config module, .ts is not supported yet.
   * @default "config.json"
   */
  configName?: string
  /**
   * Experimental features for plugin, using at your own risk!
   */
  experimental?: {
    /**
     * 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.
     * [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.
     */
    customTemplateName?: string
    /**
     * Config the asset name of root's entry file, default value is "_root"
     */
    rootEntryDistName?: string
  }
}

{
  /**
   * The RELATIVE path of your template
   * @required
   */
  template: string
  /**
   * EJS render data in this entry, which will be assigned with global `sharedData`
   * @default {}
   */
  data?: object
}

// 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"
})

We 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 ejs templates), like this,

// `pageConfigGenerator` is not required, but it can provide TypeScript reference.
export default function(opt) { // Or even promise function
  console.log(opt.sharedData);
  return {
    "template": "../template/index.html",
    data: {
      isProd: opt.sharedData.isProd
    }
  }
}

• Nested folder is SUPPORTED from v1, but will generate a temporary index.html besides your entry file.

• Env files is only supported in root folder (same level as vite.config.js), env-per-entry is NOT SUPPORTED.

• 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.

• 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,

ViteRestart({
  restart: [
    'config.[jt]s', // your configuration file name
  ]
})

• [x] v4.2+ HTML Env Replacement

# It's simple, just clone, install, and build!
git clone https://github.com/iamspark1e/vite-plugin-auto-mpa-html.git
cd vite-plugin-auto-mpa-html
npm install # or any node package manager you like
# npm run test # I'd suggest to run a fully test before commit.
npm run build

I'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,

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