@hitachivantara/app-shell-vite-plugin 2.2.1 → 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/locales-utils.d.ts

@@ -15,16 +15,20 @@ export declare function readSupportedLocales(filePath: string): string[];
  */
 export declare function discoverLanguageDirs(localesDir: string): string[];
 /**
- * Computes the merged supported-locales list respecting ordering:
+ * Computes the effective supported-locales list.
  *
- * 1. Entries from the **app's** `supported-locales.json` (in their original order).
- * 2. Entries from the **shell's** `supported-locales.json` not already listed
- *    (in their original order).
- * 3. Any language directories discovered on disk that are not in either
- *    manifest (alphabetical order).
+ * Discovers all language directories from both sources (upstream shell and
+ * local app). If the app provides a `supported-locales.json`, it acts as a
+ * **filter**: only locales listed there are kept. Otherwise all discovered
+ * locales are included.
  *
- * @param shellLocalesDir - The app-shell-ui locales directory (lower priority).
- * @param appLocalesDir   - The app's locales directory (higher priority).
+ * The result is always sorted alphabetically.
+ *
+ * Locales listed in the local manifest but without a matching language
+ * directory are warned about and dropped.
+ *
+ * @param shellLocalesDir - The app-shell-ui locales directory (upstream).
+ * @param appLocalesDir   - The app's locales directory (downstream / local).
  */
 export declare function computeSupportedLocales(shellLocalesDir: string | undefined, appLocalesDir: string | undefined): string[];
 /**
@@ -38,7 +42,11 @@ export declare function readJsonFile(filePath: string): unknown;
  * Non-JSON files are skipped (locale bundles are always JSON).
  *
  * `supported-locales.json` is skipped — it is handled separately after the
- * merge so it can reflect the union of both sources plus any discovered
- * language directories.
+ * merge so it can reflect the computed list.
+ *
+ * When `allowedLocales` is provided, only top-level directories whose name
+ * is in the set are merged; all others are skipped. This allows the app's
+ * `supported-locales.json` to act as a filter over upstream locale dirs.
+ * Sub-directories (namespace folders) are always merged recursively.
  */
-export declare function mergeDirs(src: string, dest: string): void;
+export declare function mergeDirs(src: string, dest: string, allowedLocales?: Set<string>): void;

package/dist/locales-utils.js

