@fchc8/vite-plugin-multi-page 1.1.1 → 1.3.0

package/README-EN.md

@@ -1,424 +1,270 @@
 # vite-plugin-multi-page
 
-> English Documentation | [中文文档](./README.md)
+> 中文文档 | [中文文档](./README.md)
 
-A powerful Vite plugin for building multi-page applications with smart file routing and multiple build strategies.
+A powerful Vite plugin for building multi-page applications with smart file routing and multi-strategy builds.
 
-## ✨ Features
+## Features
 
-- 🚀 **Automatic Page Discovery**: Automatically scan and configure entry pages based on file patterns
-- 🎯 **Multiple Build Strategies**: Configure different build options and optimization strategies for different pages
-- 🧩 **Flexible Configuration**: Support object configuration, function configuration, and pattern matching
-- 📱 **Responsive Templates**: Different pages can use different HTML templates
-- 🔧 **Full Vite Integration**: Inherit all Vite configuration options
-- 🌍 **Environment Variables Support**: Page-level and strategy-level environment variable definitions
-- 🎨 **Developer Friendly**: Detailed debug logs and hot reload support
+- 🎯 **Multi-page support**: Automatically discover page entry files
+- 🔧 **Multi-strategy builds**: Support configuring different build strategies for different pages
+- 📝 **TypeScript configuration**: Support TypeScript configuration files
+- 🚀 **CLI tool**: Provide a command-line batch build tool
+- 🔄 **Hot reload**: Development server supports page hot reload
+- 📦 **Smart merge**: Automatically merge multi-strategy build results
 
-## 📦 Installation
+## Installation
 
 ```bash
-npm install @fchc8/vite-plugin-multi-page
-# or
-yarn add @fchc8/vite-plugin-multi-page
-# or
-pnpm add @fchc8/vite-plugin-multi-page
+npm install vite-plugin-multi-page --save-dev
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
-### Basic Usage
+### 1. Create a configuration file
+
+Create a `multipage.config.ts` or `multipage.config.js`:
 
 ```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import viteMultiPage from '@fchc8/vite-plugin-multi-page';
