@halo-dev/ui-plugin-bundler-kit 2.21.0 → 2.21.2

package/README.md

@@ -0,0 +1,333 @@
+# @halo-dev/ui-plugin-bundler-kit
+
+A frontend build toolkit for Halo plugin development, supporting both Vite and Rsbuild build systems.
+
+## Introduction
+
+`@halo-dev/ui-plugin-bundler-kit` is a frontend build configuration toolkit specifically designed for Halo plugin development. It provides pre-configured build settings to help developers quickly set up and build frontend interfaces for Halo plugins.
+
+### Key Features
+
+- 🚀 **Ready to Use** - Provides pre-configured Vite and Rsbuild build settings
+- 📦 **Multi-Build Tool Support** - Supports both Vite and Rsbuild
+- 🔧 **Flexible Configuration** - Supports custom build configurations
+- 🎯 **Halo Optimized** - External dependencies and global variables optimized for Halo plugin development
+- 📁 **Smart Output** - Automatically selects output directory based on environment
+
+## Installation
+
+```bash
+# Using npm
+npm install @halo-dev/ui-plugin-bundler-kit
+
+# Using yarn
+yarn add @halo-dev/ui-plugin-bundler-kit
+
+# Using pnpm
+pnpm add @halo-dev/ui-plugin-bundler-kit
+```
+
+### Additional Dependencies
+
+**For Vite users**, you need to install Vite:
+
+```bash
+npm install vite
+```
+
+**For Rsbuild users**, you need to install Rsbuild:
+
+```bash
+npm install @rsbuild/core
+```
+
+## Usage
+
+### Vite Configuration
+
+Create or update `vite.config.ts` file in your project root:
+
+```typescript
+import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
+
+export default viteConfig({
+  vite: {
+    // Your custom Vite configuration
+    plugins: [
+      // Additional plugins (Vue plugin is already included)
+    ],
+    // Other configurations...
+  },
+});
+```
+
+> **Note**: Vue plugin is pre-configured, no need to add it manually.
+
+### Rsbuild Configuration
+
+Create or update `rsbuild.config.ts` file in your project root:
+
+```typescript
+import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
+
+export default rsbuildConfig({
+  rsbuild: {
+    // Your custom Rsbuild configuration
+    plugins: [
+      // Additional plugins (Vue plugin is already included)
+    ],
+    // Other configurations...
+  },
+});
+```
+
+> **Note**: Vue plugin is pre-configured, no need to add it manually.
+
+### Legacy Configuration (Deprecated)
+
+> ⚠️ **Note**: The `HaloUIPluginBundlerKit` function is deprecated. Please use `viteConfig` or `rsbuildConfig` instead.
+
+```typescript
+import { HaloUIPluginBundlerKit } from "@halo-dev/ui-plugin-bundler-kit";
+
+export default {
+  plugins: [
+    HaloUIPluginBundlerKit({
+      // Configuration options
+    }),
+  ],
+};
+```
+
+## Configuration Options
+
+### Vite Configuration Options
+
+```typescript
+interface ViteUserConfig {
+  /**
+   * Halo plugin manifest file path
+   * @default "../src/main/resources/plugin.yaml"
+   */
+  manifestPath?: string;
+
+  /**
+   * Custom Vite configuration
+   */
+  vite: UserConfig | UserConfigFnObject;
+}
+```
+
+### Rsbuild Configuration Options
+
+```typescript
+interface RsBuildUserConfig {
+  /**
+   * Halo plugin manifest file path
+   * @default "../src/main/resources/plugin.yaml"
+   */
+  manifestPath?: string;
+
+  /**
+   * Custom Rsbuild configuration
+   */
+  rsbuild: RsbuildConfig | ((env: ConfigParams) => RsbuildConfig);
+}
+```
+
+## Advanced Configuration Examples
+
+### Adding Path Aliases (Vite)
+
+```typescript
+import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
+import path from "path";
+
+export default viteConfig({
+  vite: {
+    resolve: {
+      alias: {
+        "@": path.resolve(__dirname, "src"),
+        "@components": path.resolve(__dirname, "src/components"),
+      },
+    },
+  },
+});
+```
+
+### Adding Path Aliases (Rsbuild)
+
+```typescript
+import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
+
+export default rsbuildConfig({
+  rsbuild: {
+    source: {
+      alias: {
+        "@": "./src",
+        "@components": "./src/components",
+      },
+    },
+  },
+});
+```
+
+### Adding Additional Vite Plugins
+
+```typescript
+import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
+import { defineConfig } from "vite";
+import UnoCSS from "unocss/vite";
+
+export default viteConfig({
+  vite: {
+    plugins: [
+      UnoCSS(), // Add UnoCSS plugin
+    ],
+  },
+});
+```
+
+### Adding Additional Rsbuild Plugins
+
+```typescript
+import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
+import { pluginSass } from "@rsbuild/plugin-sass";
+
+export default rsbuildConfig({
+  rsbuild: {
+    plugins: [
+      pluginSass(), // Add Sass plugin
+    ],
+  },
+});
+```
+
+### Custom Plugin Manifest Path
+
+```typescript
+import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
+
+export default viteConfig({
+  manifestPath: "application/src/main/resources/plugin.yaml", // Custom manifest file path
+  vite: {
+    // Other configurations...
+  },
+});
+```
+
+## Development Scripts
+
+Recommended scripts to add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev --mode=development --watch",
+    "build": "vite build"
+  }
+}
+```
+
+For Rsbuild:
+
+```json
+{
+  "scripts": {
+    "dev": "rsbuild dev --env-mode=development --watch",
+    "build": "rsbuild build"
+  }
+}
+```
+
+## Build Output
+
+> Relative to the root directory of the Halo plugin project
+
+- **Development**: `build/resources/main/console`
+- **Production**: `ui/build/dist`
+
+> **Note**: The production build output directory of `HaloUIPluginBundlerKit` is still `src/main/resources/console` to ensure compatibility.
+
+## Requirements
+
+- **Node.js**: ^18.0.0 || >=20.0.0
+- **Peer Dependencies**:
+  - `@rsbuild/core`: ^1.0.0 (when using Rsbuild)
+  - `@rsbuild/plugin-vue`: ^1.0.0 (when using Rsbuild)
+  - `@vitejs/plugin-vue`: ^4.0.0 || ^5.0.0 (when using Vite)
+  - `vite`: ^4.0.0 || ^5.0.0 || ^6.0.0 (when using Vite)
+
+## Vite vs Rsbuild
+
+Both Vite and Rsbuild are excellent build tools, but they have different strengths depending on your use case:
+
+### When to Use Rsbuild
+
+**Recommended for large-scale plugins**
+
+- ✅ **Code Splitting Support** - Rsbuild provides excellent support for code splitting and lazy loading
+- ✅ **Better Performance** - Generally faster build times and smaller bundle sizes for complex applications
+- ✅ **Dynamic Imports** - Perfect for plugins with heavy frontend components
+
+**Example with dynamic imports:**
+
+```typescript
+import { definePlugin } from "@halo-dev/console-shared";
+import { defineAsyncComponent } from "vue";
+import { VLoading } from "@halo-dev/components";
+
+export default definePlugin({
+  routes: [
+    {
+      parentName: "Root",
+      route: {
+        path: "demo",
+        name: "DemoPage",
+        // Lazy load heavy components
+        component: defineAsyncComponent({
+          loader: () => import("./views/DemoPage.vue"),
+          loadingComponent: VLoading,
+        }),
+      },
+    },
+  ],
+  extensionPoints: {},
+});
+```
+
+### When to Use Vite
+
+**Recommended for simple to medium-scale plugins**
+
+- ✅ **Vue Ecosystem Friendly** - Better integration with Vue ecosystem tools and plugins
+- ✅ **Rich Plugin Ecosystem** - Extensive collection of Vite plugins available
+- ✅ **Simple Configuration** - Easier to configure for straightforward use cases
+
+### Summary
+
+| Feature           | Vite         | Rsbuild      |
+| ----------------- | ------------ | ------------ |
+| Code Splitting    | ❌ Limited   | ✅ Excellent |
+| Vue Ecosystem     | ✅ Excellent | ✅ Good      |
+| Build Performance | ✅ Good      | ✅ Excellent |
+| Dev Experience    | ✅ Excellent | ✅ Excellent |
+| Plugin Ecosystem  | ✅ Rich      | ✅ Growing   |
+| Configuration     | ✅ Simple    | ⚖️ Moderate  |
+
+**Recommendation**: Use **Rsbuild** for complex plugins with large frontend codebases, and **Vite** for simpler plugins or when you need extensive Vue ecosystem integration.
+
+## License
+
+GPL-3.0
+
+## Contributing
+
+Issues and Pull Requests are welcome! Please check our [Contributing Guide](https://github.com/halo-dev/halo/blob/main/CONTRIBUTING.md) for more information.
+
+## Related Links
+
+- [Halo Website](https://www.halo.run/)
+- [Halo Documentation](https://docs.halo.run/)
+- [GitHub Repository](https://github.com/halo-dev/halo)
+- [Plugin Development Guide](https://docs.halo.run/category/ui)

package/dist/index.d.ts

@@ -1,12 +1,77 @@
-import { Plugin } from 'vite';
+import { ConfigParams, RsbuildConfig } from "@rsbuild/core";
+import { Plugin, UserConfig, UserConfigFnObject } from "vite";
 
+//#region src/legacy.d.ts
 interface HaloUIPluginBundlerKitOptions {
-    outDir?: string | {
-        dev: string;
-        prod: string;
-    };
-    manifestPath?: string;
+  outDir?: string | {
+    dev: string;
+    prod: string;
+  };
+  manifestPath?: string;
 }
+/**
+ * @deprecated Use `viteConfig` or `rsbuildConfig` instead.
+ */
 declare function HaloUIPluginBundlerKit(options?: HaloUIPluginBundlerKitOptions): Plugin;
-
-export { HaloUIPluginBundlerKit };
+//#endregion
+//#region src/rsbuild.d.ts
+interface RsBuildUserConfig {
+  /**
+   * Halo plugin manifest path.
+   *
+   * @default "../src/main/resources/plugin.yaml"
+   */
+  manifestPath?: string;
+  /**
+   * Custom Rsbuild config.
+   */
+  rsbuild: RsbuildConfig | ((env: ConfigParams) => RsbuildConfig);
+}
+/**
+ * Rsbuild config for Halo UI Plugin.
+ *
+ * @example
+ * ```ts
+ * import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
+ *
+ * export default rsbuildConfig({
+ *   rsbuild: {
+ *     // your custom rsbuild config
+ *   },
+ * });
+ * ```
+ * @param config
+ * @returns
+ */
+declare function rsbuildConfig(config?: RsBuildUserConfig): (env: ConfigParams) => RsbuildConfig;
+//#endregion
+//#region src/vite.d.ts
+interface ViteUserConfig {
+  /**
+   * Halo plugin manifest path.
+   *
+   * @default "../src/main/resources/plugin.yaml"
+   */
+  manifestPath?: string;
+  /**
+   * Custom Vite config.
+   */
+  vite: UserConfig | UserConfigFnObject;
+}
+/**
+ * Vite config for Halo UI Plugin.
+ *
+ * @example
+ * ```ts
+ * import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
+ *
+ * export default viteConfig({
+ *   vite: {
+ *     // your custom vite config
+ *   },
+ * });
+ * ```
+ */
+declare function viteConfig(config?: ViteUserConfig): UserConfigFnObject;
+//#endregion
+export { HaloUIPluginBundlerKit, rsbuildConfig, viteConfig };

package/dist/index.js

@@ -0,0 +1,218 @@
+import fs from "fs";
+import yaml from "js-yaml";
+import { defineConfig, mergeRsbuildConfig } from "@rsbuild/core";
+import { pluginVue } from "@rsbuild/plugin-vue";
+import Vue from "@vitejs/plugin-vue";
+import { defineConfig as defineConfig$1, mergeConfig } from "vite";
+
+//#region src/constants/build.ts
+const DEFAULT_OUT_DIR_DEV = "../build/resources/main/console";
+const DEFAULT_OUT_DIR_PROD = "./build/dist";
+
+//#endregion
+//#region src/constants/externals.ts
+const GLOBALS = {
+	vue: "Vue",
+	"vue-router": "VueRouter",
+	"@vueuse/core": "VueUse",
+	"@vueuse/components": "VueUse",
+	"@vueuse/router": "VueUse",
+	"@halo-dev/console-shared": "HaloConsoleShared",
+	"@halo-dev/components": "HaloComponents",
+	"@halo-dev/api-client": "HaloApiClient",
+	"@halo-dev/richtext-editor": "RichTextEditor",
+	axios: "axios"
+};
+const EXTERNALS = Object.keys(GLOBALS);
+
+//#endregion
+//#region src/constants/halo-plugin.ts
+const DEFAULT_MANIFEST_PATH = "../src/main/resources/plugin.yaml";
+
+//#endregion
+//#region src/utils/halo-plugin.ts
+function getHaloPluginManifest(manifestPath) {
+	const manifest = yaml.load(fs.readFileSync(manifestPath, "utf8"));
+	return manifest;
+}
+
+//#endregion
+//#region src/legacy.ts
+const LEGACY_OUT_DIR_PROD = "../src/main/resources/console";
+/**
+* @deprecated Use `viteConfig` or `rsbuildConfig` instead.
+*/
+function HaloUIPluginBundlerKit(options = {}) {
+	return {
+		name: "halo-ui-plugin-bundler-kit",
+		config(config, env) {
+			const isProduction = env.mode === "production";
+			let outDir = isProduction ? LEGACY_OUT_DIR_PROD : DEFAULT_OUT_DIR_DEV;
+			if (options.outDir) if (typeof options.outDir === "string") outDir = options.outDir;
+			else outDir = isProduction ? options.outDir.prod : options.outDir.dev;
+			const manifestPath = options.manifestPath || DEFAULT_MANIFEST_PATH;
+			const manifest = getHaloPluginManifest(manifestPath);
+			return {
+				...config,
+				define: { "process.env": process.env },
+				build: {
+					outDir,
+					emptyOutDir: true,
+					lib: {
+						entry: "src/index.ts",
+						name: manifest.metadata.name,
+						formats: ["iife"],
+						fileName: () => "main.js"
+					},
+					rollupOptions: {
+						external: EXTERNALS,
+						output: {
+							globals: GLOBALS,
+							extend: true
+						}
+					}
+				}
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/rsbuild.ts
+function createRsbuildPresetsConfig(manifestPath) {
+	const manifest = getHaloPluginManifest(manifestPath);
+	return defineConfig(({ envMode }) => {
+		const isProduction = envMode === "production";
+		const outDir = isProduction ? DEFAULT_OUT_DIR_PROD : DEFAULT_OUT_DIR_DEV;
+		return {
+			mode: envMode || "production",
+			plugins: [pluginVue()],
+			source: { entry: { main: "./src/index.ts" } },
+			dev: { hmr: false },
+			performance: { chunkSplit: { strategy: "custom" } },
+			tools: {
+				rspack: {
+					optimization: {
+						splitChunks: { chunks: "async" },
+						moduleIds: "named"
+					},
+					experiments: { rspackFuture: { bundlerInfo: { force: false } } },
+					module: { parser: { javascript: { importMeta: false } } },
+					output: {
+						publicPath: `/plugins/${manifest.metadata.name}/assets/console/`,
+						library: {
+							type: "window",
+							export: "default",
+							name: manifest.metadata.name
+						},
+						globalObject: "window",
+						iife: true
+					}
+				},
+				htmlPlugin: false
+			},
+			output: {
+				distPath: {
+					root: outDir,
+					js: "",
+					css: "",
+					jsAsync: "chunks",
+					cssAsync: "chunks"
+				},
+				cleanDistPath: true,
+				filename: {
+					css: (pathData) => {
+						if (pathData.chunk?.name === "main") return "style.css";
+						return "[name].[contenthash:8].css";
+					},
+					js: (pathData) => {
+						if (pathData.chunk?.name === "main") return "main.js";
+						return "[name].[contenthash:8].js";
+					}
+				},
+				externals: GLOBALS
+			}
+		};
+	});
+}
+/**
+* Rsbuild config for Halo UI Plugin.
+*
+* @example
+* ```ts
+* import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit";
+*
+* export default rsbuildConfig({
+*   rsbuild: {
+*     // your custom rsbuild config
+*   },
+* });
+* ```
+* @param config
+* @returns
+*/
+function rsbuildConfig(config) {
+	const presetsConfigFn = createRsbuildPresetsConfig(config?.manifestPath || DEFAULT_MANIFEST_PATH);
+	return defineConfig((env) => {
+		const presetsConfig = presetsConfigFn(env);
+		const userConfig = typeof config?.rsbuild === "function" ? config.rsbuild(env) : config?.rsbuild || {};
+		return mergeRsbuildConfig(presetsConfig, userConfig);
+	});
+}
+
+//#endregion
+//#region src/vite.ts
+function createVitePresetsConfig(manifestPath) {
+	const manifest = getHaloPluginManifest(manifestPath);
+	return defineConfig$1(({ mode }) => {
+		const isProduction = mode === "production";
+		return {
+			mode: mode || "production",
+			plugins: [Vue()],
+			define: { "process.env.NODE_ENV": "'production'" },
+			build: {
+				outDir: isProduction ? DEFAULT_OUT_DIR_PROD : DEFAULT_OUT_DIR_DEV,
+				emptyOutDir: true,
+				lib: {
+					entry: "src/index.ts",
+					name: manifest.metadata.name,
+					formats: ["iife"],
+					fileName: () => "main.js",
+					cssFileName: "style"
+				},
+				rollupOptions: {
+					external: EXTERNALS,
+					output: {
+						globals: GLOBALS,
+						extend: true
+					}
+				}
+			}
+		};
+	});
+}
+/**
+* Vite config for Halo UI Plugin.
+*
+* @example
+* ```ts
+* import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit";
+*
+* export default viteConfig({
+*   vite: {
+*     // your custom vite config
+*   },
+* });
+* ```
+*/
+function viteConfig(config) {
+	const presetsConfigFn = createVitePresetsConfig(config?.manifestPath || DEFAULT_MANIFEST_PATH);
+	return defineConfig$1((env) => {
+		const presetsConfig = presetsConfigFn(env);
+		const userConfig = typeof config?.vite === "function" ? config.vite(env) : config?.vite || {};
+		return mergeConfig(presetsConfig, userConfig);
+	});
+}
+
+//#endregion
+export { HaloUIPluginBundlerKit, rsbuildConfig, viteConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halo-dev/ui-plugin-bundler-kit",
-  "version": "2.21.0",
+  "version": "2.21.2",
   "homepage": "https://github.com/halo-dev/halo/tree/main/ui/packages/ui-plugin-bundler-kit#readme",
   "bugs": {
     "url": "https://github.com/halo-dev/halo/issues"
@@ -12,33 +12,32 @@
   },
   "license": "GPL-3.0",
   "author": "@halo-dev",
+  "type": "module",
   "exports": {
-    ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
-    }
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
+  "dependencies": {
     "js-yaml": "^4.1.0",
-    "unbuild": "^0.7.6",
-    "@halo-dev/api-client": "2.21.0"
+    "@halo-dev/api-client": "2.21.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9"
   },
   "peerDependencies": {
-    "vite": "^4.0.0 || ^5.0.0"
+    "@rsbuild/core": "^1.0.0",
+    "@rsbuild/plugin-vue": "^1.0.0",
+    "@vitejs/plugin-vue": "^5.0.0 || ^6.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "engines": {
     "node": "^18.0.0 || >=20.0.0"
   },
   "scripts": {
-    "build": "unbuild",
-    "dev": "unbuild --stub"
+    "build": "tsdown",
+    "dev": "tsdown --watch"
   }
 }

package/src/constants/build.ts

@@ -0,0 +1,4 @@
+const DEFAULT_OUT_DIR_DEV = "../build/resources/main/console";
+const DEFAULT_OUT_DIR_PROD = "./build/dist";
+
+export { DEFAULT_OUT_DIR_DEV, DEFAULT_OUT_DIR_PROD };