@@ -54,53 +54,23 @@ export function discoverLanguageDirs(localesDir) {
         .toSorted();
 }
 /**
- * Computes the merged supported-locales list respecting ordering:
+ * Computes the effective supported-locales list.
  *
- * 1. Entries from the **app's** `supported-locales.json` (in their original order).
- * 2. Entries from the **shell's** `supported-locales.json` not already listed
- *    (in their original order).
- * 3. Any language directories discovered on disk that are not in either
- *    manifest (alphabetical order).
+ * Discovers all language directories from both sources (upstream shell and
+ * local app). If the app provides a `supported-locales.json`, it acts as a
+ * **filter**: only locales listed there are kept. Otherwise all discovered
+ * locales are included.
  *
- * @param shellLocalesDir - The app-shell-ui locales directory (lower priority).
- * @param appLocalesDir   - The app's locales directory (higher priority).
+ * The result is always sorted alphabetically.
+ *
+ * Locales listed in the local manifest but without a matching language
+ * directory are warned about and dropped.
+ *
+ * @param shellLocalesDir - The app-shell-ui locales directory (upstream).
+ * @param appLocalesDir   - The app's locales directory (downstream / local).
  */
 export function computeSupportedLocales(shellLocalesDir, appLocalesDir) {
-    const seen = new Set();
-    const result = [];
-    const addUnique = (lng) => {
-        if (!seen.has(lng)) {
-            seen.add(lng);
-            result.push(lng);
-        }
-    };
-    // 1. App manifest entries first (highest priority order)
-    if (appLocalesDir) {
-        for (const lng of readSupportedLocales(path.join(appLocalesDir, SUPPORTED_LOCALES_FILE))) {
-            addUnique(lng);
-        }
-    }
-    // 2. Shell manifest entries that weren't already listed
-    if (shellLocalesDir) {
-        for (const lng of readSupportedLocales(path.join(shellLocalesDir, SUPPORTED_LOCALES_FILE))) {
-            addUnique(lng);
-        }
-    }
-    // 3. Discovered language directories not in either manifest (alphabetical)
-    const discoveredDirs = [];
-    for (const dir of [shellLocalesDir, appLocalesDir]) {
-        if (dir) {
-            for (const lng of discoverLanguageDirs(dir)) {
-                if (!seen.has(lng))
-                    discoveredDirs.push(lng);
-            }
-        }
-    }
-    // deduplicate and sort before appending
-    for (const lng of [...new Set(discoveredDirs)].toSorted()) {
-        addUnique(lng);
-    }
-    // Validate: warn and drop manifest entries without a matching language directory
+    // Collect all language directories that actually exist on disk
     const allDirs = new Set();
     for (const dir of [shellLocalesDir, appLocalesDir]) {
         if (dir) {
@@ -109,12 +79,33 @@ export function computeSupportedLocales(shellLocalesDir, appLocalesDir) {
             }
         }
     }
-    return result.filter((lng) => {
-        if (allDirs.has(lng))
-            return true;
-        console.warn(`[app-shell-locales] Locale "${lng}" is listed in ${SUPPORTED_LOCALES_FILE} but has no corresponding language directory — ignoring.`);
-        return false;
-    });
+    // Determine if the app provides a supported-locales.json file.
+    // Physical existence of the file is what matters — even if it's empty,
+    // malformed, or contains no valid entries, it still acts as a filter
+    // (resulting in an empty effective locale list).
+    const manifestPath = appLocalesDir
+        ? path.join(appLocalesDir, SUPPORTED_LOCALES_FILE)
+        : undefined;
+    const hasLocalManifest = manifestPath ? fs.existsSync(manifestPath) : false;
+    // Read the manifest entries (empty if file is missing/invalid)
+    const localManifest = manifestPath ? readSupportedLocales(manifestPath) : [];
+    // Determine the effective set of locales
+    let result;
+    if (hasLocalManifest) {
+        // Filter: only keep unique locales from the manifest that have a directory.
+        // If the manifest is empty/malformed, this correctly yields an empty list.
+        result = [...new Set(localManifest)].filter((lng) => {
+            if (allDirs.has(lng))
+                return true;
+            console.warn(`[app-shell-locales] Locale "${lng}" is listed in ${SUPPORTED_LOCALES_FILE} but has no corresponding language directory — ignoring.`);
+            return false;
+        });
+    }
+    else {
+        // No local manifest → include everything discovered
+        result = [...allDirs];
+    }
+    return result.toSorted();
 }
 /**
  * Parses a JSON file, wrapping parse errors with the file path for
@@ -135,15 +126,23 @@ export function readJsonFile(filePath) {
  * Non-JSON files are skipped (locale bundles are always JSON).
  *
  * `supported-locales.json` is skipped — it is handled separately after the
- * merge so it can reflect the union of both sources plus any discovered
- * language directories.
+ * merge so it can reflect the computed list.
+ *
+ * When `allowedLocales` is provided, only top-level directories whose name
+ * is in the set are merged; all others are skipped. This allows the app's
+ * `supported-locales.json` to act as a filter over upstream locale dirs.
+ * Sub-directories (namespace folders) are always merged recursively.
  */