+export default context => {
+  const { mode, command, isCLI } = context;
+  const isProduction = mode === 'production';
 
-export default defineConfig({
-  plugins: [
-    viteMultiPage({
-      entry: 'src/pages/**/*.{ts,js}',
-      template: 'index.html',
-      exclude: ['src/main.ts'],
-      debug: true,
-    }),
-  ],
-});
-```
+  return {
+    // Page entry matching rule
+    entry: 'src/pages/**/*.{ts,js}',
 
-### Project Structure Example
+    // HTML template
+    template: 'index.html',
 
-```
-project/
-├── src/
-│   └── pages/
-│       ├── home.ts          → /home.html
-│       ├── about.ts         → /about.html
-│       ├── admin/
-│       │   └── dashboard.ts → /dashboard.html
-│       └── mobile/
-│           └── app.js       → /app.html
-├── index.html
-├── admin.html
-└── mobile.html
-```
+    // Template placeholder
+    placeholder: '{{ENTRY_FILE}}',
 
-## 🎯 Advanced Configuration
+    // Excluded files
+    exclude: ['src/shared/**/*.ts'],
 
-### Multiple Build Strategies
+    // Debug mode
+    debug: !isProduction || isCLI,
 
-```typescript
-import { defineConfig } from 'vite';
-import viteMultiPage from '@fchc8/vite-plugin-multi-page';
-
-export default defineConfig({
-  plugins: [
-    viteMultiPage({
-      entry: 'src/pages/**/*.{ts,js}',
-
-      // Define build strategies
-      buildStrategies: {
-        // Modern browser strategy
-        default: {
-          viteConfig: {
-            define: {
-              'process.env.BUILD_TYPE': '"modern"',
-            },
-          },
-          output: {
-            format: 'es',
-            entryFileNames: 'assets/[name]-[hash].js',
-          },
-          build: {
-            target: 'es2015',
-            minify: 'esbuild',
-            sourcemap: true,
-          },
+    // Build strategy
+    strategies: {
+      default: {
+        define: {
+          IS_DEFAULT: true,
+          API_BASE: isProduction ? '"https://api.example.com"' : '"http://localhost:3001/api"',
         },
-
-        // Legacy compatibility strategy
-        legacy: {
-          viteConfig: {
-            define: {
-              'process.env.BUILD_TYPE': '"legacy"',
-            },
-          },
-          output: {
-            format: 'iife',
-            entryFileNames: 'legacy/[name].js',
-          },
-          build: {
-            target: 'es5',
-            minify: 'terser',
-            sourcemap: false,
-          },
+        build: {
+          sourcemap: !isProduction,
+          minify: isProduction ? 'esbuild' : false,
         },
+      },
 
-        // Mobile optimization strategy
-        mobile: {
-          viteConfig: {
-            css: {
-              devSourcemap: true,
-            },
-            optimizeDeps: {
-              include: ['mobile-utils'],
-            },
-          },
-          build: {
-            target: 'es2018',
-            chunkSizeWarningLimit: 300,
-          },
+      mobile: {
+        define: {
+          IS_MOBILE: true,
+          API_BASE: isProduction
+            ? '"https://mobile-api.example.com"'
+            : '"http://localhost:3001/mobile-api"',
+        },
+        build: {
+          target: ['es2015', 'chrome58', 'safari11'],
+          minify: isProduction ? 'terser' : false,
         },
       },
-    }),
-  ],
-});
-```
-
-### Function Configuration
-
-```typescript
-viteMultiPage({
-  entry: 'src/pages/**/*.{ts,js}',
+    },
 
-  // Use function for dynamic configuration
-  pageConfigs: context => {
-    const { pageName, filePath, relativePath } = context;
+    // Page configuration function
+    pageConfigs: context => {
+      // Determine the application strategy based on the file path
+      if (context.relativePath.includes('/mobile/')) {
+        return {
+          strategy: 'mobile',
+          define: {
+            PAGE_NAME: context.pageName,
+            MOBILE_PAGE: true,
+          },
+        };
+      }
 
-    // Admin pages
-    if (pageName.startsWith('admin')) {
+      // Default strategy
       return {
         strategy: 'default',
-        template: 'admin.html',
         define: {
-          'process.env.API_BASE': '"https://admin-api.example.com"',
+          PAGE_NAME: context.pageName,
+          DEFAULT_PAGE: true,
         },
       };
-    }
-
-    // Mobile pages
-    if (relativePath.includes('/mobile/')) {
-      return {
-        strategy: 'mobile',
-        template: 'mobile.html',
-        define: {
-          'process.env.API_BASE': '"https://mobile-api.example.com"',
-        },
-      };
-    }
-
-    // Default configuration
-    return {
-      strategy: 'default',
-    };
-  },
-});
+    },
+  };
+};
 ```
 
-### Object Configuration with Pattern Matching
+### 2. Configure Vite
 
-```typescript
-viteMultiPage({
-  entry: 'src/pages/**/*.{ts,js}',
-
-  pageConfigs: {
-    // Exact match
-    home: {
-      strategy: 'default',
-      template: 'home.html',
-    },
+Add the plugin in `vite.config.ts`:
 
-    // Wildcard match
-    'admin*': {
-      strategy: 'default',
-      template: 'admin.html',
-    },
+```typescript
+import { defineConfig } from 'vite';
+import viteMultiPage from 'vite-plugin-multi-page';
 
-    // Pattern match
-    'mobile-app': {
-      strategy: 'mobile',
-      match: ['**/mobile/**', '*mobile*'],
-      template: 'mobile.html',
-    },
-  },
+export default defineConfig({
+  plugins: [viteMultiPage()],
 });
 ```
 
-## 📋 Configuration Options
-
-### MultiPageOptions
-
-| Option            | Type                                               | Default                                | Description                 |
-| ----------------- | -------------------------------------------------- | -------------------------------------- | --------------------------- |
-| `entry`           | `string`                                           | `"src/**/*.{ts,js}"`                   | Entry file matching pattern |
-| `template`        | `string`                                           | `"index.html"`                         | Default HTML template       |
-| `exclude`         | `string[]`                                         | `["src/main.ts", "src/vite-env.d.ts"]` | Files to exclude            |
-| `placeholder`     | `string`                                           | `"{{ENTRY_FILE}}"`                     | Placeholder in template     |
-| `debug`           | `boolean`                                          | `false`                                | Enable debug logs           |
-| `buildStrategies` | `Record<string, BuildStrategy>`                    | `{}`                                   | Build strategy definitions  |
-| `pageConfigs`     | `Record<string, PageConfig> \| PageConfigFunction` | `{}`                                   | Page configurations         |
+### 3. Create page files
 
-### BuildStrategy
+Create page files according to the convention:
 
-```typescript
-interface BuildStrategy {
-  // Full Vite configuration support
-  viteConfig?: Omit<UserConfig, 'plugins' | 'build'> & {
-    build?: BuildOptions;
-  };
+```
+src/pages/
+├── home.js                    # → /home.html
+├── about.js                   # → /about.html
+├── mobile/
+│   └── main.ts               # → /mobile.html (mobile strategy)
+└── admin/
+    └── main.ts               # → /admin.html
+```
 
-  // Output configuration
-  output?: {
-    format?: 'es' | 'cjs' | 'umd' | 'iife';
-    dir?: string;
-    entryFileNames?: string;
-    chunkFileNames?: string;
-    assetFileNames?: string;
-    globals?: Record<string, string>;
-    external?: string | string[] | ((id: string) => boolean);
-  };
+## Page discovery rules
 
-  // Build configuration
-  build?: {
-    target?: string | string[];
-    minify?: boolean | 'terser' | 'esbuild';
-    sourcemap?: boolean | 'inline' | 'hidden';
-    lib?: boolean | LibraryOptions;
-    cssCodeSplit?: boolean;
-    cssTarget?: string | string[];
-    rollupOptions?: any;
-    // ... more Vite build options
-  };
+The plugin discovers page entries according to the following rules:
 
-  // Environment variables
-  define?: Record<string, any>;
+1. **First-level files** (priority 1): `src/pages/home.js` → `/home.html`
+2. **Directory main files** (priority 2): `src/pages/mobile/main.ts` → `/mobile.html`
 
-  // Alias configuration
-  alias?: Record<string, string>;
+**Directory priority rule**: If both `src/pages/about.js` and `src/pages/about/main.ts` exist, `src/pages/about/main.ts` will be used.
 
-  // Server configuration
-  server?: ServerOptions;
+## Build strategies
 
-  // CSS configuration
-  css?: CSSOptions;
+### Strategy configuration
 
-  // Dependency optimization
-  optimizeDeps?: DepOptimizationOptions;
-}
-```
-
-### PageConfig
+策略配置支持所有 Vite 配置选项:
 
 ```typescript
-interface PageConfig {
-  strategy?: string; // Build strategy to use
-  template?: string; // Page template
-  exclude?: string[]; // Exclude rules
-  define?: Record<string, any>; // Environment variables
-  alias?: Record<string, string>; // Aliases
-  build?: Partial<BuildStrategy['build']>; // Build configuration
-  match?: string | string[]; // Match patterns
+strategies: {
+  mobile: {
+    define: {
+      IS_MOBILE: true,
+    },
+    build: {
+      target: ['es2015'],
+      minify: 'terser',
+      terserOptions: {
+        compress: {
+          drop_console: true,
+        },
+      },
+    },
+    // Other Vite configurations...
+  },
 }
 ```
 
-## 🌟 Use Cases
+### Page strategy assignment
 
-### 1. Enterprise Multi-Page Application
+Assign strategies to pages through the `pageConfigs` function:
 
 ```typescript
-buildStrategies: {
-  admin: {
-    viteConfig: {
-      define: { 'process.env.APP_TYPE': '"admin"' }
-    },
-    build: {
-      target: 'es2015',
-      sourcemap: true
-    }
-  },
+pageConfigs: context => {
+  const { pageName, relativePath } = context;
 
-  public: {
-    viteConfig: {
-      define: { 'process.env.APP_TYPE': '"public"' }
-    },
-    build: {
-      target: 'es5',
-      minify: 'terser'
-    }
+  if (relativePath.includes('/mobile/')) {
+    return { strategy: 'mobile' };
   }
-}
-```
-
-### 2. Mobile Optimization
 
-```typescript
-buildStrategies: {
-  mobile: {
-    viteConfig: {
-      css: { devSourcemap: true },
-      optimizeDeps: { include: ['@mobile/utils'] }
-    },
-    build: {
-      target: 'es2018',
-      chunkSizeWarningLimit: 300,
-      cssCodeSplit: true
-    }
+  if (pageName.startsWith('admin')) {
+    return { strategy: 'admin' };
   }
-}
+
+  return { strategy: 'default' };
+};
 ```
 
-### 3. Component Library Development
+## 命令行工具
 
-```typescript
-buildStrategies: {
-  library: {
-    build: {
-      lib: {
-        entry: 'src/index.ts',
-        name: 'MyLibrary',
-        formats: ['es', 'umd']
-      },
-      minify: false,
-      sourcemap: true
-    }
-  }
-}
-```
+### 批量构建
 
-## 📱 Example Project
+```bash
+# Build all strategies
+npx vite-mp
 
-Check the `example/` directory for a complete example project including:
+# Pass additional Vite parameters
+npx vite-mp --host --port 3000
 
-- Admin dashboard (modern syntax)
-- Mobile application (compatible syntax)
-- Component library documentation
-- Different HTML templates
-- Function configuration examples
+# Enable debug mode
+npx vite-mp --debug
+```
 
-### Quick Start
+### 开发服务器
 
 ```bash
-# Method 1: Use setup script (recommended)
-./setup-example.sh
-
-# Method 2: Manual setup
-npm run build          # Build the plugin first
-cd example
-npm install            # Install example dependencies
-npm run dev            # Run development server
-
-# Method 3: Use root scripts
-npm run example:dev     # Development mode
-npm run example:build   # Build
-npm run example:preview # Preview build results
+# Start development server (all pages)
+npm run dev
+
+# Only display pages with specific strategies
+npm run dev -- --strategy mobile
 ```
 
-### Example Pages
+## Environment variables
 
-After building, visit these pages:
+- `VITE_BUILD_STRATEGY`: Specify a single strategy build
+- `IS_MOBILE`: Mobile identifier (configured in define)
+- `API_BASE`: API base address (configured in define)
 
-- `/home.html` - Home page (default strategy)
-- `/about.html` - About page (default strategy)
-- `/dashboard.html` - Admin dashboard (modern ES syntax + dedicated template)
-- `/app.html` - Mobile app (ES5 compatible syntax + mobile template)
-- `/index.html` - Component library docs (library mode + docs template)
+## TypeScript support
 
-## 🔧 Development
+The plugin fully supports TypeScript configuration files:
 
-```bash
-# Clone the project
-git clone https://github.com/fchc7/vite-plugin-multi-page.git
-cd vite-plugin-multi-page
+```typescript
+// multipage.config.ts
+import type { ConfigFunction } from 'vite-plugin-multi-page';
 
-# Install dependencies
-pnpm install
+const config: ConfigFunction = context => {
+  return {
+    entry: 'src/pages/**/*.{ts,js}',
+    // ... other configurations
+  };
+};
 
-# Development mode
-pnpm dev
+export default config;
+```
 
-# Type checking
-pnpm type-check
+## API reference
 
-# Code formatting
-pnpm format
+### Configuration options
 
-# Code linting
-pnpm lint
+| Option        | Type                       | Default                    | Description                  |
+| ------------- | -------------------------- | -------------------------- | ---------------------------- |
+| `entry`       | `string`                   | `'src/pages/**/*.{ts,js}'` | Page entry matching rule     |
+| `template`    | `string`                   | `'index.html'`             | HTML template file           |
+| `placeholder` | `string`                   | `'{{ENTRY_FILE}}'`         | Template placeholder         |
+| `exclude`     | `string[]`                 | `[]`                       | Excluded file patterns       |
+| `debug`       | `boolean`                  | `false`                    | Enable debug log             |
+| `strategies`  | `Record<string, Strategy>` | `{}`                       | Build strategy configuration |
+| `pageConfigs` | `Function \| Object`       | `{}`                       | Page                         |
 
-# Build
-pnpm build
-```
+### Utility functions
 
-## 🤝 Contributing
+```typescript
+import { defineConfig, defineConfigTransform } from 'vite-plugin-multi-page';
+
+// Define configuration
+export default defineConfig(context => ({
+  // Configuration options
+}));
 
-Issues and Pull Requests are welcome!
+// Configuration transformation
+const transform = defineConfigTransform((config, context) => {
+  // Modify configuration
+  return config;
+});
+```
 
-## 📄 License
+## Example project
 
-MIT License
+See [example](./example) directory for a complete example project.
 
-## 🔗 Related Links
+## License
 
-- [Vite Official Documentation](https://vitejs.dev/)
-- [TypeScript](https://www.typescriptlang.org/)
-- [ESLint](https://eslint.org/)
-- [Prettier](https://prettier.io/)
+MIT License