@equinor/fusion-framework-vite-plugin-spa 4.1.0 → 4.1.2

package/src/html/sw.ts

@@ -1,238 +0,0 @@
-/// <reference lib="webworker" />
-
-import type { ResourceConfiguration } from '../types.js';
-
-/**
- * Represents an authentication token with an access token and its expiration time.
- */
-type Token = {
-  accessToken: string;
-  expiresOn: number;
-};
-
-/**
- * A cache structure for storing tokens, where each token is associated with a unique string key.
- *
- * @typeParam string - The key used to identify a token in the cache.
- * @typeParam Token - The type of the token being stored in the cache.
- */
-type TokenCache = Map<string, Token>;
-
-/**
- * A reference to the global scope of the service worker.
- *
- * The `self` variable is explicitly cast to `ServiceWorkerGlobalScope` to ensure
- * type safety and provide access to service worker-specific APIs.
- *
- * This is necessary because `globalThis` is a generic global object and does not
- * include service worker-specific properties and methods by default.
- */
-const self = globalThis as unknown as ServiceWorkerGlobalScope;
-
-/**
- * An array of settings used for token injection.
- * Each setting defines the configuration for injecting tokens
- * into the application, such as authentication or API tokens.
- */
-let resourceConfigurations: ResourceConfiguration[] = [];
-
-/**
- * A cache for storing tokens, implemented as a `Map`.
- * This cache is used to temporarily hold tokens for quick retrieval.
- *
- * @type {TokenCache} - A `Map` instance where the keys and values are determined by the `TokenCache` type definition.
- */
-const tokenCache: TokenCache = new Map();
-
-/**
- * Generates a unique key by sorting and concatenating an array of scope strings.
- *
- * @param scopes - An array of strings representing the scopes to be processed.
- * @returns A single string representing the sorted and concatenated scopes, separated by commas.
- */
-function getScopeKey(scopes: string[]): string {
-  return scopes.sort().join(',');
-}
-
-/**
- * Checks if a token associated with the specified scopes is valid.
- *
- * This function determines the validity of a token by checking if it exists
- * in the token cache and if its expiration time has not been reached.
- *
- * @param scopes - An array of strings representing the scopes for which the token is required.
- * @returns `true` if a valid token exists for the given scopes; otherwise, `false`.
- */
-function isTokenValid(scopes: string[]): boolean {
-  const scopeKey = getScopeKey(scopes);
-  // No cached entry at all means there's nothing to validate
-  if (!tokenCache.has(scopeKey)) {
-    return false;
-  }
-  const tokenData = tokenCache.get(scopeKey);
-  return tokenData !== undefined && Date.now() < tokenData.expiresOn;
-}
-
-/**
- * Requests an access token from a client using the Service Worker's `clients` API.
- * Communicates with the client via a `MessageChannel` to retrieve the token.
- *
- * @param scopes - An array of strings representing the scopes for which the token is requested.
- * @returns A promise that resolves to the token object containing the `accessToken` and `expiresOn` properties.
- * @throws An error if no clients are available or if the client responds with an error.
- *
- * @example
- * ```typescript
- * const token = await requestTokenFromClient(['scope1', 'scope2']);
- * console.log(token.accessToken); // Access token string
- * console.log(token.expiresOn);  // Expiration timestamp
- * ```
- */
-async function requestTokenFromClient(scopes: string[]): Promise<Token> {
-  const clients = await self.clients.matchAll();
-
-  // ensure there are clients available
-  if (clients.length === 0) {
-    throw new Error('No clients available');
-  }
-
-  // create a message channel to communicate with the client
-  const messageChannel = new MessageChannel();
-  const token = await new Promise<Token>((resolve, reject) => {
-    messageChannel.port1.onmessage = (event) => {
-      // Reject when the client reports it couldn't provide a token
-      if (event.data.error) {
-        reject(event.data.error);
-      }
-      resolve(event.data as { accessToken: string; expiresOn: number });
-    };
-    clients[0].postMessage({ type: 'GET_TOKEN', scopes }, [messageChannel.port2]);
-  });
-
-  // A resolved but empty response means the client didn't actually return a token
-  if (!token) {
-    throw new Error('No token received');
-  }
-
-  // store the token in the cache
-  tokenCache.set(getScopeKey(scopes), token);
-
-  return token;
-}
-
-/**
- * Retrieves an access token for the specified scopes. If no valid token is found,
- * it requests a new one from the client.
- *
- * @param scopes - An array of strings representing the required scopes for the token.
- * @returns A promise that resolves to the access token as a string.
- * @throws An error if no access token is found after attempting to retrieve or request one.
- */
-async function getToken(scopes: string[]): Promise<string> {
-  // if no valid token is found, request a new one
-  if (!isTokenValid(scopes)) {
-    await requestTokenFromClient(scopes);
-  }
-  const scopeKey = getScopeKey(scopes);
-  const { accessToken } = tokenCache.get(scopeKey) || {};
-  // A missing accessToken here means the client failed to provide a usable token
-  if (!accessToken) {
-    throw new Error('No access token found');
-  }
-  return accessToken;
-}
-
-// Match request to proxy config
-/**
- * Retrieves the matching token injection configuration for a given URL.
- *
- * @param url - The URL to match against the token injection settings.
- * @returns The matching `TokenInjectionSetting` if found, otherwise `undefined`.
- *
- * The function compares the provided URL with the `url` property of each
- * `TokenInjectionSetting` in the `tokenInjectionSettings` array. If the
- * provided URL starts with the resolved `config.url`, it is considered a match.
- *
- * Note:
- * - If `config.url` starts with a `/`, it is resolved relative to the service
- *   worker's origin (`self.location.origin`).
- * - The comparison is performed using fully resolved absolute URLs.
- */
-function getMatchingConfig(url: string): ResourceConfiguration | undefined {
-  // Find the first configured resource whose resolved base URL prefixes the request URL
-  return resourceConfigurations.find((config) => {
-    const configUrl = new URL(
-      config.url,
-      config.url.startsWith('/') ? self.location.origin : undefined,
-    ).href;
-    const requestUrl = new URL(url, self.location.origin).href;
-    return requestUrl.startsWith(configUrl);
-  });
-}
-
-// Install event
-self.addEventListener('install', (event: ExtendableEvent) => {
-  event.waitUntil(self.skipWaiting());
-});
-
-// Activate event
-self.addEventListener('activate', (event: ExtendableEvent) => {
-  event.waitUntil(self.clients.claim());
-});
-
-// Handle configuration from main thread
-self.addEventListener('message', async (event: ExtendableMessageEvent) => {
-  const { type, config } = event.data;
-  // Only the INIT_CONFIG message carries resource configuration to apply
-  if (type === 'INIT_CONFIG') {
-    resourceConfigurations = config as ResourceConfiguration[];
-
-    // CRITICAL: Force skipWaiting() and claim clients to ensure this service worker takes control
-    // This handles both waiting and already-active service workers during hard refresh
-    // - skipWaiting() forces activation if the service worker is in waiting state
-    // - clients.claim() takes control of all clients immediately
-    await self.skipWaiting();
-    await self.clients.claim();
-  }
-});
-
-// Handle fetch events
-self.addEventListener('fetch', (event: FetchEvent) => {
-  const request = event.request.clone();
-  const url = new URL(request.url);
-  const matchedConfig = getMatchingConfig(url.toString());
-
-  // only handle requests that match the config
-  if (matchedConfig) {
-    const requestHeaders = new Headers(request.headers);
-    const handleRequest = async () => {
-      // if the matched config has scopes, append the token to the request
-      if (matchedConfig.scopes) {
-        const token = await getToken(matchedConfig.scopes);
-        requestHeaders.set('Authorization', `Bearer ${token}`);
-      }
-
-      // if the matched config has a rewrite, rewrite the url
-      if (typeof matchedConfig.rewrite === 'string') {
-        url.pathname = url.pathname.replace(matchedConfig?.url, matchedConfig.rewrite);
-      }
-
-      // Consume the ReadableStream body and convert to text
-      // ReadableStreams can only be consumed once, so we extract the content here
-      // request.text() resolves to empty string when the request has no body
-      const body = await request.text();
-
-      // fetch the request with the modified url and headers, preserving the original HTTP method and body
-      // This ensures OPTIONS, PATCH, DELETE and other methods are forwarded correctly
-      // `cache` is forwarded explicitly - otherwise callers requesting `no-store` (e.g. polling
-      // endpoints) would silently fall back to the default HTTP cache once re-fetched here.
-      return fetch(url, {
-        method: request.method,
-        headers: requestHeaders,
-        body: body || undefined,
-        cache: request.cache,
-      });
-    };
-    event.respondWith(handleRequest());
-  }
-});

