@equinor/fusion-framework-vite-plugin-spa 3.1.11 → 4.0.0

package/src/types.ts

@@ -1,58 +1,147 @@
 import type { ConfigEnv } from 'vite';
 
+/**
+ * Base type for template environment variables.
+ *
+ * @remarks
+ * A loose record that can hold any key-value pairs later flattened into
+ * `FUSION_SPA_*` environment variables by {@link objectToEnv}.
+ * Extend this type (or use {@link FusionTemplateEnv}) when you need a
+ * strongly-typed environment shape.
+ */
 export type TemplateEnv = Record<string, unknown>;
 
+/**
+ * Describes a single resource that the SPA service worker should intercept.
+ *
+ * When the service worker sees a fetch request whose URL starts with {@link url},
+ * it optionally rewrites the path and attaches an OAuth Bearer token obtained
+ * from the MSAL module for the specified {@link scopes}.
+ *
+ * @example
+ * ```ts
+ * const resource: ResourceConfiguration = {
+ *   url: '/app-proxy',
+ *   rewrite: '/@fusion-api/app',
+ *   scopes: ['api://backend/.default'],
+ * };
+ * ```
+ */
 export type ResourceConfiguration = {
+  /** URL path prefix to match against outgoing fetch requests. */
   url: string;
+  /** OAuth scopes used to acquire a Bearer token for matched requests. */
   scopes?: string[];
+  /** Replacement path prefix; the matched {@link url} segment is swapped for this value. */
   rewrite?: string;
 };
 
 /**
- * Represents the environment configuration for a template.
+ * Strongly-typed environment configuration consumed by the default SPA
+ * HTML template and bootstrap script.
+ *
+ * @remarks
+ * Values are flattened to `FUSION_SPA_*` environment variables at build time
+ * and injected into the HTML template via Vite's
+ * {@link https://vite.dev/guide/env-and-mode.html#html-constant-replacement | constant replacement}.
+ * They can also be overridden through a `.env` file.
+ *
+ * @see {@link PluginOptions.generateTemplateEnv} for how to supply these values.
  */
 export type FusionTemplateEnv = {
-  /** Document title */
+  /** HTML `<title>` for the generated page. */
   title: string;
-  /** Template bootstrap file path */
+
+  /**
+   * Path to the bootstrap module loaded by the HTML template.
+   *
+   * @defaultValue `'/@fusion-spa-bootstrap.js'`
+   */
   bootstrap: string;
 
+  /** Optional telemetry configuration. */
   telemetry?: {
+    /**
+     * Minimum severity level for console telemetry output.
+     *
+     * @remarks
+     * Maps to `TelemetryLevel` values: Debug (0), Information (1),
+     * Warning (2), Error (3), Critical (4).
+     *
+     * @defaultValue `1` (Information)
+     */
     consoleLevel?: number;
   };
 
-  /** Id of the portal to load */
+  /**
+   * Portal to load and render inside the SPA shell.
+   *
+   * @remarks
+   * The `id` can reference:
+   * - A local npm package (e.g. `@equinor/fusion-framework-dev-portal`)
+   * - A portal identifier from the Fusion Portal Service
+   * - Any custom portal implementation
+   */
   portal: {
+    /** Portal identifier used to fetch the portal manifest. */
     id: string;
+    /**
+     * Version tag for the portal manifest.
+     * @defaultValue `'latest'`
+     */
     tag?: string;
+    /**
+     * When `true`, portal entry point requests are prefixed with `/portal-proxy`
+     * so they can be intercepted by a proxy server.
+     * @defaultValue `false`
+     */
     proxy?: boolean;
   };
 
-  /** Service discovery configuration */
+  /** Service discovery endpoint and authentication scopes. */
   serviceDiscovery: {
+    /** URL of the Fusion service discovery endpoint. */
     url: string;
+    /** OAuth scopes required to authenticate service discovery requests. */
     scopes: string[];
   };
 
-  /** MSAL configuration */
+  /** Microsoft Authentication Library (MSAL) configuration for Azure AD. */
   msal: {
+    /** Azure AD tenant identifier. */
     tenantId: string;
+    /** Application (client) identifier registered in Azure AD. */
     clientId: string;
+    /** Redirect URI for the authentication callback. */
     redirectUri: string;
+    /**
+     * When `'true'`, the application automatically prompts for login
+     * on initial load.
+     */
     requiresAuth: string;
   };
-  /** Service worker configuration */
+
+  /** Service worker resource interception configuration. */
   serviceWorker: {
+    /**
+     * Array of resource configurations the service worker will manage.
+     * @see {@link ResourceConfiguration}
+     */
     resources: ResourceConfiguration[];
   };
 };
 
 /**
- * A function type that generates a partial environment configuration for a template.
+ * Factory function that produces a partial template environment from the
+ * current Vite {@link ConfigEnv} (mode, command, etc.).
+ *
+ * @remarks
+ * Returned values are merged with defaults and flattened into
+ * `FUSION_SPA_*` environment variables.
  *
- * @template TEnv - The type of the environment configuration. Defaults to `TemplateEnv`.
- * @param configEnv - The configuration environment provided as input.
- * @returns A partial environment configuration of type `TEnv`, or `undefined` if no configuration is provided.
+ * @template TEnv - Shape of the environment configuration. Defaults to {@link TemplateEnv}.
+ * @param configEnv - Vite configuration environment containing `mode` and `command`.
+ * @returns A partial environment object, or `undefined` to use defaults only.
  */
 export type TemplateEnvFn<TEnv extends TemplateEnv> = (
   configEnv: ConfigEnv,

package/src/util/load-env.ts

@@ -2,16 +2,22 @@ import { type ConfigEnv, loadEnv, type UserConfig } from 'vite';
 import { resolve } from 'node:path';
 
 /**
- * Loads environment variables for a Vite project based on the provided configuration and environment.
+ * Loads environment variables from `.env` files for the Fusion SPA plugin.
  *
- * @see {@link http://vite.dev/guide/env-and-mode.html#env-files}
+ * @remarks
+ * Delegates to Vite's {@link https://vite.dev/guide/env-and-mode.html#env-files | loadEnv}
+ * using the resolved project root and env directory. Only variables whose
+ * name starts with {@link namespace} are returned.
  *
- * @param config - The user configuration object, which includes properties such as `root` and `envDir`.
- *   - `root`: The root directory of the project. Defaults to the current working directory if not specified.
- *   - `envDir`: The directory containing environment files. If not specified, defaults to the root directory.
- * @param env - The environment configuration object.
- *   - `mode`: The mode in which the application is running (e.g., 'development', 'production').
- * @returns A record of environment variables prefixed with `FUSION_SPA_`.
+ * Values loaded here override any matching keys produced by
+ * {@link PluginOptions.generateTemplateEnv}.
+ *
+ * @param config - Vite user configuration (`root`, `envDir`).
+ * @param env - Vite configuration environment containing the current `mode`.
+ * @param namespace - Variable name prefix to filter on.
+ * @returns A flat record of matching environment variable names to their string values.
+ *
+ * @defaultValue namespace — `'FUSION_SPA_'`
  */
 export function loadEnvironment(
   config: UserConfig,

package/src/util/object-to-env.ts

@@ -1,32 +1,26 @@
 /**
- * Converts a nested object into a flat object with keys in snake_case and uppercase.
- * Nested keys are prefixed with their parent keys, separated by underscores.
- * Non-object values are stringified.
+ * Flattens a nested object into a single-level record with
+ * `UPPER_SNAKE_CASE` keys suitable for Vite's `config.define`.
  *
- * @param obj - The input object to be flattened and converted.
- * @param prefix - An optional prefix to prepend to the keys (default is an empty string).
- * @returns A flat object with snake_case, uppercase keys and stringified values.
+ * @remarks
+ * Used internally by the Fusion SPA plugin to convert the object
+ * returned by {@link PluginOptions.generateTemplateEnv} into
+ * `import.meta.env.*` defines.
  *
- * @example
- * ```typescript
- * const input = {
- *   someKey: "value",
- *   nestedObject: {
- *     anotherKey: 42,
- *     deepNested: {
- *       finalKey: true
- *     }
- *   }
- * };
+ * - camelCase keys are converted to UPPER_SNAKE_CASE.
+ * - Nested objects are recursively flattened with `_` separators.
+ * - Arrays and primitives are JSON-stringified.
+ *
+ * @param obj - The object to flatten.
+ * @param prefix - Key prefix prepended to every output key.
+ * @returns A flat record mapping `PREFIX_KEY` strings to JSON-stringified values.
  *
- * const result = objectToEnv(input);
- * console.log(result);
- * // Output:
- * // {
- * //   SOME_KEY: "\"value\"",
- * //   NESTED_OBJECT_ANOTHER_KEY: "42",
- * //   NESTED_OBJECT_DEEP_NESTED_FINAL_KEY: "true"
- * // }
+ * @defaultValue prefix — `'FUSION_SPA'`
+ *
+ * @example
+ * ```ts
+ * objectToEnv({ portal: { id: 'my-portal' } }, 'FUSION_SPA');
+ * // => { FUSION_SPA_PORTAL_ID: '"my-portal"' }
  * ```
  */
 export function objectToEnv(obj: object, prefix = 'FUSION_SPA'): Record<string, string> {

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '3.1.11';
+export const version = '4.0.0';