@meng-xi/vite-plugin 0.0.4 → 0.0.6

package/README-en.md

@@ -2,60 +2,72 @@
 
 <div align="center">
 	<a href="https://github.com/MengXi-Studio/vite-plugin">
-		<img alt="梦曦工作室 Logo" width="215" src="https://github.com/MengXi-Studio/vite-plugin/blob/master/packages/docs/src/public/logo.svg">
+		<img alt="MengXi Studio Logo" width="215" src="https://github.com/MengXi-Studio/vite-plugin/blob/master/packages/docs/src/public/logo.png">
 	</a>
 	<br>
 	<h1>@meng-xi/vite-plugin</h1>
+	<p>A toolkit providing practical plugins for Vite, also a complete plugin development framework</p>
 
 [![license](https://img.shields.io/github/license/MengXi-Studio/vite-plugin.svg)](LICENSE) [![npm](https://img.shields.io/npm/v/@meng-xi/vite-plugin?color=blue)](https://www.npmjs.com/package/@meng-xi/vite-plugin)
 ![npm](https://img.shields.io/npm/dt/@meng-xi/vite-plugin?color=green)
 
 </div>
 
-> - This is a toolkit that provides practical plugins for Vite, and also serves as a complete **Vite Plugin Development Framework**.
-> - Extends Vite build process functionality, providing automated processing solutions for common build tasks.
-> - All plugins support detailed configuration options, allowing customization based on project needs to meet different usage scenarios.
-> - Plugins provide error handling mechanisms to ensure build processes can catch errors, improving build reliability.
-> - Export core components like BasePlugin, Logger, Validator, allowing developers to build custom plugins based on the same infrastructure.
+## Features
 
----
+- **Ready to Use** - Provides practical plugins for file copying, router generation, version management, icon injection
+- **Plugin Development Framework** - Exports core components like BasePlugin, Logger, Validator for building custom plugins
+- **Complete Lifecycle** - Supports initialization, config resolution, destroy lifecycle management with automatic hook composition
+- **Type Safe** - Complete TypeScript type definitions with configuration validators ensuring parameter correctness
+- **Flexible Configuration** - All plugins support detailed configuration to meet diverse scenario requirements
+- **Safe Execution** - Built-in error handling strategies (throw / log / ignore) for unified exception management
 
-Start reading the [documentation](https://mengxi-studio.github.io/vite-plugin/).
+## Documentation
 
-## Quick Start
-
-### Installation
+View full documentation: [https://mengxi-studio.github.io/vite-plugin/](https://mengxi-studio.github.io/vite-plugin/)
 
-Install `@meng-xi/vite-plugin` using a package manager:
+## Installation
 
 ```bash
-# Using npm
-npm install @meng-xi/vite-plugin --save-dev
+# npm
+npm install @meng-xi/vite-plugin -D
 
-# Using yarn
-yarn add @meng-xi/vite-plugin --save-dev
+# yarn
+yarn add @meng-xi/vite-plugin -D
 
-# Using pnpm
-pnpm add @meng-xi/vite-plugin --save-dev
+# pnpm
+pnpm add @meng-xi/vite-plugin -D
 ```
 
-### Basic Usage
+## Quick Start
 
-#### Using Built-in Plugins
+### Using Built-in Plugins
 
 ```typescript
 import { defineConfig } from 'vite'
-import { copyFile, injectIco } from '@meng-xi/vite-plugin'
+import { copyFile, generateRouter, generateVersion, injectIco } from '@meng-xi/vite-plugin'
 
 export default defineConfig({
 	plugins: [
-		// Copy file plugin
+		// Copy files
 		copyFile({
 			sourceDir: 'src/assets',
 			targetDir: 'dist/assets'
 		}),
 
-		// Inject icon plugin
+		// Generate router config (uni-app)
+		generateRouter({
+			pagesJsonPath: 'src/pages.json',
+			outputPath: 'src/router.config.ts'
+		}),
+
+		// Generate version
+		generateVersion({
+			format: 'datetime',
+			outputType: 'both'
+		}),
+
+		// Inject website icon
 		injectIco({
 			base: '/assets'
 		})
@@ -63,24 +75,34 @@ export default defineConfig({
 })
 ```
 
-#### Developing Custom Plugins
+### Accessing Plugin Instance
+
+All built-in plugins return an object with a `pluginInstance` property for accessing internal state:
 
 ```typescript
-import { BasePlugin, createPluginFactory, Validator } from '@meng-xi/vite-plugin'
+import type { PluginWithInstance } from '@meng-xi/vite-plugin/factory'
+import type { GenerateRouterOptions } from '@meng-xi/vite-plugin'
+
+const routerPlugin = generateRouter({ watch: true }) as PluginWithInstance<GenerateRouterOptions>
+
+// Access plugin internals via pluginInstance
+console.log(routerPlugin.pluginInstance?.options)
+```
+
+### Developing Custom Plugins
+
+```typescript
+import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin'
+import type { BasePluginOptions, PluginWithInstance } from '@meng-xi/vite-plugin/factory'
 import type { Plugin } from 'vite'
 
-interface MyPluginOptions {
+interface MyPluginOptions extends BasePluginOptions {
 	path: string
-	enabled?: boolean
-	verbose?: boolean
-	errorStrategy?: 'throw' | 'log' | 'ignore'
 }
 
 class MyPlugin extends BasePlugin<MyPluginOptions> {
 	protected getDefaultOptions() {
-		return {
-			path: './default'
-		}
+		return { path: './default' }
 	}
 
 	protected validateOptions(): void {
@@ -96,69 +118,226 @@ class MyPlugin extends BasePlugin<MyPluginOptions> {
 			this.logger.info(`Plugin started with path: ${this.options.path}`)
 		}
 	}
+
+	protected destroy(): void {
+		super.destroy()
+		// Custom cleanup logic, e.g. close connections, stop watchers
+	}
 }
 
 export const myPlugin = createPluginFactory(MyPlugin)
 ```
 
-## Plugin Details
+## Plugin Development Framework
 
-### copyFile Plugin
+### BasePlugin Core Concepts
 
-Used to copy files or directories to specified locations after Vite build is completed.
+`BasePlugin` is the base class for all plugins, providing complete lifecycle management and development conventions:
 
-**Configuration Options**:
+#### Lifecycle
 
-- `sourceDir`: Source directory path (required)
-- `targetDir`: Target directory path (required)
-- `overwrite`: Whether to overwrite existing files, default is `true`
-- `recursive`: Whether to recursively copy subdirectories, default is `true`
-- `verbose`: Whether to output detailed logs, default is `true`
-- `enabled`: Whether to enable the plugin, default is `true`
+| Phase             | Method             | Description                                                    |
+| ----------------- | ------------------ | -------------------------------------------------------------- |
+| Initialization    | `constructor`      | Merge options, initialize logger and validator                 |
+| Config Resolution | `onConfigResolved` | Called when Vite config is resolved                            |
+| Hook Registration | `addPluginHooks`   | Register Vite plugin hooks                                     |
+| Destroy           | `destroy`          | Automatically called during `closeBundle` for resource cleanup |
 
-### injectIco Plugin
+#### Automatic Hook Composition
 
-Used to inject website icon links into the head of HTML files during the Vite build process.
+The `toPlugin()` method automatically composes the following hooks:
 
-**Configuration Options**:
+- **configResolved** - Base class `onConfigResolved` runs first, then subclass hook
+- **closeBundle** - Subclass hook runs first, then base class `destroy`
 
-- `base`: Base path for icon files
-- `url`: Complete URL for the icon
-- `link`: Custom complete link tag HTML
-- `icons`: Custom icon array
-- `verbose`: Whether to output detailed logs, default is `true`
-- `enabled`: Whether to enable the plugin, default is `true`
-- `copyOptions`: Icon file copying configuration
+> Subclasses don't need to manually register `closeBundle` hooks for cleanup — just override the `destroy()` method.
 
-## Contribution
+#### Required Methods
 
-Welcome to contribute to `@meng-xi/vite-plugin`. Here are the steps to contribute code:
+| Method                   | Description           |
+| ------------------------ | --------------------- |
+| `getPluginName()`        | Return plugin name    |
+| `addPluginHooks(plugin)` | Add Vite plugin hooks |
 
-1. Fork the project: Fork this project on GitHub.
-2. Clone the code: Clone the forked project to your local machine.
+#### Optional Methods
 
-```bash
-git clone https://github.com/your-username/vite-plugin.git
-cd vite-plugin
+| Method                     | Default Behavior  | Description                                 |
+| -------------------------- | ----------------- | ------------------------------------------- |
+| `getDefaultOptions()`      | Returns `{}`      | Provide plugin default options              |
+| `validateOptions()`        | No validation     | Validate configuration parameters           |
+| `getEnforce()`             | `undefined`       | Plugin execution order (`'pre'` / `'post'`) |
+| `onConfigResolved(config)` | Store config      | Config resolved callback                    |
+| `destroy()`                | Unregister logger | Cleanup logic when plugin is destroyed      |
+
+#### Built-in Properties
+
+| Property     | Type                     | Description                   |
+| ------------ | ------------------------ | ----------------------------- |
+| `options`    | `Required<T>`            | Merged complete configuration |
+| `logger`     | `PluginLogger`           | Plugin logger                 |
+| `validator`  | `Validator<T>`           | Configuration validator       |
+| `viteConfig` | `ResolvedConfig \| null` | Resolved Vite configuration   |
+
+#### Error Handling Strategy
+
+Control error behavior via the `errorStrategy` configuration option:
+
+- `'throw'` (default) - Log error and throw exception, halting the build
+- `'log'` - Log error but don't throw, continue execution
+- `'ignore'` - Log error but don't throw, continue execution
+
+Wrap error-prone operations with `safeExecute` / `safeExecuteSync`:
+
+```typescript
+const result = await this.safeExecute(async () => {
+	return await someAsyncOperation()
+}, 'Execute async operation')
 ```
 
-3. Create a new branch: Create a new feature branch based on the `master` branch.
+### createPluginFactory
 
-```bash
-git checkout -b feature/your-feature
+Create plugin factory functions with optional normalizer support:
+
+```typescript
+// Basic usage
+const myPlugin = createPluginFactory(MyPlugin)
+
+// With normalizer (supports shorthand string config)
+const myPlugin = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))
+
+// Usage with shorthand
+myPlugin('./custom-path')
 ```
 
-4. Commit changes: Ensure your code passes tests and commit your changes with clear commit messages.
+### Logger
 
-```bash
-git add .
-git commit -m "feat: add your feature description"
+Global singleton log manager providing independent log control for each plugin:
+
+```typescript
+import { Logger } from '@meng-xi/vite-plugin/logger'
+
+// Create logger (usually called automatically by BasePlugin)
+Logger.create({ name: 'my-plugin', enabled: true })
+
+// Unregister plugin log config (automatically called on plugin destroy)
+Logger.unregister('my-plugin')
+
+// Destroy singleton (for test scenarios)
+Logger.destroy()
 ```
 
-5. Push changes: Push your local branch to GitHub.
+Log output format:
 
-```bash
-git push origin feature/your-feature
 ```
+ℹ️ [@meng-xi/vite-plugin:my-plugin] Info message
+✅ [@meng-xi/vite-plugin:my-plugin] Success message
+⚠️ [@meng-xi/vite-plugin:my-plugin] Warning message
+❌ [@meng-xi/vite-plugin:my-plugin] Error message
+```
+
+## Built-in Plugins
+
+### copyFile
+
+Copy files or directories to specified locations after Vite build is completed.
+
+| Option      | Type    | Default | Description                                |
+| ----------- | ------- | ------- | ------------------------------------------ |
+| sourceDir   | string  | -       | Source directory path (required)           |
+| targetDir   | string  | -       | Target directory path (required)           |
+| overwrite   | boolean | true    | Whether to overwrite existing files        |
+| recursive   | boolean | true    | Whether to recursively copy subdirectories |
+| incremental | boolean | true    | Whether to enable incremental copying      |
+
+### generateRouter
+
+Automatically generate router configuration files based on uni-app project's `pages.json`.
+
+| Option               | Type                                              | Default                | Description                                      |
+| -------------------- | ------------------------------------------------- | ---------------------- | ------------------------------------------------ |
+| pagesJsonPath        | string                                            | 'src/pages.json'       | Path to pages.json file                          |
+| outputPath           | string                                            | 'src/router.config.ts' | Output file path                                 |
+| outputFormat         | 'ts' \| 'js'                                      | 'ts'                   | Output file format                               |
+| nameStrategy         | 'path' \| 'camelCase' \| 'pascalCase' \| 'custom' | 'camelCase'            | Route name strategy                              |
+| customNameGenerator  | (path: string) => string                          | -                      | Custom route name generator function             |
+| includeSubPackages   | boolean                                           | true                   | Whether to include sub-package routes            |
+| watch                | boolean                                           | true                   | Whether to watch changes and auto-regenerate     |
+| metaMapping          | Record\<string, string\>                          | -                      | Mapping from page style fields to meta           |
+| exportTypes          | boolean                                           | true                   | Whether to export type definitions               |
+| preserveRouteChanges | boolean                                           | true                   | Whether to preserve user modifications to routes |
+
+### generateVersion
+
+Automatically generate version numbers during the Vite build process.
+
+| Option       | Type                                                                  | Default           | Description                    |
+| ------------ | --------------------------------------------------------------------- | ----------------- | ------------------------------ |
+| format       | 'timestamp' \| 'date' \| 'datetime' \| 'semver' \| 'hash' \| 'custom' | 'timestamp'       | Version format                 |
+| customFormat | string                                                                | -                 | Custom format template         |
+| semverBase   | string                                                                | '1.0.0'           | Semantic version base          |
+| outputType   | 'file' \| 'define' \| 'both'                                          | 'file'            | Output type                    |
+| outputFile   | string                                                                | 'version.json'    | Output file path               |
+| defineName   | string                                                                | '**APP_VERSION**' | Global variable name to inject |
+| hashLength   | number                                                                | 8                 | Hash length (1-32)             |
+| prefix       | string                                                                | -                 | Version number prefix          |
+| suffix       | string                                                                | -                 | Version number suffix          |
+| extra        | Record\<string, unknown\>                                             | -                 | Extra info (JSON file only)    |
+
+### injectIco
+
+Inject website icon links into the head of HTML files during the Vite build process.
+
+| Option      | Type   | Default | Description                     |
+| ----------- | ------ | ------- | ------------------------------- |
+| base        | string | '/'     | Base path for icon files        |
+| url         | string | -       | Complete URL for the icon       |
+| link        | string | -       | Custom complete link tag HTML   |
+| icons       | Icon[] | -       | Custom icon array               |
+| copyOptions | object | -       | Icon file copying configuration |
+
+`Icon` interface definition:
+
+| Property | Type   | Required | Description        |
+| -------- | ------ | -------- | ------------------ |
+| rel      | string | Yes      | Icon relation type |
+| href     | string | Yes      | Icon URL           |
+| sizes    | string | No       | Icon sizes         |
+| type     | string | No       | Icon MIME type     |
+
+## Sub-path Exports
+
+Support importing modules on demand to reduce bundle size:
+
+```typescript
+// Full import
+import { copyFile, BasePlugin, Logger } from '@meng-xi/vite-plugin'
+
+// Module-level import
+import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory'
+import { Logger } from '@meng-xi/vite-plugin/logger'
+import { copyFile, generateRouter } from '@meng-xi/vite-plugin/plugins'
+import { Validator, readFileContent, writeFileContent } from '@meng-xi/vite-plugin/common'
+
+// Type imports (on-demand type definitions from sub-paths)
+import type { PluginWithInstance, PluginFactory, BasePluginOptions } from '@meng-xi/vite-plugin/factory'
+import type { GenerateVersionOptions, InjectIcoOptions, Icon } from '@meng-xi/vite-plugin/plugins'
+import type { DateFormatOptions } from '@meng-xi/vite-plugin/common'
+```
+
+## Changelog
+
+See [GitHub Releases](https://github.com/MengXi-Studio/vite-plugin/releases)
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Commit changes: `git commit -m "feat: your feature description"`
+4. Push to branch: `git push origin feature/your-feature`
+5. Create a Pull Request
+
+## License
 
-6. Create a PR: Create a Pull Request on GitHub and wait for review.
+[MIT](LICENSE)