package/src/index.ts

@@ -1,34 +0,0 @@
-/**
- * @module @equinor/fusion-framework-vite-plugin-spa
- *
- * Vite plugin for building Fusion Framework Single Page Applications (SPAs).
- *
- * Provides HTML template generation, MSAL authentication bootstrapping,
- * service discovery wiring, portal loading, and authenticated API proxying
- * via a service worker.
- *
- * @remarks
- * This plugin is intended for non-production development environments and
- * is designed for use with `@equinor/fusion-framework-cli`.
- *
- * @example
- * ```ts
- * import { fusionSpaPlugin } from '@equinor/fusion-framework-vite-plugin-spa';
- *
- * export default defineConfig({
- *   plugins: [
- *     fusionSpaPlugin({
- *       generateTemplateEnv: () => ({
- *         title: 'My App',
- *         portal: { id: 'my-portal' },
- *         serviceDiscovery: { url: 'https://...', scopes: ['api://...'] },
- *         msal: { tenantId: '...', clientId: '...', redirectUri: '...' },
- *       }),
- *     }),
- *   ],
- * });
- * ```
- */
-export { default, plugin as fusionSpaPlugin, type PluginOptions } from './plugin.js';
-
-export * from './types.js';

package/src/plugin.ts

@@ -1,202 +0,0 @@
-import { normalizePath, type Plugin } from 'vite';
-
-import { fileURLToPath } from 'node:url';
-
-import defaultTemplate from './html/html.js';
-
-import { objectToEnv } from './util/object-to-env.js';
-import { loadEnvironment } from './util/load-environment.js';
-
-import type { TemplateEnv, TemplateEnvFn } from './types.js';
-
-/**
- * Options accepted by the Fusion SPA Vite plugin.
- *
- * @remarks
- * Controls HTML template generation, environment variable prefixing,
- * and the factory that produces template environment values from the
- * current Vite build/serve context.
- *
- * @template TEnv - Shape of the template environment. Defaults to {@link TemplateEnv}.
- *
- * @example
- * ```ts
- * const opts: PluginOptions<FusionTemplateEnv> = {
- *   templateEnvPrefix: 'FUSION_SPA_',
- *   generateTemplateEnv: (env) => ({
- *     title: 'My App',
- *     portal: { id: 'my-portal' },
- *     serviceDiscovery: { url: '...', scopes: ['...'] },
- *     msal: { tenantId: '...', clientId: '...', redirectUri: '...' },
- *   }),
- * };
- * ```
- */
-export type PluginOptions<TEnv extends TemplateEnv = TemplateEnv> = {
-  /**
-   * Custom HTML template string.
-   *
-   * @remarks
-   * When omitted the plugin uses a built-in template that loads the
-   * bootstrap script, sets the page title, and includes the Equinor font.
-   */
-  template?: string;
-
-  /**
-   * Prefix used when reading environment variables from `.env` files.
-   *
-   * @defaultValue `'FUSION_SPA_'`
-   */
-  templateEnvPrefix?: string;
-
-  /**
-   * Factory that returns partial environment values merged with defaults
-   * and flattened into `{templateEnvPrefix}*` variables.
-   *
-   * @see {@link TemplateEnvFn}
-   */
-  generateTemplateEnv?: TemplateEnvFn<TEnv>;
-
-  /**
-   * Optional logger used for plugin diagnostics during Vite config
-   * resolution.
-   */
-  logger?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
-};
-
-/**
- * Built-in defaults applied when no matching value is provided by
- * {@link PluginOptions.generateTemplateEnv} or `.env` files.
- */
-const defaultEnv: Partial<TemplateEnv> = {
-  title: 'Fusion SPA',
-  bootstrap: '/@fusion-spa-bootstrap.js',
-};
-
-/**
- * Creates the Fusion SPA Vite plugin.
- *
- * @remarks
- * The plugin hooks into Vite's `config`, `resolveId`, and `configureServer`
- * lifecycle to:
- *
- * 1. Flatten {@link PluginOptions.generateTemplateEnv | template env} values
- *    and `.env` overrides into `import.meta.env.FUSION_SPA_*` defines.
- * 2. Resolve virtual module IDs (`/@fusion-spa-bootstrap.js`,
- *    `/@fusion-spa-sw.js`) to the package's pre-built HTML assets.
- * 3. Serve the SPA HTML template for every `text/html` GET request
- *    (SPA fallback).
- *
- * @template TEnv - Shape of the template environment.
- * @param options - Plugin configuration. See {@link PluginOptions}.
- * @returns A Vite {@link Plugin} instance named `fusion-framework-plugin-spa`.
- *
- * @example
- * ```ts
- * import { plugin as fusionSpaPlugin } from '@equinor/fusion-framework-vite-plugin-spa';
- *
- * export default defineConfig({
- *   plugins: [
- *     fusionSpaPlugin({
- *       generateTemplateEnv: () => ({
- *         title: 'My App',
- *         portal: { id: 'my-portal' },
- *       }),
- *     }),
- *   ],
- * });
- * ```
- */
-export const plugin = <TEnv extends TemplateEnv = TemplateEnv>(
-  options?: PluginOptions<TEnv>,
-): Plugin => {
-  // SPA index template
-  const indexTemplate = options?.template ?? defaultTemplate;
-  const log = options?.logger;
-
-  return {
-    name: 'fusion-framework-plugin-spa',
-    resolveId: async (id) => {
-      // resolve resource aliases to the correct path
-      switch (id) {
-        case '/@fusion-spa-bootstrap.js': {
-          const file = await import.meta.resolve(
-            '@equinor/fusion-framework-vite-plugin-spa/bootstrap.js',
-          );
-          return fileURLToPath(file);
-        }
-        case '/@fusion-spa-sw.js': {
-          const file = await import.meta.resolve('@equinor/fusion-framework-vite-plugin-spa/sw.js');
-          return fileURLToPath(file);
-        }
-      }
-    },
-    config: async (config, configEnv) => {
-      const templateEnvPrefix = options?.templateEnvPrefix ?? 'FUSION_SPA_';
-      // generate environment variables from plugin options
-      const pluginEnvObj = { ...defaultEnv, ...options?.generateTemplateEnv?.(configEnv) };
-      const pluginEnv = objectToEnv(pluginEnvObj ?? defaultEnv, templateEnvPrefix);
-
-      log?.debug('plugin config environment\n', pluginEnv);
-
-      // load environment variables from files
-      const loadedEnv = loadEnvironment(config, configEnv, templateEnvPrefix);
-
-      log?.debug('plugin loaded environment\n', pluginEnv);
-
-      // Loaded env values override plugin-configured defaults
-      const env = { ...pluginEnv, ...loadedEnv };
-
-      log?.debug('plugin environment\n', env);
-
-      // define environment variables
-      config.define ??= {};
-      // Convert each env entry into a valid JS expression for Vite's config.define
-      for (const [key, value] of Object.entries(env)) {
-        // All values must be valid JavaScript expressions for Vite's config.define
-        // Try to parse as JSON first (handles booleans, numbers, objects, arrays)
-        // If that fails, stringify the raw value as a string literal
-        try {
-          const parsed = JSON.parse(String(value));
-          // Re-stringify to ensure it's a valid JS expression
-          config.define[`import.meta.env.${key}`] = JSON.stringify(parsed);
-        } catch {
-          // If JSON.parse fails, it's a plain string - wrap it as a JSON string for Vite
-          config.define[`import.meta.env.${key}`] = JSON.stringify(String(value));
-        }
-      }
-
-      config.server ??= {};
-      config.server.fs ??= {};
-      config.server.fs.allow ??= [];
-      // allow access to the html directory
-
-      const htmlDir = fileURLToPath(new URL('../html', import.meta.url));
-      config.server.fs.allow.push(normalizePath(htmlDir));
-
-      log?.info(`plugin configured for ${env.FUSION_SPA_PORTAL_ID}`);
-    },
-    configureServer(server) {
-      // Apply SPA fallback
-      server.middlewares.use(async (req, res, next) => {
-        // Skip if this is not a GET request or the request is not for HTML
-        if (!req.url || req.method !== 'GET' || !req.headers.accept?.includes('text/html')) {
-          return next();
-        }
-
-        const html = await server.transformIndexHtml(req.url, indexTemplate, req.originalUrl);
-
-        res.writeHead(200, {
-          'content-type': 'text/html',
-          'content-length': Buffer.byteLength(html),
-          'cache-control': 'no-cache',
-          ...server.config.server.headers,
-        });
-
-        return res.end(html);
-      });
-    },
-  };
-};
-
-export default plugin;

