import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import mogic from 'vite-plugin-mogic'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    mogic({
      entryName: "main.tsx",
      defaultTemplate: "./templates/index.html", // 默认模板路径
      sharedData: {}, // 全局共享数据
      enableProdDirectory: false, // 生产环境是否启用目录页面
      renderEngineOption: {} // Handlebars 渲染选项
    })
  ],
})

项目结构示例

以下是一个典型的多页应用项目结构：

.
├── package.json
├── public
│   └── vite.svg
├── src
│   ├── mogic
│   │   ├── App.css
│   │   ├── App.tsx
│   │   ├── assets
│   │   │   └── react.svg
│   │   ├── mogic.json
│   │   ├── index.css
│   │   ├── main.tsx
│   │   └── vite-env.d.ts
├── index.html
├── tsconfig.json
└── vite.config.ts

页面配置

在每个入口目录下创建 mogic.json 文件：

{
    "title": "Mogic Template",
    "description": "This is a template for Mogic",
    "keywords": "Mogic, Template"
}

重要变更：

✅ 使用 mogic.json 替代 config.json
✅ 数据直接放在根级别，不需要 data 包装
✅ 不再支持 template 字段，请使用插件的 defaultTemplate 选项

多层级项目配置

如果你的项目文件在 src 子目录下，需要在 vite.config.(js/ts) 中进行额外配置：

export default defineConfig({
  root: "src", // 设置根目录为 src
  base: "",
  build: {
    outDir: "../dist", // 输出到项目根目录的 dist 文件夹
    emptyOutDir: true,
  },
  plugins: [
    react(),
    mogic({
      entryName: "main.tsx",
      defaultTemplate: path.resolve(__dirname, "index.html"),
    })
  ]
})

构建

完成配置后，运行构建命令：

npm run build

构建完成后，dist 目录将包含所有生成的页面。

注意：插件使用虚拟入口系统，构建过程中不会生成临时文件，避免了文件冲突问题。

配置选项

插件选项

interface PluginOption {
  /**
   * 入口文件名，插件会搜索所有包含此文件的目录作为页面入口
   * @default "main.js"
   * @example "main.tsx", "main.js", "index.js"
   */
  entryName?: string

  /**
   * 默认模板文件路径，当页面没有指定模板时使用
   * @default undefined
   * @example "./templates/index.html"
   */
  defaultTemplate?: string

  /**
   * Handlebars 渲染引擎配置选项
   * @default {}
   */
  renderEngineOption?: {
    compileOptions?: CompileOptions
    runtimeOptions?: RuntimeOptions
  }

  /**
   * 全局共享数据，会合并到每个页面的数据中
   * @default {}
   * @example { siteName: "我的网站", version: "1.0.0" }
   */
  sharedData?: object

  /**
   * 是否在生产环境生成目录导航页面
   * 开发环境始终启用目录页面
   * @default false
   */
  enableProdDirectory?: boolean
}

页面配置选项

每个页面入口目录中的 mogic.json 文件用于配置该页面的数据。这些数据会在模板渲染时与全局 sharedData 合并。

配置示例：

{
  "title": "Mogic Template",
  "description": "This is a template for Mogic",
  "keywords": "Mogic, Template"
}

配置说明：

所有数据直接放在根级别，不需要 data 包装
支持任意结构的 JSON 数据
数据会与 sharedData 合并后传递给 Handlebars 模板
页面级数据优先级高于全局 sharedData

重要提醒：

❌ 不再支持 template 字段
❌ 不再支持 data 包装结构
✅ 使用插件的 defaultTemplate 选项指定模板

模板系统

插件使用 Handlebars 作为模板引擎。在 HTML 模板中，你可以使用页面配置中的所有数据：

<!DOCTYPE html>
<html>
<head>
  <title>{{title}}</title>
  <meta name="description" content="{{description}}">
  <meta name="keywords" content="{{keywords}}">
  <meta name="author" content="{{author}}">
</head>
<body>
  <div id="app"></div>
</body>
</html>

高级功能

智能目录排序

插件会自动按照文件创建时间对入口目录进行排序（最新创建的在前），确保开发目录页面的展示顺序符合开发习惯。

虚拟入口系统

插件采用虚拟入口系统，构建过程中不会在文件系统中生成临时文件，避免了与现有文件的冲突问题，提高了构建效率。

开发时目录导航

开发环境下会自动生成一个目录导航页面，方便在多个页面间快速切换。访问开发服务器根路径即可看到所有页面的入口链接。

目录过滤

插件会自动跳过以下划线 _ 开头的目录，这些目录不会被识别为页面入口。这个特性可以用于存放共享组件、工具函数等非页面文件。

开发体验优化

配置文件热重载

当 mogic.json 文件发生变化时，可以配合 vite-plugin-restart 实现自动重启：

import ViteRestart from 'vite-plugin-restart'

export default defineConfig({
  plugins: [
    mogicPlugin(/* ... */),
    ViteRestart({
      restart: [
        '**/mogic.json', // 监听所有 mogic.json 文件变化
      ]
    })
  ]
})

注意事项与限制

环境变量：只支持项目根目录的 .env 文件，暂不支持页面级别的环境变量文件
目录命名：以下划线 _ 开头的目录会被自动跳过，不会作为页面入口
配置文件：每个页面入口必须包含 mogic.json 配置文件
模板路径：建议使用相对路径指定模板文件位置

Keywords

FAQs

What is vite-plugin-mogic?

Is vite-plugin-mogic popular?

Is vite-plugin-mogic well maintained?

Package last updated on 15 Sep 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

vite-plugin-mogic