@halo-dev/ui-plugin-bundler-kit 2.23.0 → 2.25.0

package/src/__tests__/provider.spec.ts

@@ -0,0 +1,301 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { ConfigParams, RsbuildConfig } from "@rsbuild/core";
+import type { ConfigEnv, UserConfig } from "vite";
+import { afterEach, describe, expect, it } from "vitest";
+import { rsbuildConfig } from "../rsbuild";
+import { viteConfig } from "../vite";
+
+const originalCwd = process.cwd();
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  while (tempDirs.length > 0) {
+    const tempDir = tempDirs.pop();
+    if (tempDir) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+});
+
+describe("provider defaults", () => {
+  it("keeps plugin provider defaults when provider is omitted", () => {
+    const uiDir = setupPluginProject();
+    process.chdir(uiDir);
+
+    const vite = resolveViteConfig(viteConfig({ vite: {} }), "development");
+    expect(vite.base).toBeUndefined();
+    expect(vite.build?.outDir).toBe("../build/resources/main/ui");
+    expect(vite.build?.lib).toMatchObject({
+      entry: "src/index.ts",
+      name: "fake-plugin",
+      formats: ["iife"],
+      cssFileName: "style",
+    });
+
+    const rsbuild = resolveRsbuildConfig(
+      rsbuildConfig({ rsbuild: {} }),
+      "development"
+    );
+    expect(rsbuild.output?.distPath?.root).toBe("../build/resources/main/ui");
+    expect(rsbuild.tools?.rspack?.output?.publicPath).toBe(
+      "/plugins/fake-plugin/assets/ui/"
+    );
+    expect(rsbuild.tools?.rspack?.output?.library).toMatchObject({
+      type: "window",
+      export: "default",
+      name: "fake-plugin",
+    });
+
+    const productionVite = resolveViteConfig(viteConfig({ vite: {} }));
+    expect(productionVite.build?.outDir).toBe("./build/dist");
+
+    const productionRsbuild = resolveRsbuildConfig(
+      rsbuildConfig({ rsbuild: {} })
+    );
+    expect(productionRsbuild.output?.distPath?.root).toBe("./build/dist");
+  });
+
+  it("keeps plugin provider defaults when provider is explicit", () => {
+    const uiDir = setupPluginProject();
+    process.chdir(uiDir);
+
+    const vite = resolveViteConfig(
+      viteConfig({ provider: "plugin", vite: {} }),
+      "development"
+    );
+    expect(vite.build?.outDir).toBe("../build/resources/main/ui");
+
+    const rsbuild = resolveRsbuildConfig(
+      rsbuildConfig({ provider: "plugin", rsbuild: {} }),
+      "development"
+    );
+    expect(rsbuild.tools?.rspack?.output?.publicPath).toBe(
+      "/plugins/fake-plugin/assets/ui/"
+    );
+  });
+
+  it("uses custom manifest paths for plugin and theme providers", () => {
+    const projectRoot = createTempDir();
+    const pluginManifestPath = path.join(projectRoot, "custom-plugin.yaml");
+    const themeManifestPath = path.join(projectRoot, "custom-theme.yaml");
+    fs.writeFileSync(
+      pluginManifestPath,
+      [
+        "metadata:",
+        "  name: custom-plugin",
+        "spec:",
+        "  requires: '>=2.25.0'",
+        "",
+      ].join("\n")
+    );
+    fs.writeFileSync(
+      themeManifestPath,
+      ["metadata:", "  name: custom-theme", ""].join("\n")
+    );
+
+    const pluginConfig = resolveViteConfig(
+      viteConfig({
+        manifestPath: pluginManifestPath,
+        vite: {},
+      })
+    );
+    expect(pluginConfig.build?.lib).toMatchObject({
+      name: "custom-plugin",
+    });
+
+    const themeConfig = resolveRsbuildConfig(
+      rsbuildConfig({
+        provider: "theme",
+        manifestPath: themeManifestPath,
+        rsbuild: {},
+      })
+    );
+    expect(themeConfig.tools?.rspack?.output?.publicPath).toBe(
+      "/themes/custom-theme/ui-plugin/assets/"
+    );
+    expect(themeConfig.tools?.rspack?.output?.library).toMatchObject({
+      name: "theme:custom-theme",
+    });
+  });
+
+  it("generates Vite theme provider defaults", () => {
+    const uiPluginDir = setupThemeProject();
+    process.chdir(uiPluginDir);
+
+    const config = resolveViteConfig(
+      viteConfig({ provider: "theme", vite: {} })
+    );
+
+    expect(config.base).toBe("/themes/earth/ui-plugin/assets/");
+    expect(config.build?.outDir).toBe("dist");
+    expect(config.build?.lib).toMatchObject({
+      entry: "src/index.ts",
+      name: "theme:earth",
+      formats: ["iife"],
+      cssFileName: "style",
+    });
+    expect(config.build?.rollupOptions?.external).toContain("vue");
+    expect(config.build?.rollupOptions?.output).toMatchObject({
+      globals: expect.objectContaining({
+        vue: "Vue",
+      }),
+      extend: true,
+    });
+  });
+
+  it("generates Rsbuild theme provider defaults", () => {
+    const uiPluginDir = setupThemeProject();
+    process.chdir(uiPluginDir);
+
+    const config = resolveRsbuildConfig(
+      rsbuildConfig({ provider: "theme", rsbuild: {} })
+    );
+
+    expect(config.output?.distPath?.root).toBe("dist");
+    expect(config.output?.filename?.js).toBeDefined();
+    expect(config.output?.filename?.css).toBeDefined();
+    expect(config.output?.externals).toMatchObject({
+      vue: "Vue",
+    });
+    expect(config.tools?.rspack?.output?.publicPath).toBe(
+      "/themes/earth/ui-plugin/assets/"
+    );
+    expect(config.tools?.rspack?.output?.library).toMatchObject({
+      type: "window",
+      export: "default",
+      name: "theme:earth",
+    });
+  });
+
+  it("merges user config after provider defaults", () => {
+    const uiPluginDir = setupThemeProject();
+    process.chdir(uiPluginDir);
+
+    const vite = resolveViteConfig(
+      viteConfig({
+        provider: "theme",
+        vite: {
+          base: "/custom/",
+          build: {
+            outDir: "custom-dist",
+          },
+        },
+      })
+    );
+    expect(vite.base).toBe("/custom/");
+    expect(vite.build?.outDir).toBe("custom-dist");
+
+    const rsbuild = resolveRsbuildConfig(
+      rsbuildConfig({
+        provider: "theme",
+        rsbuild: {
+          output: {
+            distPath: {
+              root: "custom-dist",
+            },
+          },
+          tools: {
+            rspack: {
+              output: {
+                publicPath: "/custom/",
+              },
+            },
+          },
+        },
+      })
+    );
+    expect(rsbuild.output?.distPath?.root).toBe("custom-dist");
+    expect(rsbuild.tools?.rspack?.output?.publicPath).toBe("/custom/");
+  });
+
+  it("merges function user config after provider defaults", () => {
+    const uiPluginDir = setupThemeProject();
+    process.chdir(uiPluginDir);
+
+    const vite = resolveViteConfig(
+      viteConfig({
+        provider: "theme",
+        vite: ({ mode }) => ({
+          define: {
+            __MODE__: JSON.stringify(mode),
+          },
+        }),
+      })
+    );
+    expect(vite.define).toMatchObject({
+      "process.env.NODE_ENV": "'production'",
+      __MODE__: '"production"',
+    });
+
+    const rsbuild = resolveRsbuildConfig(
+      rsbuildConfig({
+        provider: "theme",
+        rsbuild: ({ envMode }) => ({
+          output: {
+            filename: {
+              js: `custom-${envMode}.js`,
+            },
+          },
+        }),
+      })
+    );
+    expect(rsbuild.output?.filename?.js).toBe("custom-production.js");
+  });
+});
+
+function setupPluginProject() {
+  const projectRoot = createTempDir();
+  const uiDir = path.join(projectRoot, "ui");
+  fs.mkdirSync(path.join(projectRoot, "src/main/resources"), {
+    recursive: true,
+  });
+  fs.mkdirSync(uiDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, "src/main/resources/plugin.yaml"),
+    [
+      "metadata:",
+      "  name: fake-plugin",
+      "spec:",
+      "  requires: '>=2.25.0'",
+      "",
+    ].join("\n")
+  );
+  return uiDir;
+}
+
+function setupThemeProject() {
+  const projectRoot = createTempDir();
+  const uiPluginDir = path.join(projectRoot, "ui-plugin");
+  fs.mkdirSync(uiPluginDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, "theme.yaml"),
+    ["metadata:", "  name: earth", ""].join("\n")
+  );
+  return uiPluginDir;
+}
+
+function createTempDir() {
+  const tempDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), "halo-ui-plugin-bundler-kit-")
+  );
+  tempDirs.push(tempDir);
+  return tempDir;
+}
+
+function resolveViteConfig(config: unknown, mode = "production") {
+  return (config as (env: ConfigEnv) => UserConfig)({
+    command: "build",
+    mode,
+    isSsrBuild: false,
+    isPreview: false,
+  });
+}
+
+function resolveRsbuildConfig(config: unknown, envMode = "production") {
+  return (config as (env: ConfigParams) => RsbuildConfig)({
+    envMode,
+  } as ConfigParams);
+}