package/src/types.ts

@@ -1,160 +0,0 @@
-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;
-};
-
-/**
- * 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 = {
-  /** HTML `<title>` for the generated page. */
-  title: string;
-
-  /**
-   * 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;
-  };
-
-  /**
-   * 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 endpoint and authentication scopes. */
-  serviceDiscovery: {
-    /** URL of the Fusion service discovery endpoint. */
-    url: string;
-    /** OAuth scopes required to authenticate service discovery requests. */
-    scopes: string[];
-  };
-
-  /** 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;
-    /**
-     * When `'true'`, authentication is served by an in-process mock client
-     * instead of Entra ID — no credentials, redirects, or network calls.
-     * Intended for CI/Playwright runs against the dev server.
-     */
-    mock?: string | boolean;
-    /**
-     * A mock JWT (e.g. from `createMockToken`) whose payload claims (`name`,
-     * `preferred_username`, `oid`, `tid`, `scp`) become the signed-in mock
-     * user. Only read when {@link mock} is set; ignored otherwise.
-     */
-    mockToken?: string;
-  };
-
-  /** Service worker resource interception configuration. */
-  serviceWorker: {
-    /**
-     * Array of resource configurations the service worker will manage.
-     * @see {@link ResourceConfiguration}
-     */
-    resources: ResourceConfiguration[];
-  };
-};
-
-/**
- * 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 - 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,
-) => Partial<TEnv> | undefined;

package/src/util/load-environment.ts

@@ -1,35 +0,0 @@
-import { type ConfigEnv, loadEnv, type UserConfig } from 'vite';
-import { resolve } from 'node:path';
-
-/**
- * Loads environment variables from `.env` files for the Fusion SPA plugin.
- *
- * @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.
- *
- * 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,
-  env: ConfigEnv,
-  namespace = 'FUSION_SPA_',
-): Record<string, string> {
-  // resolve the root directory
-  const resolvedRoot = resolve(config.root || process.cwd());
-  // resolve the environment directory
-  const envDir = config.envDir ? resolve(resolvedRoot, config.envDir) : resolvedRoot;
-  // load environment variables from the specified directory
-  return loadEnv(env.mode, envDir, namespace);
-}
-
-export default loadEnvironment;