@olenbetong/appframe-vite 6.8.1 → 6.9.0

package/README.md

@@ -68,12 +68,25 @@ This package reads `package.json.appframe` to know what to proxy and how to buil
 			"routes": ["^/custom/.*"], // Optional: extra proxied routes
 		},
 		"build": {
-			"externals": true, // Map React and ReactDOM to globals
+			"platform": true, // Import React and the af packages from the site's platform bundle
+			"externals": true, // Legacy: map React and ReactDOM to globals
 		},
 	},
 }
 ```
 
+### `build.platform`
+
+Apps on the 2026 site templates (`ob.2026.application`) set `"platform": true`. The production
+build then leaves `react`, `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-dom`,
+`react-dom/client`, `@olenbetong/appframe-core` and `@olenbetong/appframe-data` as bare imports,
+which the template's import map resolves to `@olenbetong/synergi-platform` — one cached React
+per page, shared with the site chrome. The `af.data` global redirect (`dataGlobal`) then only
+applies to the dev server, which has no import map. The build also writes `dist/platform.json`
+with the versions the app compiled against; `scripts/app-deploy.ts` refuses to deploy when the
+target article renders no import map or its platform carries other versions (override with
+`--allow-platform-mismatch`).
+
 ## What it does (at a glance)
 
 - Dev server
@@ -86,7 +99,7 @@ This package reads `package.json.appframe` to know what to proxy and how to buil
   - Writes filenames to Appframe paths, using the article ID, e.g.:
     - `file/article/script/<ARTICLE_ID>/main.[hash].min.js`
     - `file/article/style/<ARTICLE_ID>/style.[hash].min.css`
-  - Optionally treats `react` and `react-dom` as externals and maps them to `React` and `ReactDOM` globals.
+  - With `build.platform`, leaves React and the af packages as bare imports for the template's import map and writes `dist/platform.json`; the legacy `build.externals` maps `react` and `react-dom` to `React` and `ReactDOM` globals instead.
   - Adds a Rollup visualizer report at `dist/stats.html`.
 - Resolve
   - Adds the alias `~/` to `/src/` so imports like `~/components/Button` resolve to `src/components/Button`.
@@ -240,27 +253,29 @@ procedures:
 
 **Supported fields per entry:**
 
-| Field         | Type                 | Description                                                         |
-| ------------- | -------------------- | ------------------------------------------------------------------- |
-| `id`          | `string`             | Variable name used in generated code (e.g. `dsAccountGroups`)       |
-| `resource`    | `string`             | Database object ID (e.g. `atbv_Accounting_SubsidiaryLedgerGroups`)  |
-| `output`      | `string`             | Output file path relative to project root                           |
-| `global`      | `boolean`            | Use `af.data.generateApiDataObject` / `new af.ProcedureAPI` globals |
-| `types`       | `boolean`            | Emit TypeScript type definitions                                    |
-| `permissions` | `string`             | Permissions: I = insert, U = update, D = delete (e.g. `IUD`)        |
-| `maxRecords`  | `number`             | Max records to fetch (default `50`; `-1` for all)                   |
-| `sortOrder`   | `string \| string[]` | Sort order, e.g. `Created:Desc` or `[Created:Desc, Name]`           |
-| `master`      | `string`             | Master data object name (or `name:importPath`)                      |
-| `linkFields`  | `string \| string[]` | Fields linking child to master                                      |
-| `expose`      | `boolean \| string`  | Expose on `af.article.dataObjects` / `af.article.procedures`        |
-| `dynamic`     | `boolean`            | Enable dynamic loading                                              |
-| `unique`      | `string`             | Unique table name for update/delete                                 |
-| `overrides`   | `string \| string[]` | Type overrides, e.g. `MyField:string[]`                             |
-| `distinct`    | `boolean`            | Fetch distinct rows                                                 |
-| `aggregates`  | `string \| string[]` | Aggregate bindings, e.g. `Qty:SUM`                                  |
-| `groupBy`     | `string \| string[]` | Group-by fields                                                     |
-| `where`       | `string`             | Initial where clause                                                |
-| `fields`      | `string \| string[]` | Fields to include (all if omitted)                                  |
+| Field         | Type                 | Description                                                                     |
+| ------------- | -------------------- | ------------------------------------------------------------------------------- |
+| `id`          | `string`             | Variable name used in generated code (e.g. `dsAccountGroups`)                   |
+| `resource`    | `string`             | Database object ID (e.g. `atbv_Accounting_SubsidiaryLedgerGroups`)              |
+| `output`      | `string`             | Output file path relative to project root                                       |
+| `global`      | `boolean`            | Use `af.data.generateApiDataObject` / `new af.ProcedureAPI` globals             |
+| `types`       | `boolean`            | Emit TypeScript type definitions                                                |
+| `permissions` | `string`             | Permissions: I = insert, U = update, D = delete (e.g. `IUD`)                    |
+| `maxRecords`  | `number`             | Max records to fetch (default `50`; `-1` for all)                               |
+| `sortOrder`   | `string \| string[]` | Sort order, e.g. `Created:Desc` or `[Created:Desc, Name]`                       |
+| `master`      | `string`             | Master data object name (or `name:importPath`)                                  |
+| `linkFields`  | `string \| string[]` | Fields linking child to master                                                  |
+| `expose`      | `boolean \| string`  | Expose on `af.article.dataObjects` / `af.article.procedures`                    |
+| `dynamic`     | `boolean`            | Enable dynamic loading                                                          |
+| `unique`      | `string`             | Unique table name for update/delete                                             |
+| `overrides`   | `string \| string[]` | Type overrides, e.g. `MyField:string[]`                                         |
+| `distinct`    | `boolean`            | Fetch distinct rows                                                             |
+| `aggregates`  | `string \| string[]` | Aggregate bindings, e.g. `Qty:SUM`                                              |
+| `groupBy`     | `string \| string[]` | Group-by fields                                                                 |
+| `where`       | `string`             | Initial where clause                                                            |
+| `fields`      | `string \| string[]` | Fields to include (all if omitted)                                              |
+| `transaction` | `boolean`            | Procedures only. `false` stops the framework wrapping the call in a transaction |
+| `timeout`     | `number`             | Procedures only. Milliseconds before the call is abandoned (default `30000`)    |
 
 A top-level `server` key can override the hostname (defaults to `appframe.proxy.hostname` from `package.json`).
 

package/lib/appframeDataGlobal.d.ts

@@ -1,4 +1,19 @@
 import type { Plugin } from "vite";
+/**
+ * Names the framework puts on the `af.data` global. These are the exports shared by
+ * `bundle-entries/browser.esm.ts` and `bundle-entries/browser-compat.esm.ts` — which of
+ * the two a page loads depends on the user's UserMode, so only names present in *both*
+ * are safe to read off the global.
+ */
+export declare const GLOBAL_EXPORTS: string[];
+/**
+ * Helpers the `af.data` bundles do not expose, mapped to the module they live in. These
+ * are pure functions whose only dependencies on the rest of the package are types, so
+ * bundling them creates no second client, data object or event bus — the state that must
+ * stay single-instance still comes from the global. Move an entry up to GLOBAL_EXPORTS
+ * once the browser bundle entries export it and the new af.data has been deployed.
+ */
+export declare const LOCAL_EXPORTS: Record<string, string[]>;
 /**
  * Redirects imports of `@olenbetong/appframe-data` to the `af.data` global the article
  * already loads.

package/lib/appframeDataGlobal.js

@@ -7,7 +7,7 @@ const VIRTUAL_ID = "\0appframe-data-global";
  * the two a page loads depends on the user's UserMode, so only names present in *both*
  * are safe to read off the global.
  */
-const GLOBAL_EXPORTS = [
+export const GLOBAL_EXPORTS = [
     "Client",
     "DataHandler",
     "DataObject",
@@ -32,7 +32,7 @@ const GLOBAL_EXPORTS = [
  * stay single-instance still comes from the global. Move an entry up to GLOBAL_EXPORTS
  * once the browser bundle entries export it and the new af.data has been deployed.
  */
-const LOCAL_EXPORTS = {
+export const LOCAL_EXPORTS = {
     "formDataToObject.js": ["formDataToDataObjectRecord", "formDataToObject", "formDataToProcedureParameters"],
     "exportDataObject.js": ["exportOptionsFromDataObject", "getDataObjectReportRequest", "openDataObjectReport"],
     "DataHandler.js": ["isRequestError"],

package/lib/build.d.ts

@@ -1,2 +1,35 @@
-import type { UserConfig } from "vite";
+import { type Plugin, type UserConfig } from "vite";
+/**
+ * The bare specifiers the 2026 site templates resolve through their import map to the
+ * `@olenbetong/synergi-platform` bundle: one React per page, and the `af` packages as
+ * shims over the globals the article loads. An app built with `appframe.build.platform`
+ * leaves these external and so must run on a template that renders the import map.
+ */
+export declare const PLATFORM_EXTERNALS: string[];
+/**
+ * The IIFE global each platform specifier is published under (`buildConfig.entries` in the
+ * platform package), for builds that cannot use the import map.
+ */
+export declare const PLATFORM_GLOBALS: Record<string, string>;
+export declare function usesPlatform(appframe: {
+    build?: {
+        platform?: boolean;
+    };
+} | undefined): boolean;
+/**
+ * The packages whose version the platform manifest records; an app must match the served
+ * platform on every one it has installed.
+ */
+export declare const PLATFORM_UPSTREAM: string[];
+export type PlatformManifest = {
+    /** The package versions the app resolved at build time. */
+    upstream: Record<string, string>;
+};
+/**
+ * Writes `dist/platform.json` after a platform build: the versions of the platform packages the
+ * app was compiled against. The deploy script compares it with the manifest of the platform the
+ * target site serves, since an app compiled against one React and run on another is a runtime
+ * error, not a build error.
+ */
+export declare function platformManifest(): Plugin;
 export declare function addAppframeBuildConfig(config: UserConfig): Promise<UserConfig>;

package/lib/build.js

@@ -1,7 +1,100 @@
 import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { visualizer } from "rollup-plugin-visualizer";
+import { esmExternalRequirePlugin } from "vite";
 import { importJson } from "./importJson.js";
+/**
+ * The bare specifiers the 2026 site templates resolve through their import map to the
+ * `@olenbetong/synergi-platform` bundle: one React per page, and the `af` packages as
+ * shims over the globals the article loads. An app built with `appframe.build.platform`
+ * leaves these external and so must run on a template that renders the import map.
+ */
+export const PLATFORM_EXTERNALS = [
+    "react",
+    "react/jsx-runtime",
+    "react/jsx-dev-runtime",
+    "react-dom",
+    "react-dom/client",
+    "react-router",
+    "@digdir/designsystemet-web",
+    "@digdir/designsystemet-react",
+    "@olenbetong/appframe-core",
+    "@olenbetong/appframe-data",
+    "@olenbetong/appframe-react",
+    "@olenbetong/appframe-ds",
+    "@olenbetong/appframe-ds/grid",
+    "@olenbetong/appframe-ds/mdi",
+    "@olenbetong/appframe-ds/progress",
+    "@olenbetong/appframe-ds/report-downloader",
+];
+/**
+ * The IIFE global each platform specifier is published under (`buildConfig.entries` in the
+ * platform package), for builds that cannot use the import map.
+ */
+export const PLATFORM_GLOBALS = {
+    react: "React",
+    "react/jsx-runtime": "ReactJSXRuntime",
+    "react/jsx-dev-runtime": "ReactJSXDevRuntime",
+    "react-dom": "ReactDOM",
+    "react-dom/client": "ReactDOMClient",
+    "react-router": "ReactRouter",
+    "@digdir/designsystemet-web": "Designsystemet.web",
+    "@digdir/designsystemet-react": "Designsystemet.react",
+    "@olenbetong/appframe-core": "SynergiPlatform.appframeCore",
+    "@olenbetong/appframe-data": "SynergiPlatform.appframeData",
+    "@olenbetong/appframe-react": "SynergiPlatform.appframeReact",
+    "@olenbetong/appframe-ds": "SynergiPlatform.appframeDs",
+    "@olenbetong/appframe-ds/grid": "SynergiPlatform.appframeDsGrid",
+    "@olenbetong/appframe-ds/mdi": "SynergiPlatform.appframeDsMdi",
+    "@olenbetong/appframe-ds/progress": "SynergiPlatform.appframeDsProgress",
+    "@olenbetong/appframe-ds/report-downloader": "SynergiPlatform.appframeDsReportDownloader",
+};
+export function usesPlatform(appframe) {
+    return appframe?.build?.platform === true;
+}
+/**
+ * The packages whose version the platform manifest records; an app must match the served
+ * platform on every one it has installed.
+ */
+export const PLATFORM_UPSTREAM = [
+    "react",
+    "react-dom",
+    "react-router",
+    "@digdir/designsystemet-react",
+    "@digdir/designsystemet-web",
+    "@digdir/designsystemet-css",
+    "@olenbetong/appframe-core",
+    "@olenbetong/appframe-data",
+    "@olenbetong/appframe-react",
+    "@olenbetong/appframe-ds",
+];
+/**
+ * Writes `dist/platform.json` after a platform build: the versions of the platform packages the
+ * app was compiled against. The deploy script compares it with the manifest of the platform the
+ * target site serves, since an app compiled against one React and run on another is a runtime
+ * error, not a build error.
+ */
+export function platformManifest() {
+    return {
+        name: "appframe:platform-manifest",
+        apply: "build",
+        async writeBundle() {
+            let manifest = { upstream: {} };
+            for (let name of PLATFORM_UPSTREAM) {
+                let file = resolve(process.cwd(), "node_modules", name, "package.json");
+                try {
+                    manifest.upstream[name] = JSON.parse(await readFile(file, "utf8")).version;
+                }
+                catch {
+                    // Not every app depends on every platform package (an app without a grid has no
+                    // appframe-ds, say); only what the app resolved is recorded and checked.
+                }
+            }
+            await writeFile(resolve(process.cwd(), "dist", "platform.json"), `${JSON.stringify(manifest, null, "\t")}\n`);
+        },
+    };
+}
 export async function addAppframeBuildConfig(config) {
     let appPkg = await importJson("./package.json", true);
     let { appframe } = appPkg;
@@ -22,9 +115,21 @@ export async function addAppframeBuildConfig(config) {
     config.appType = "custom";
     config.build.rolldownOptions = {
         input: { main: entry },
-        // Cast visualizer plugin to any to avoid Rollup type version clashes
-        plugins: [visualizer({ filename: "./dist/stats.html", gzipSize: true })],
-        external: appframe.build.externals !== false ? ["react", "react-dom", "react-dom/client"] : [],
+        plugins: [
+            // Cast visualizer plugin to any to avoid Rollup type version clashes
+            visualizer({ filename: "./dist/stats.html", gzipSize: true }),
+            // The platform set stays external through this plugin rather than the top-level
+            // `external`: CommonJS dependencies in the app (MUI X, exceljs) `require("react")`, and
+            // only the plugin turns those requires into imports the import map can resolve. A
+            // plain external leaves a `require` shim that throws in the browser. The plugin must
+            // own the list, so the externals are not repeated below.
+            ...(usesPlatform(appframe) ? [esmExternalRequirePlugin({ external: PLATFORM_EXTERNALS })] : []),
+        ],
+        external: usesPlatform(appframe)
+            ? []
+            : appframe.build.externals !== false
+                ? ["react", "react-dom", "react-dom/client"]
+                : [],
         treeshake: {
             /*
              * `@digdir/designsystemet-react` does not declare `sideEffects: false`, so the
@@ -39,7 +144,9 @@ export async function addAppframeBuildConfig(config) {
             moduleSideEffects: (id) => !/[\\/]node_modules[\\/].*designsystemet-react[\\/]/.test(id.replace(/\?.*$/, "")),
         },
         output: {
-            globals: appframe.build.externals !== false
+            // Platform builds keep the bare specifiers (ESM, resolved by the import map); the old
+            // externals mode maps them to window globals instead.
+            globals: !usesPlatform(appframe) && appframe.build.externals !== false
                 ? {
                     react: "React",
                     "react-dom": "ReactDOM",

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import type { Plugin } from "vite";
 import { appframeDataGlobal } from "./appframeDataGlobal.js";
-import { addAppframeBuildConfig } from "./build.js";
+import { addAppframeBuildConfig, PLATFORM_EXTERNALS, PLATFORM_GLOBALS, PLATFORM_UPSTREAM, platformManifest, usesPlatform } from "./build.js";
 import { createDevMiddleware } from "./devServer.js";
 import { publishSafeOutput } from "./publishSafeOutput.js";
 export interface AppframePluginOptions {
@@ -32,6 +32,7 @@ export interface AppframePluginOptions {
     dataGlobal?: boolean;
 }
 export default function appframe(options?: AppframePluginOptions): Plugin[];
-export { addAppframeBuildConfig, appframeDataGlobal, createDevMiddleware, publishSafeOutput };
+export { addAppframeBuildConfig, appframeDataGlobal, createDevMiddleware, PLATFORM_EXTERNALS, PLATFORM_GLOBALS, PLATFORM_UPSTREAM, platformManifest, publishSafeOutput, usesPlatform, };
+export type { PlatformManifest } from "./build.js";
 export { DEVTOOLS_API_VERSION, type DevtoolsDiscovery, type DevtoolsServerInfo } from "./devtoolsServer.js";
 export type { JobOptions, ReleaseEvent, ReleaseScriptEvent, ReleaseSnapshot, ReleaseStep } from "./releaseServer.js";

package/lib/index.js

@@ -1,8 +1,9 @@
+import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import bodyParser from "body-parser";
 import { watch } from "chokidar";
 import { appframeDataGlobal } from "./appframeDataGlobal.js";
-import { addAppframeBuildConfig } from "./build.js";
+import { addAppframeBuildConfig, PLATFORM_EXTERNALS, PLATFORM_GLOBALS, PLATFORM_UPSTREAM, platformManifest, usesPlatform, } from "./build.js";
 import { generateFromConfig } from "./cli-resources-generate.js";
 import { createDevMiddleware, getLoginInfo, getProxyRoutes } from "./devServer.js";
 import { createDevtoolsMiddleware } from "./devtoolsServer.js";
@@ -240,7 +241,30 @@ export default function appframe(options = {}) {
             };
         },
     };
-    return [...(dataGlobal ? [appframeDataGlobal()] : []), plugin, publishSafeOutput()];
+    let plugins = [plugin, publishSafeOutput()];
+    let platform = usesPlatform(readAppframeConfig());
+    if (platform) {
+        plugins.push(platformManifest());
+    }
+    if (dataGlobal) {
+        // An app built against the platform leaves `@olenbetong/appframe-data` as a bare
+        // specifier for the import map, so the global redirect only applies to the dev server
+        // (which has no import map) and to builds that bundle their own runtime.
+        plugins.unshift({
+            ...appframeDataGlobal(),
+            apply: (_config, env) => env.command === "serve" || !platform,
+        });
+    }
+    return plugins;
 }
-export { addAppframeBuildConfig, appframeDataGlobal, createDevMiddleware, publishSafeOutput };
+/** The `appframe` section of the app's package.json, read synchronously at plugin creation. */
+function readAppframeConfig() {
+    try {
+        return JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf8")).appframe;
+    }
+    catch {
+        return undefined;
+    }
+}
+export { addAppframeBuildConfig, appframeDataGlobal, createDevMiddleware, PLATFORM_EXTERNALS, PLATFORM_GLOBALS, PLATFORM_UPSTREAM, platformManifest, publishSafeOutput, usesPlatform, };
 export { DEVTOOLS_API_VERSION } from "./devtoolsServer.js";

package/lib/resourceGenerate.d.ts

@@ -9,6 +9,8 @@ export declare function writeGeneratedFile(filePath: string, content: string): P
 export type CLIOptions = {
     /** Procedures only. `false` stops the framework wrapping the call in a transaction. */
     transaction?: boolean;
+    /** Procedures only. Milliseconds before the call is abandoned; the generated default is 30000. */
+    timeout?: number;
     server: string;
     types?: boolean;
     global: boolean;

package/lib/resourceGenerate.js

@@ -305,7 +305,7 @@ export function getProcedureDefinition(name, procDefinition, options) {
     output.push(`export const ${procName} = new ${options.global ? "af." : ""}ProcedureAPI${options.types ? `<${paramTypeName}, ${options.typesJsonReturnType ?? "{ Table?: unknown[] }"}>` : ""}({
   procedureId: "${name}",
   parameters: ${JSON.stringify(parameters, null, 2)},
-  timeout: 30000${options.transaction === false ? ",\n  transaction: false" : ""}
+  timeout: ${options.timeout ?? 30000}${options.transaction === false ? ",\n  transaction: false" : ""}
 });`);
     if (options.expose) {
         output.push("");

package/lib/resourcesConfig.d.ts

@@ -37,6 +37,12 @@ export type ResourceEntry = {
      * remote write a distributed one, which fails without MSDTC configured between the servers.
      */
     transaction?: boolean;
+    /**
+     * Procedures only. Milliseconds the call may take before it is abandoned, client and server
+     * alike (default `30000`). For a procedure that reads across a linked server or scans a large
+     * table, where a preview alone can take a minute.
+     */
+    timeout?: number;
     /** Permissions to set: I = insert, U = update, D = delete (e.g. `IUD`) */
     permissions?: string;
     /** Maximum records to fetch (default `50`; use `-1` for all) */

package/lib/resourcesConfig.js

@@ -98,6 +98,7 @@ export function entryToCLIOptions(entry, hostname) {
         dynamic: entry.dynamic ?? false,
         types: entry.types,
         transaction: entry.transaction,
+        timeout: entry.timeout,
         maxRecords: entry.maxRecords !== undefined ? String(entry.maxRecords) : "50",
         sortOrder: sortOrderToString(entry.sortOrder),
         permissions: entry.permissions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-vite",
-  "version": "6.8.1",
+  "version": "6.9.0",
   "description": "Tools to use and deploy Vite applications to Appframe",
   "main": "./lib/index.js",
   "type": "module",
@@ -39,14 +39,14 @@
     "inquirer-autocomplete-standalone": "^0.8.1",
     "jsdom": "30.0.1",
     "rollup-plugin-visualizer": "^7.1.1",
-    "yaml": "^2.9.0",
-    "@olenbetong/appframe-data": "1.7.1"
+    "yaml": "^2.9.1",
+    "@olenbetong/appframe-data": "1.7.2"
   },
   "devDependencies": {
     "@types/jsdom": "^30.0.0",
     "@types/node": "26.5.1",
     "typescript": "7.0.2",
-    "vite": "8.2.2"
+    "vite": "8.3.0"
   },
   "peerDependencies": {
     "vite": ">=8.1.5"