package/src/constants/build.ts

@@ -1,4 +1,15 @@
 const DEFAULT_OUT_DIR_DEV = "../build/resources/main/console";
+const DEFAULT_OUT_DIR_DEV_BASE = "../build/resources/main";
 const DEFAULT_OUT_DIR_PROD = "./build/dist";
+const DEFAULT_THEME_OUT_DIR = "dist";
 
-export { DEFAULT_OUT_DIR_DEV, DEFAULT_OUT_DIR_PROD };
+function getDefaultOutDirDev(bundleLocation: string) {
+  return `${DEFAULT_OUT_DIR_DEV_BASE}/${bundleLocation}`;
+}
+
+export {
+  DEFAULT_OUT_DIR_DEV,
+  DEFAULT_OUT_DIR_PROD,
+  DEFAULT_THEME_OUT_DIR,
+  getDefaultOutDirDev,
+};

package/src/constants/externals.ts

@@ -9,6 +9,7 @@ const GLOBALS = {
   "@halo-dev/components": "HaloComponents",
   "@halo-dev/api-client": "HaloApiClient",
   "@halo-dev/richtext-editor": "RichTextEditor",
+  "@formkit/vue": "FormKitVue",
   axios: "axios",
 };
 

package/src/constants/halo-plugin.ts

