@hitachivantara/app-shell-vite-plugin 2.3.0 → 2.4.0

package/dist/automatic-utils.js

@@ -62,7 +62,7 @@ export function mapFolderIndexFilesToRoutes(root, viewsFolder) {
             .replaceAll(/\$/g, ":")
             .toLowerCase();
         const viewConfig = {
-            bundle: `@self/${getFinalModuleName(bundle)}.js`,
+            bundle: `$app/${getFinalModuleName(bundle)}.js`,
             route,
         };
         routes.push({ viewConfig, module: bundle });
@@ -102,11 +102,15 @@ export function applyAutomaticViewsAndRoutes(config, selfAppName, root, viewsFol
         const flattenedViews = flattenViews(appShellConfiguration.mainPanel.views);
         const existingRoutes = flattenedViews.map((view) => view.route);
         const existingBundles = flattenedViews.reduce((bundles, view) => {
-            if (view.bundle.startsWith("@self/")) {
+            if (view.bundle.startsWith("$app/")) {
                 bundles.push(view.bundle);
             }
+            else if (view.bundle.startsWith("@self/")) {
+                // TODO(major): remove @self/ support in favour of $app/
+                bundles.push(view.bundle.replace("@self/", "$app/"));
+            }
             else if (view.bundle.startsWith(selfAppName)) {
-                bundles.push(view.bundle.replace(selfAppName, "@self"));
+                bundles.push(view.bundle.replace(selfAppName, "$app"));
             }
             return bundles;
         }, []);

package/dist/nodeModule.d.ts

@@ -6,4 +6,4 @@ export declare const require: NodeJS.Require;
  * @param suffix to be added after the module path
  * @returns The module path normalized
  */
-export declare function resolveModule(moduleName: string, suffix?: string): string;
+export declare function resolveModule(moduleName: string, suffix?: string): any;

package/dist/vite-configuration-processor-plugin.d.ts

@@ -1,16 +1,30 @@
 import type { PluginOption } from "vite";
 import type { HvAppShellConfig } from "@hitachivantara/app-shell-shared";
+/**
+ * Options for the configuration processor plugin.
+ */
+export interface ProcessConfigurationOptions {
+    /** Project root directory. */
+    root: string;
+    /** The original App Shell configuration json. */
+    appShellConfig: HvAppShellConfig;
+    /** The name of the application bundle being built. */
+    selfAppName: string;
+    /** The set of modules to be created by the rollup. */
+    modules: string[];
+    /** If true, the index.html entry point will be added to the bundle. */
+    buildEntryPoint: boolean;
+    /** Flag to control if config is included at index.html. */
+    inlineConfig: boolean;
+    /** Flag to control if we are creating an empty AppShell instance. */
+    generateEmptyShell: boolean;
+    /** If true, always writes app-shell.config.json to dist for dual-use packages. */
+    experimentalNewPackageLayout: boolean;
+}
 /**
  * Process configuration, executing several tasks:
  *  - Create rollup configuration to support module creation
  *  - Generates final transformed configuration json
  *  - "base" value is always "./" for build, and main app baseUrl for preview or dev
- * @param root Project root directory.
- * @param appShellConfig The original App Shell configuration json.
- * @param selfAppName The name of the application bundle being built.
- * @param buildEntryPoint If true, the index.html entry point will be added to the bundle.
- * @param inlineConfig flag to control if config is included at index.html
- * @param generateEmptyShell flag to control if we are creating an empty AppShell instance
- * @param modules the set of modules to be created by the rollup
  */
-export default function processConfiguration(root: string, appShellConfig: HvAppShellConfig, selfAppName: string, buildEntryPoint: boolean, inlineConfig: boolean, generateEmptyShell: boolean, modules?: string[]): PluginOption;
+export default function processConfiguration(options: ProcessConfigurationOptions): PluginOption;

package/dist/vite-configuration-processor-plugin.js

@@ -7,15 +7,9 @@ import sharedDependencies from "./shared-dependencies.js";
  *  - Create rollup configuration to support module creation
  *  - Generates final transformed configuration json
  *  - "base" value is always "./" for build, and main app baseUrl for preview or dev
- * @param root Project root directory.
- * @param appShellConfig The original App Shell configuration json.
- * @param selfAppName The name of the application bundle being built.
- * @param buildEntryPoint If true, the index.html entry point will be added to the bundle.
- * @param inlineConfig flag to control if config is included at index.html
- * @param generateEmptyShell flag to control if we are creating an empty AppShell instance
- * @param modules the set of modules to be created by the rollup
  */
-export default function processConfiguration(root, appShellConfig, selfAppName, buildEntryPoint, inlineConfig, generateEmptyShell, modules = []) {
+export default function processConfiguration(options) {
+    const { root, appShellConfig, selfAppName, modules, buildEntryPoint, inlineConfig, generateEmptyShell, experimentalNewPackageLayout, } = options;
     let finalAppShellConfig;
     let basePath;
     return {
@@ -58,7 +52,7 @@ export default function processConfiguration(root, appShellConfig, selfAppName,
          * @param options build options
          */
         async generateBundle(options) {
-            if (generateEmptyShell || !buildEntryPoint) {
+            if (generateEmptyShell) {
                 return;
             }
             // obtain the directory (dist) where the new config file will be placed
@@ -82,11 +76,16 @@ export default function processConfiguration(root, appShellConfig, selfAppName,
                 finalAppShellConfig.baseUrl = basePath;
             }
             finalAppShellConfig.apps = undefined;
-            // Replace all @self references using simple string replacement
+            // Replace all $app and @self (deprecated) references using simple string replacement.
             let configString = JSON.stringify(finalAppShellConfig);
+            configString = configString.replaceAll(`"$app/`, `"${selfAppName}/`);
+            // TODO(major): remove @self/ support in favour of $app/
             configString = configString.replaceAll(`"@self/`, `"${selfAppName}/`);
             finalAppShellConfig = JSON.parse(configString);
-            if (!inlineConfig) {
+            // Write app-shell.config.json to dist when:
+            // - inlineConfig is false (standard flow), OR
+            // - experimentalNewPackageLayout is true (ensures dual-use: app shell or app bundle)
+            if (!inlineConfig || experimentalNewPackageLayout) {
                 fs.writeFileSync(path.resolve(targetDir, "app-shell.config.json"), JSON.stringify(finalAppShellConfig));
             }
         },

package/dist/vite-dist-package-json-plugin.d.ts

@@ -0,0 +1,5 @@
+import type { Plugin } from "vite";
+/**
+ * Generates a cleaned dist/package.json during Vite builds.
+ */
+export default function distPackageJsonPlugin(root?: string, sourceCondition?: string): Plugin;

package/dist/vite-dist-package-json-plugin.js

@@ -0,0 +1,211 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * Default custom export condition used internally by workspace packages
+ * to resolve TypeScript source during development.
+ *
+ * This condition must never leak into published artifacts because external
+ * consumers would not be able to resolve it.
+ */
+const DEFAULT_SOURCE_CONDITION = "@pentaho-apps:source";
+/**
+ * Runtime-relevant package.json fields copied into dist output.
+ *
+ * All other fields are intentionally excluded.
+ */
+const INCLUDED_FIELDS = [
+    "name",
+    "version",
+    "type",
+    "license",
+    "description",
+    "dependencies",
+    "peerDependencies",
+    "peerDependenciesMeta",
+    "optionalDependencies",
+];
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Reads and parses a JSON file.
+ *
+ * Returns `undefined` if the file does not exist or cannot be parsed.
+ */
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Removes the build output prefix from an export path.
+ *
+ * Example:
+ *   ./dist/index.js → ./index.js
+ */
+function stripDistPrefix(prefix, value) {
+    return value.startsWith(prefix) ? `./${value.slice(prefix.length)}` : value;
+}
+/**
+ * Transforms a package export target for dist/package.json.
+ *
+ * Processing rules:
+ *
+ * Strings:
+ * - Must resolve inside build.outDir
+ * - build.outDir prefix is stripped
+ *
+ * Objects:
+ * - Removes dev-only source condition
+ * - Recursively transforms nested targets
+ * - Removed if empty after transformation
+ *
+ * Arrays:
+ * - Node fallback arrays are eagerly collapsed to the first
+ *   valid non-null target because import maps do not support
+ *   Node conditional fallback resolution semantics.
+ *
+ * null:
+ * - Preserved as explicit export exclusion
+ *
+ * undefined:
+ * - Internal sentinel meaning "omit this entry"
+ */
+function transformExportTargetForDist(target, distPrefix, sourceCondition) {
+    // Explicit export exclusion must be preserved
+    if (target === null) {
+        return null;
+    }
+    // Direct export path
+    if (typeof target === "string") {
+        const stripped = stripDistPrefix(distPrefix, target);
+        // Ignore paths outside dist output
+        return stripped === target ? undefined : stripped;
+    }
+    // Fallback array
+    if (Array.isArray(target)) {
+        for (const entry of target) {
+            const resolved = transformExportTargetForDist(entry, distPrefix, sourceCondition);
+            if (resolved !== undefined && resolved !== null) {
+                return resolved;
+            }
+        }
+        return undefined;
+    }
+    // Conditional exports object
+    const result = {};
+    for (const [condition, value] of Object.entries(target)) {
+        // Remove workspace-only source condition
+        if (condition === sourceCondition) {
+            continue;
+        }
+        const transformed = transformExportTargetForDist(value, distPrefix, sourceCondition);
+        // Omitted targets disappear entirely
+        if (transformed === undefined) {
+            continue;
+        }
+        result[condition] = transformed;
+    }
+    return Object.keys(result).length === 0 ? undefined : result;
+}
+/**
+ * Normalizes package exports into canonical subpath map form.
+ *
+ * Converts:
+ *
+ *   "exports": "./index.js"
+ *   → { ".": "./index.js" }
+ *
+ *   "exports": { "import": "./index.js" }
+ *   → { ".": { "import": "./index.js" } }
+ *
+ * Leaves already-normalized subpath maps untouched.
+ */
+function normalizeExportsToSubpathMap(exportsField) {
+    if (exportsField == null) {
+        throw new Error(`[App Shell]: package.json is missing "exports".`);
+    }
+    // Sugar form:
+    // "exports": "./index.js"
+    // "exports": ["./a.js", "./b.js"]
+    if (typeof exportsField === "string" || Array.isArray(exportsField)) {
+        return { ".": exportsField };
+    }
+    const keys = Object.keys(exportsField);
+    // Already a subpath map
+    if (keys.every((key) => key.startsWith("."))) {
+        return exportsField;
+    }
+    // Root conditional exports sugar
+    return { ".": exportsField };
+}
+/**
+ * Appends standard metadata exports required at runtime.
+ */
+function appendStandardExports(exportsMap, outDir) {
+    exportsMap["./package.json"] = "./package.json";
+    exportsMap["./app-shell.config.json"] = "./app-shell.config.json";
+    if (fs.existsSync(path.join(outDir, "locales"))) {
+        exportsMap["./locales/*"] = "./locales/*";
+    }
+}
+// ─── Dist package.json generation ────────────────────────────────────────────
+/**
+ * Generates dist/package.json from the source package.
+ *
+ * The generated package:
+ * - strips dev-only export conditions
+ * - rewrites export paths relative to dist/
+ * - preserves explicit null exclusions
+ * - supports nested conditional exports
+ */
+function generateDistPackageJson(root, outDir, buildOutDir, sourceCondition) {
+    const pkgPath = path.join(root, "package.json");
+    const pkg = readJsonFile(pkgPath);
+    if (!pkg || !fs.existsSync(outDir)) {
+        return false;
+    }
+    const rawExports = pkg.exports;
+    const distPrefix = `./${buildOutDir}/`;
+    const transformedExports = transformExportTargetForDist(normalizeExportsToSubpathMap(rawExports), distPrefix, sourceCondition);
+    /**
+     * The entire exports tree may collapse after removing dev-only
+     * conditions and invalid dist targets.
+     */
+    if (transformedExports === undefined) {
+        throw new Error(`[App Shell] ${pkg.name}: exports resolved to empty after transformation.`);
+    }
+    appendStandardExports(transformedExports, outDir);
+    const distPkg = {};
+    // Copy runtime-relevant fields
+    for (const field of INCLUDED_FIELDS) {
+        if (pkg[field] != null) {
+            distPkg[field] = pkg[field];
+        }
+    }
+    distPkg.exports = transformedExports;
+    fs.writeFileSync(path.join(outDir, "package.json"), JSON.stringify(distPkg, null, 2) + "\n");
+    console.info(`[App Shell] Generated ${buildOutDir}/package.json for ${pkg.name}`);
+    return true;
+}
+// ─── Plugin ──────────────────────────────────────────────────────────────────
+/**
+ * Generates a cleaned dist/package.json during Vite builds.
+ */
+export default function distPackageJsonPlugin(root, sourceCondition = DEFAULT_SOURCE_CONDITION) {
+    let config;
+    return {
+        name: "app-shell:vite-dist-package-json-plugin",
+        apply: "build",
+        configResolved(resolved) {
+            config = resolved;
+        },
+        closeBundle() {
+            const packageRoot = root ?? config.root;
+            const outDir = path.resolve(packageRoot, config.build.outDir);
+            generateDistPackageJson(packageRoot, outDir, config.build.outDir, sourceCondition);
+        },
+    };
+}

package/dist/vite-plugin.d.ts

@@ -97,6 +97,42 @@ export interface AppShellVitePluginOptions {
      * @default false
      */
     disableAppsKeyNormalization?: boolean;
+    /**
+     * Enables the experimental new package layout feature set.
+     *
+     * When `true`, the plugin activates behaviors that are part of the
+     * new app bundle distribution/publishing package layout. Currently, this gates:
+     *
+     * - **`dist/package.json` generation** — a cleaned-up `package.json` is
+     *   written to the Vite output directory after each build. The source
+     *   `package.json` contains dev-time fields and conditions that do not apply
+     *   to published/distributed packages; the generated manifest only includes
+     *   the fields relevant to consumers.
+     * - **`dist/app-shell.config.json`** — the resolved App Shell configuration
+     *   is written to the output directory so that app bundles are self-contained
+     *   and can be consumed both as standalone App Shells or as bundles for
+     *   another App Shell.
+     *
+     * Additional behaviors may be added under this flag in future PRs before
+     * the feature set is stabilized and the flag is removed.
+     *
+     * @default false
+     * @experimental
+     */
+    experimentalNewPackageLayout?: boolean;
+    /**
+     * The custom exports condition used to resolve TypeScript source files during
+     * development. Only applies when `experimentalNewPackageLayout` is `true`.
+     *
+     * Workspace packages declare a scoped condition (e.g. `"@pentaho-apps:source"`)
+     * in their `exports` map that points directly at the TypeScript source. This
+     * lets consumers import the live source during development without a prior
+     * build step. The condition is stripped from `dist/package.json` so it never
+     * leaks to consumers that don't have the TypeScript sources available.
+     *
+     * @default "@pentaho-apps:source"
+     */
+    sourceCondition?: string;
 }
 /**
  * Vite plugin to support App Shell apps setup

package/dist/vite-plugin.js

@@ -10,6 +10,7 @@ import SHARED_DEPENDENCIES from "./shared-dependencies.js";
 import getVirtualEntrypoints from "./virtual-entrypoints.js";
 import processConfiguration from "./vite-configuration-processor-plugin.js";
 import fixCrossOrigin from "./vite-crossorigin-fix-plugin.js";
+import distPackageJsonPlugin from "./vite-dist-package-json-plugin.js";
 import generateBaseTag from "./vite-generate-base-plugin.js";
 import generateBashScript from "./vite-generate-bash-script-plugin.js";
 import generateImportmap, { extraDependencies, } from "./vite-importmap-plugin.js";
@@ -26,7 +27,7 @@ const ViteBuildMode = {
  * @param env Environment variable
  */
 export async function HvAppShellVitePlugin(opts = {}, env = {}) {
-    const { root = process.cwd(), mode = ViteBuildMode.PRODUCTION, externalImportMap = false, viewsFolder = "src/pages", autoViewsAndRoutes = false, autoMenu = false, inlineConfig = opts.generateEmptyShell ?? false, generateEmptyShell = false, modules = [], disableAppsKeyNormalization = false, } = opts;
+    const { root = process.cwd(), mode = ViteBuildMode.PRODUCTION, externalImportMap = false, viewsFolder = "src/pages", autoViewsAndRoutes = false, autoMenu = false, inlineConfig = opts.generateEmptyShell ?? false, generateEmptyShell = false, modules = [], disableAppsKeyNormalization = false, experimentalNewPackageLayout = false, sourceCondition, } = opts;
     const globalEnv = loadEnv(mode, process.cwd(), "");
     const { type = globalEnv.CI ? "bundle" : "app" } = opts;
     console.info(`Vite running in mode: ${mode}`);
@@ -112,7 +113,16 @@ export async function HvAppShellVitePlugin(opts = {}, env = {}) {
         buildEntryPoint &&
             generateBaseTag(appShellConfiguration, generateEmptyShell),
         // configure the build process based on the config file
-        processConfiguration(root, appShellConfiguration, packageJson.name, buildEntryPoint, inlineConfig, generateEmptyShell, modules.concat(autoViewsBundles)),
+        processConfiguration({
+            root,
+            appShellConfig: appShellConfiguration,
+            selfAppName: packageJson.name,
+            modules: modules.concat(autoViewsBundles),
+            buildEntryPoint,
+            inlineConfig,
+            generateEmptyShell,
+            experimentalNewPackageLayout,
+        }),
         // allow crossorigin="use-credentials" in the index.html
         fixCrossOrigin(),
         // serve the app shell config file as json and watch for changes
@@ -121,5 +131,8 @@ export async function HvAppShellVitePlugin(opts = {}, env = {}) {
         generateEmptyShell && generateBashScript(externalImportMap, inlineConfig),
         // copy/merge app-shell-ui locales into dist (build) or serve via middleware (dev)
         copyAppShellLocales(buildEntryPoint),
+        // generate dist/package.json for the build output directory
+        experimentalNewPackageLayout &&
+            distPackageJsonPlugin(root, sourceCondition),
     ];
 }

package/dist/vite-watch-config-plugin.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 const prepareConfigForDevMode = (config, selfAppName) => {
     let configString = JSON.stringify(config);
+    configString = configString.replaceAll(`"$app/`, `"${selfAppName}/`);
+    // TODO(major): remove @self/ support in favour of $app/
     configString = configString.replaceAll(`"@self/`, `"${selfAppName}/`);
     return JSON.parse(configString);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitachivantara/app-shell-vite-plugin",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "private": false,
   "author": "Hitachi Vantara UI Kit Team",
@@ -20,11 +20,10 @@
   "dependencies": {
     "@emotion/cache": "^11.11.0",
     "@emotion/react": "^11.11.1",
-    "@hitachivantara/app-shell-services": "^2.0.3",
-    "@hitachivantara/app-shell-shared": "^2.3.1",
-    "@hitachivantara/app-shell-ui": "^2.3.2",
-    "@hitachivantara/uikit-react-icons": "^6.0.4",
-    "@hitachivantara/uikit-react-shared": "^6.0.4",
+    "@hitachivantara/app-shell-services": "^2.0.4",
+    "@hitachivantara/app-shell-shared": "^2.3.2",
+    "@hitachivantara/app-shell-ui": "^2.3.3",
+    "@hitachivantara/uikit-react-shared": "^6.0.5",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
@@ -59,5 +58,5 @@
     },
     "./package.json": "./package.json"
   },
-  "gitHead": "333e132a9823018d508ebbe71c81d0b467f9008d"
+  "gitHead": "65c4f4394e8f8c7cccb58203e1c08c6832434638"
 }