-export function mergeDirs(src, dest) {
+export function mergeDirs(src, dest, allowedLocales) {
     fs.mkdirSync(dest, { recursive: true });
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
         const srcPath = path.join(src, entry.name);
         const destPath = path.join(dest, entry.name);
         if (entry.isDirectory()) {
+            // At the top level, skip locale dirs not in the allowed set
+            if (allowedLocales && !allowedLocales.has(entry.name))
+                continue;
+            // Sub-directories are always merged (no further filtering)
             mergeDirs(srcPath, destPath);
         }
         else if (entry.name === SUPPORTED_LOCALES_FILE) {

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-crossorigin-fix-plugin.js

@@ -12,7 +12,7 @@ export function addUseCredentials(scriptSrc, html) {
 }
 function processScript(bundle, scriptSrc, html, seen = new Set()) {
     seen.add(scriptSrc);
-    const script = bundle[scriptSrc];
+    const script = bundle?.[scriptSrc];
     if (!script || script.type !== "chunk") {
         return html;
     }

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-locales-plugin.d.ts

@@ -6,7 +6,17 @@ import type { PluginOption } from "vite";
  *
  * Local locale files (from the app's public/locales/) always take priority.
  *
- * `supported-locales.json` is merged by taking the union of both arrays and
- * adding any language directories discovered during the merge.
+ * If the app provides a `supported-locales.json`, it acts as a filter:
+ * only listed locales are included from upstream. If no local file is
+ * provided, all upstream locales are merged in.
+ *
+ * When `mergeUpstream` is false (e.g. `type: "bundle"`), the build skips
+ * upstream merging entirely but still generates `supported-locales.json`
+ * from the local locale directories, filtering by the local manifest when
+ * present. In dev mode, upstream locales are always served regardless of
+ * this flag, since the full app runs locally and needs the shell translations.
+ *
+ * @param mergeUpstream - Whether to merge upstream app-shell-ui locales.
+ *   Defaults to `true` (for `type: "app"`).
  */
-export default function copyAppShellLocales(): PluginOption;
+export default function copyAppShellLocales(mergeUpstream?: boolean): PluginOption;

package/dist/vite-locales-plugin.js

@@ -21,6 +21,24 @@ function resolveAppShellUiLocales() {
     }
     return undefined;
 }
+/**
+ * Computes the effective set of allowed locales for a given locales directory.
+ *
+ * When a local `supported-locales.json` exists, it acts as a filter — even if
+ * it resolves to an empty list (all entries invalid), so that an invalid
+ * manifest doesn't accidentally allow everything.
+ *
+ * @returns The effective locale list (sorted, deduplicated) and the
+ *   corresponding `Set` to use as a filter (or `undefined` when no local
+ *   manifest exists — meaning "allow all").
+ */
+function resolveEffectiveLocales(shellLocalesDir, appLocalesDir) {
+    const hasLocalManifest = fs.existsSync(path.join(appLocalesDir, SUPPORTED_LOCALES_FILE));
+    const locales = computeSupportedLocales(shellLocalesDir, appLocalesDir);
+    // When a local manifest exists, always filter — even with an empty set.
+    const allowedSet = hasLocalManifest ? new Set(locales) : undefined;
+    return { locales, allowedSet };
+}
 /**
  * Vite plugin that handles app-shell locale files:
  * - In dev mode: serves merged locale files via middleware
@@ -28,10 +46,20 @@ function resolveAppShellUiLocales() {
  *
  * Local locale files (from the app's public/locales/) always take priority.
  *
- * `supported-locales.json` is merged by taking the union of both arrays and
- * adding any language directories discovered during the merge.
+ * If the app provides a `supported-locales.json`, it acts as a filter:
+ * only listed locales are included from upstream. If no local file is
+ * provided, all upstream locales are merged in.
+ *
+ * When `mergeUpstream` is false (e.g. `type: "bundle"`), the build skips
+ * upstream merging entirely but still generates `supported-locales.json`
+ * from the local locale directories, filtering by the local manifest when
+ * present. In dev mode, upstream locales are always served regardless of
+ * this flag, since the full app runs locally and needs the shell translations.
+ *
+ * @param mergeUpstream - Whether to merge upstream app-shell-ui locales.
+ *   Defaults to `true` (for `type: "app"`).
  */
-export default function copyAppShellLocales() {
+export default function copyAppShellLocales(mergeUpstream = true) {
     let resolvedOutDir;
     let isBuild = false;
     return {
@@ -42,8 +70,16 @@ export default function copyAppShellLocales() {
             isBuild = config.command === "build";
         },
         // --- DEV MODE: serve merged locales via middleware ---
+        // In dev, always resolve upstream locales regardless of `mergeUpstream`,
+        // because the full app runs locally and needs the shell translations.
+        // The `mergeUpstream` flag only affects the build output.
         configureServer(server) {
             const appShellUiLocalesDir = resolveAppShellUiLocales();
+            const localLocalesDir = path.resolve(server.config.root, "public/locales");
+            // Compute the effective locale set once at server start, using the
+            // same logic as the build path. A server restart is needed when the
+            // locale directory structure or supported-locales.json changes.
+            const { locales: effectiveLocales, allowedSet } = resolveEffectiveLocales(appShellUiLocalesDir, localLocalesDir);
             server.middlewares.use((req, res, next) => {
                 // Parse the pathname, stripping the Vite base and any query string
                 // so locale requests work under non-root base paths (e.g. /myapp/).
@@ -58,19 +94,15 @@ export default function copyAppShellLocales() {
                 if (!pathname.startsWith(base))
                     return next();
                 const relativePath = pathname.slice(base.length);
-                // Handle supported-locales.json separately — it's an array, not a
-                // key/value bundle, and must reflect the union of both sources plus
-                // any language directories that exist on disk.
+                // Serve the computed supported-locales.json
                 if (relativePath === `locales/${SUPPORTED_LOCALES_FILE}`) {
-                    const localLocalesDir = path.resolve(server.config.root, "public/locales");
-                    const merged = computeSupportedLocales(appShellUiLocalesDir, localLocalesDir);
-                    if (merged.length === 0) {
+                    if (effectiveLocales.length === 0) {
                         res.statusCode = 404;
                         res.end();
                         return;
                     }
                     res.setHeader("Content-Type", "application/json");
-                    res.end(JSON.stringify(merged));
+                    res.end(JSON.stringify(effectiveLocales));
                     return;
                 }
                 const match = relativePath.match(/^locales\/([^/]+)\/([^/]+\.json)$/);
@@ -80,9 +112,11 @@ export default function copyAppShellLocales() {
                 // Guard against path traversal (e.g. `..` segments)
                 if (lng.includes("..") || nsFile.includes(".."))
                     return next();
-                const localLocalesBase = path.resolve(server.config.root, "public/locales");
-                const localPath = path.join(localLocalesBase, lng, nsFile);
-                if (!localPath.startsWith(localLocalesBase + path.sep))
+                // Filter by the effective locale set (same logic as build)
+                if (allowedSet && !allowedSet.has(lng))
+                    return next();
+                const localPath = path.join(localLocalesDir, lng, nsFile);
+                if (!localPath.startsWith(localLocalesDir + path.sep))
                     return next();
                 const shellPath = appShellUiLocalesDir
                     ? path.join(appShellUiLocalesDir, lng, nsFile)
@@ -118,19 +152,31 @@ export default function copyAppShellLocales() {
             // guard, locale files would be written to that folder on disk.
             if (!isBuild || !resolvedOutDir)
                 return;
-            const appShellUiLocales = resolveAppShellUiLocales();
-            if (!appShellUiLocales)
-                return;
             const targetLocales = path.resolve(resolvedOutDir, "locales");
-            // Recursive merge: app-shell-ui files are merged into target,
-            // with existing (local) keys taking priority in JSON files.
-            // supported-locales.json is skipped during this step.
-            mergeDirs(appShellUiLocales, targetLocales);
-            // Compute the union of supported locales from both sources and from
-            // the language directories that now exist in the merged output.
-            const merged = computeSupportedLocales(appShellUiLocales, targetLocales);
-            if (merged.length > 0) {
-                fs.writeFileSync(path.join(targetLocales, SUPPORTED_LOCALES_FILE), `${JSON.stringify(merged)}\n`);
+            const appShellUiLocales = mergeUpstream
+                ? resolveAppShellUiLocales()
+                : undefined;
+            if (appShellUiLocales) {
+                const { allowedSet } = resolveEffectiveLocales(appShellUiLocales, targetLocales);
+                // Recursive merge: app-shell-ui files are merged into target,
+                // with existing (local) keys taking priority in JSON files.
+                // supported-locales.json is skipped during this step.
+                // Only locale dirs in the allowed set are merged (if filtering).
+                mergeDirs(appShellUiLocales, targetLocales, allowedSet);
+            }
+            // Generate supported-locales.json from the (possibly merged) output.
+            // When no upstream is involved, this is purely based on local dirs.
+            const { locales: finalLocales } = resolveEffectiveLocales(appShellUiLocales, targetLocales);
+            // Always write/normalize the output supported-locales.json so that any
+            // stale copy from public/ (already placed into dist/ by Vite) is
+            // overwritten with the computed result. If the effective list is empty,
+            // remove the file entirely so the output doesn't ship invalid entries.
+            const manifestPath = path.join(targetLocales, SUPPORTED_LOCALES_FILE);
+            if (finalLocales.length > 0) {
+                fs.writeFileSync(manifestPath, `${JSON.stringify(finalLocales)}\n`);
+            }
+            else if (fs.existsSync(manifestPath)) {
+                fs.unlinkSync(manifestPath);
             }
         },
     };

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}`);
@@ -56,6 +57,7 @@ export async function HvAppShellVitePlugin(opts = {}, env = {}) {
                     {
                         src: resolveModule("es-module-shims"),
                         dest: "bundles",
+                        rename: { stripBase: true },
                     },
                     ...(!devMode && buildEntryPoint
                         ? [
@@ -70,6 +72,7 @@ export async function HvAppShellVitePlugin(opts = {}, env = {}) {
                                     }
                                 }),
                                 dest: "bundles",
+                                rename: { stripBase: true },
                             },
                         ]
                         : []),
@@ -110,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
@@ -118,6 +130,9 @@ export async function HvAppShellVitePlugin(opts = {}, env = {}) {
         // generate the shell script to replace the placeholders in the index.html
         generateEmptyShell && generateBashScript(externalImportMap, inlineConfig),
         // copy/merge app-shell-ui locales into dist (build) or serve via middleware (dev)
-        (buildEntryPoint || devMode) && copyAppShellLocales(),
+        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.2.1",
+  "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.0",
-    "@hitachivantara/app-shell-ui": "^2.3.1",
-    "@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",
@@ -37,7 +36,7 @@
     "react-dom": "^18.2.0",
     "react-router-dom": "^6.9.0",
     "rollup": "^4.57.1",
-    "vite-plugin-static-copy": "^3.1.0"
+    "vite-plugin-static-copy": "^4.1.0"
   },
   "peerDependencies": {
     "vite": "^4.1.4 || ^5.0.4 || ^6.0.0 || ^7.0.0 || ^8.0.0"
@@ -59,5 +58,5 @@
     },
     "./package.json": "./package.json"
   },
-  "gitHead": "96cf5b00b7c82a85b7ebae56e00d48c0b543bebc"
+  "gitHead": "65c4f4394e8f8c7cccb58203e1c08c6832434638"
 }