@@ -1,3 +1,9 @@
-const DEFAULT_MANIFEST_PATH = "../src/main/resources/plugin.yaml";
+const DEFAULT_PLUGIN_MANIFEST_PATH = "../src/main/resources/plugin.yaml";
+const DEFAULT_THEME_MANIFEST_PATH = "../theme.yaml";
+const DEFAULT_MANIFEST_PATH = DEFAULT_PLUGIN_MANIFEST_PATH;
 
-export { DEFAULT_MANIFEST_PATH };
+export {
+  DEFAULT_MANIFEST_PATH,
+  DEFAULT_PLUGIN_MANIFEST_PATH,
+  DEFAULT_THEME_MANIFEST_PATH,
+};

package/src/rsbuild.ts

@@ -6,16 +6,39 @@ import {
   type RsbuildMode,
 } from "@rsbuild/core";
 import { pluginVue } from "@rsbuild/plugin-vue";
-import { DEFAULT_OUT_DIR_DEV, DEFAULT_OUT_DIR_PROD } from "./constants/build";
+import {
+  DEFAULT_OUT_DIR_PROD,
+  DEFAULT_THEME_OUT_DIR,
+  getDefaultOutDirDev,
+} from "./constants/build";
 import { GLOBALS } from "./constants/externals";
-import { DEFAULT_MANIFEST_PATH } from "./constants/halo-plugin";
-import { getHaloPluginManifest } from "./utils/halo-plugin";
+import {
+  DEFAULT_PLUGIN_MANIFEST_PATH,
+  DEFAULT_THEME_MANIFEST_PATH,
+} from "./constants/halo-plugin";
+import {
+  getHaloPluginBundleLocation,
+  getHaloPluginManifest,
+  getHaloThemeAssetPublicPath,
+  getHaloThemeManifest,
+  getHaloThemeModuleName,
+  getManifestName,
+} from "./utils/halo-plugin";
+
+type Provider = "plugin" | "theme";
 
 export interface RsBuildUserConfig {
   /**
-   * Halo plugin manifest path.
+   * UI plugin provider type.
+   *
+   * @default "plugin"
+   */
+  provider?: "plugin" | "theme";
+
+  /**
+   * Halo plugin or theme manifest path.
    *
-   * @default "../src/main/resources/plugin.yaml"
+   * @default "../src/main/resources/plugin.yaml" for plugins, "../theme.yaml" for themes
    */
   manifestPath?: string;
 
@@ -25,13 +48,16 @@ export interface RsBuildUserConfig {
   rsbuild: RsbuildConfig | ((env: ConfigParams) => RsbuildConfig);
 }
 
-function createRsbuildPresetsConfig(manifestPath: string) {
-  const manifest = getHaloPluginManifest(manifestPath);
+function createRsbuildPresetsConfig(provider: Provider, manifestPath: string) {
+  const defaults =
+    provider === "theme"
+      ? getThemeProviderDefaults(manifestPath)
+      : getPluginProviderDefaults(manifestPath);
 
   return defineConfig(({ envMode }) => {
     const isProduction = envMode === "production";
 
-    const outDir = isProduction ? DEFAULT_OUT_DIR_PROD : DEFAULT_OUT_DIR_DEV;
+    const outDir = isProduction ? defaults.outDir.prod : defaults.outDir.dev;
 
     return {
       mode: (envMode as RsbuildMode) || "production",
@@ -72,11 +98,11 @@ function createRsbuildPresetsConfig(manifestPath: string) {
             },
           },
           output: {
-            publicPath: `/plugins/${manifest.metadata.name}/assets/console/`,
+            publicPath: defaults.publicPath,
             library: {
               type: "window",
               export: "default",
-              name: manifest.metadata.name,
+              name: defaults.moduleName,
             },
             globalObject: "window",
             iife: true,
@@ -113,6 +139,46 @@ function createRsbuildPresetsConfig(manifestPath: string) {
   });
 }
 
+function getPluginProviderDefaults(manifestPath: string) {
+  const manifest = getHaloPluginManifest(manifestPath);
+  const bundleLocation = getHaloPluginBundleLocation(manifest);
+
+  return {
+    moduleName: getManifestName(manifest),
+    outDir: {
+      prod: DEFAULT_OUT_DIR_PROD,
+      dev: getDefaultOutDirDev(bundleLocation),
+    },
+    publicPath: `/plugins/${getManifestName(manifest)}/assets/${bundleLocation}/`,
+  };
+}
+
+function getThemeProviderDefaults(manifestPath: string) {
+  const manifest = getHaloThemeManifest(manifestPath);
+
+  return {
+    moduleName: getHaloThemeModuleName(manifest),
+    outDir: {
+      prod: DEFAULT_THEME_OUT_DIR,
+      dev: DEFAULT_THEME_OUT_DIR,
+    },
+    publicPath: getHaloThemeAssetPublicPath(manifest),
+  };
+}
+
+function getProvider(config?: RsBuildUserConfig): Provider {
+  return config?.provider || "plugin";
+}
+
+function getManifestPath(provider: Provider, config?: RsBuildUserConfig) {
+  if (config?.manifestPath) {
+    return config.manifestPath;
+  }
+  return provider === "theme"
+    ? DEFAULT_THEME_MANIFEST_PATH
+    : DEFAULT_PLUGIN_MANIFEST_PATH;
+}
+
 /**
  * Rsbuild config for Halo UI Plugin.
  *
@@ -132,8 +198,10 @@ function createRsbuildPresetsConfig(manifestPath: string) {
 export function rsbuildConfig(
   config?: RsBuildUserConfig
 ): (env: ConfigParams) => RsbuildConfig {
+  const provider = getProvider(config);
   const presetsConfigFn = createRsbuildPresetsConfig(
-    config?.manifestPath || DEFAULT_MANIFEST_PATH
+    provider,
+    getManifestPath(provider, config)
   );
   return defineConfig((env) => {
     const presetsConfig = presetsConfigFn(env);

package/src/utils/halo-plugin.ts

@@ -1,11 +1,67 @@
 import fs from "node:fs";
 import type { Plugin as HaloPlugin } from "@halo-dev/api-client";
 import yaml from "js-yaml";
+import { gte, minVersion } from "semver";
+
+const UI_BUNDLE_MIN_HALO_VERSION = "2.25.0";
+const UI_BUNDLE_LOCATION = "ui";
+const CONSOLE_BUNDLE_LOCATION = "console";
+const THEME_MODULE_NAME_PREFIX = "theme:";
+
+interface HaloThemeManifest {
+  metadata: {
+    name: string;
+  };
+}
 
 export function getHaloPluginManifest(manifestPath: string) {
-  const manifest = yaml.load(
-    fs.readFileSync(manifestPath, "utf8")
-  ) as HaloPlugin;
+  return readManifest<HaloPlugin>(manifestPath);
+}
+
+export function getHaloThemeManifest(manifestPath: string) {
+  return readManifest<HaloThemeManifest>(manifestPath);
+}
+
+export function getManifestName(
+  manifest: Pick<HaloPlugin, "metadata"> | HaloThemeManifest
+) {
+  return manifest.metadata.name;
+}
+
+export function getHaloThemeModuleName(manifest: HaloThemeManifest) {
+  return `${THEME_MODULE_NAME_PREFIX}${getManifestName(manifest)}`;
+}
+
+export function getHaloThemeAssetPublicPath(manifest: HaloThemeManifest) {
+  return `/themes/${getManifestName(manifest)}/ui-plugin/assets/`;
+}
+
+export function getHaloPluginBundleLocation(manifest: HaloPlugin) {
+  const requiresMinVersion = getRequiresMinVersion(manifest.spec.requires);
+  return requiresMinVersion &&
+    gte(requiresMinVersion, UI_BUNDLE_MIN_HALO_VERSION)
+    ? UI_BUNDLE_LOCATION
+    : CONSOLE_BUNDLE_LOCATION;
+}
+
+function getRequiresMinVersion(requires: string | undefined) {
+  const normalizedRequires = requires?.trim();
+
+  if (!normalizedRequires) {
+    return;
+  }
+
+  try {
+    return minVersion(normalizedRequires);
+  } catch {
+    console.warn(
+      `[ui-plugin-bundler-kit] Invalid semver range in plugin manifest "spec.requires": "${requires}". ` +
+        `Falling back to "${CONSOLE_BUNDLE_LOCATION}" bundle location.`
+    );
+    return;
+  }
+}
 
-  return manifest;
+function readManifest<T>(manifestPath: string) {
+  return yaml.load(fs.readFileSync(manifestPath, "utf8")) as T;
 }

package/src/vite.ts

@@ -5,16 +5,39 @@ import {
   UserConfig,
   UserConfigFnObject,
 } from "vite";
-import { DEFAULT_OUT_DIR_DEV, DEFAULT_OUT_DIR_PROD } from "./constants/build";
+import {
+  DEFAULT_OUT_DIR_PROD,
+  DEFAULT_THEME_OUT_DIR,
+  getDefaultOutDirDev,
+} from "./constants/build";
 import { EXTERNALS, GLOBALS } from "./constants/externals";
-import { DEFAULT_MANIFEST_PATH } from "./constants/halo-plugin";
-import { getHaloPluginManifest } from "./utils/halo-plugin";
+import {
+  DEFAULT_PLUGIN_MANIFEST_PATH,
+  DEFAULT_THEME_MANIFEST_PATH,
+} from "./constants/halo-plugin";
+import {
+  getHaloPluginBundleLocation,
+  getHaloPluginManifest,
+  getHaloThemeAssetPublicPath,
+  getHaloThemeManifest,
+  getHaloThemeModuleName,
+  getManifestName,
+} from "./utils/halo-plugin";
+
+type Provider = "plugin" | "theme";
 
 export interface ViteUserConfig {
   /**
-   * Halo plugin manifest path.
+   * UI plugin provider type.
+   *
+   * @default "plugin"
+   */
+  provider?: "plugin" | "theme";
+
+  /**
+   * Halo plugin or theme manifest path.
    *
-   * @default "../src/main/resources/plugin.yaml"
+   * @default "../src/main/resources/plugin.yaml" for plugins, "../theme.yaml" for themes
    */
   manifestPath?: string;
 
@@ -24,22 +47,26 @@ export interface ViteUserConfig {
   vite: UserConfig | UserConfigFnObject;
 }
 
-function createVitePresetsConfig(manifestPath: string) {
-  const manifest = getHaloPluginManifest(manifestPath);
+function createVitePresetsConfig(provider: Provider, manifestPath: string) {
+  const defaults =
+    provider === "theme"
+      ? getThemeProviderDefaults(manifestPath)
+      : getPluginProviderDefaults(manifestPath);
 
   return defineConfig(({ mode }) => {
     const isProduction = mode === "production";
 
     return {
       mode: mode || "production",
+      base: defaults.base,
       plugins: [Vue()],
       define: { "process.env.NODE_ENV": "'production'" },
       build: {
-        outDir: isProduction ? DEFAULT_OUT_DIR_PROD : DEFAULT_OUT_DIR_DEV,
+        outDir: isProduction ? defaults.outDir.prod : defaults.outDir.dev,
         emptyOutDir: true,
         lib: {
           entry: "src/index.ts",
-          name: manifest.metadata.name,
+          name: defaults.moduleName,
           formats: ["iife"],
           fileName: () => "main.js",
           cssFileName: "style",
@@ -56,6 +83,46 @@ function createVitePresetsConfig(manifestPath: string) {
   });
 }
 
+function getPluginProviderDefaults(manifestPath: string) {
+  const manifest = getHaloPluginManifest(manifestPath);
+  const bundleLocation = getHaloPluginBundleLocation(manifest);
+
+  return {
+    moduleName: getManifestName(manifest),
+    outDir: {
+      prod: DEFAULT_OUT_DIR_PROD,
+      dev: getDefaultOutDirDev(bundleLocation),
+    },
+    base: undefined,
+  };
+}
+
+function getThemeProviderDefaults(manifestPath: string) {
+  const manifest = getHaloThemeManifest(manifestPath);
+
+  return {
+    moduleName: getHaloThemeModuleName(manifest),
+    outDir: {
+      prod: DEFAULT_THEME_OUT_DIR,
+      dev: DEFAULT_THEME_OUT_DIR,
+    },
+    base: getHaloThemeAssetPublicPath(manifest),
+  };
+}
+
+function getProvider(config?: ViteUserConfig): Provider {
+  return config?.provider || "plugin";
+}
+
+function getManifestPath(provider: Provider, config?: ViteUserConfig) {
+  if (config?.manifestPath) {
+    return config.manifestPath;
+  }
+  return provider === "theme"
+    ? DEFAULT_THEME_MANIFEST_PATH
+    : DEFAULT_PLUGIN_MANIFEST_PATH;
+}
+
 /**
  * Vite config for Halo UI Plugin.
  *
@@ -71,8 +138,10 @@ function createVitePresetsConfig(manifestPath: string) {
  * ```
  */
 export function viteConfig(config?: ViteUserConfig) {
+  const provider = getProvider(config);
   const presetsConfigFn = createVitePresetsConfig(
-    config?.manifestPath || DEFAULT_MANIFEST_PATH
+    provider,
+    getManifestPath(provider, config)
   );
   return defineConfig((env) => {
     const presetsConfig = presetsConfigFn(env);

package/vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "vite-plus";
+export default defineConfig({
+  pack: {
+    entry: ["./src/index.ts"],
+    format: ["esm"],
+    dts: {
+      tsgo: true,
+    },
+    exports: true,
+  },
+});