@equinor/fusion-framework-vite-plugin-spa 1.0.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# @equinor/fusion-framework-vite-plugin-spa
+
+## 1.0.0-next.0
+
+### Major Changes
+
+- [#3074](https://github.com/equinor/fusion-framework/pull/3074) [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13) Thanks [@odinr](https://github.com/odinr)! - ---
+
+  **New Package: Fusion Framework Vite SPA Plugin**
+
+  This plugin enables building single-page applications (SPAs) with Vite. It provides features such as service discovery, MSAL authentication, and service worker configuration.
+
+  **Features**:
+
+  - **Service Discovery**: Fetch service discovery configurations and authenticate requests.
+  - **MSAL Authentication**: Authenticate users with Azure AD.
+  - **Service Worker**: Intercept fetch requests, apply authentication headers, and rewrite URLs.
+  - **Custom Templates**: Define custom HTML templates for SPAs.
+  - **Environment Configuration**: Configure the plugin using `.env` files or programmatically.
+
+  **Usage**:
+
+  ```ts
+  import { defineConfig } from "vite";
+  import { plugin as fusionSpaPlugin } from "@equinor/fusion-framework-vite-plugin-spa";
+
+  export default defineConfig({
+    plugins: [fusionSpaPlugin()],
+  });
+  ```
+
+  ```ts
+  fusionSpaPlugin({
+    generateTemplateEnv: () => ({
+      title: "My App",
+      portal: {
+        id: "my-portal",
+      },
+      serviceDiscovery: {
+        url: "https://my-server.com/service-discovery",
+        scopes: ["api://my-app/scope"],
+      },
+      msal: {
+        tenantId: "my-tenant-id",
+        clientId: "my-client-id",
+        redirectUri: "https://my-app.com/auth-callback",
+        requiresAuth: "true",
+      },
+      serviceWorker: {
+        resources: [
+          {
+            url: "/app-proxy",
+            rewrite: "/@fusion-api/app",
+            scopes: ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default"],
+          },
+        ],
+      },
+    }),
+  });
+  ```
+
+  **Additional Details**:
+
+  - **Custom Bootstrap**: Allows defining custom bootloader scripts.
+  - **Dynamic Proxy**: Supports dynamic proxy services using `@equinor/fusion-framework-vite-plugin-api-service`.
+  - **Environment Variables**: Automatically maps `.env` variables to `import.meta.env`.
+
+  Refer to the README for detailed documentation.
+
+### Patch Changes
+
+- [#3074](https://github.com/equinor/fusion-framework/pull/3074) [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13) Thanks [@odinr](https://github.com/odinr)! - Fetch and pass portal config to portal render function in bootstrap.ts
+
+  - The SPA bootstrap script now fetches the portal config from `/portals/{portalId}@{portalTag}/config` and passes it as `config` to the portal's render function.
+  - This enables portals to receive their runtime configuration directly at startup.
+
+- [#3074](https://github.com/equinor/fusion-framework/pull/3074) [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13) Thanks [@odinr](https://github.com/odinr)! - update Vite to 6.3.5
+
+- Updated dependencies [[`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13), [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13), [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13)]:
+  - @equinor/fusion-framework-vite-plugin-api-service@1.0.0-next.0
+  - @equinor/fusion-framework-module-http@6.3.3-next.0
+  - @equinor/fusion-framework-module-service-discovery@8.0.15-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Equinor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# Fusion Framework Vite SPA Plugin
+
+This plugin is used to build a single page application (SPA) with Vite.
+
+## Usage
+
+```ts
+import { defineConfig } from 'vite';
+import { plugin as fusionSpaPlugin } from '@equinor/fusion-framework-vite-plugin-spa';
+
+export default defineConfig({
+  plugins: [fusionSpaPlugin()],
+});
+```
+
+## Configure the plugin
+
+```ts
+fusionSpaPlugin({
+  generateTemplateEnv: () => {
+    return {
+      title: 'My App',
+      portal: {
+        id: 'my-portal',
+      },
+      serviceDiscovery: {
+        url: 'https://my-server.com/service-discovery',
+        scopes: ['api://my-app/scope'],
+      },
+      msal: {
+        tenantId: 'my-tenant-id',
+        clientId: 'my-client-id',
+        redirectUri: 'https://my-app.com/auth-callback',
+        requiresAuth: 'true',
+      },
+      serviceWorker: {
+        resources: [
+          {
+            url: '/app-proxy',
+            rewrite: '/@fusion-api/app',
+            scopes: ['xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default'],
+        ],
+      },
+    }
+  }
+});
+```
+
+### Service Discovery
+
+The service discovery URL is used to fetch the service discovery configuration from the server.
+The service discovery scopes are used to authenticate the service discovery request.
+
+### MSAL
+
+The MSAL configuration is used to authenticate the user with Azure AD.
+- `tenantId` is the ID of the Azure AD tenant.
+- `clientId` is the ID of the Azure AD application.
+- `redirectUri` is the URL to redirect the user to after authentication.
+- `requiresAuth` _(optional)_ property is used to specify if the framework requires authentication, will try to login user on initial load.
+
+### Service Worker
+
+The service worker configuration is used to configure routes for the service worker.
+
+When `fetch` calls are made to the `url` path, the service worker will intercept the request and apply authentication headers to the request for the specified scopes. The request url will be rewritten to the `rewrite` path, by replacing the `url` with the `rewrite` path.
+
+- `resources` is an array of resources which the service worker will handle.
+  -  `url` path to match requests to
+  -  `rewrite` _(optional)_ path to replace the `url` with
+  -  `scopes` _(optional)_ is an array of scopes to use for the resource.
+
+Example:
+```ts
+const serviceWorker = {
+  resources: [
+    {
+      url: '/app-proxy',
+      rewrite: '/@fusion-api/app',
+      scopes: [
+        '2bed749c-843b-413d-8b17-e7841869730f/.default',
+        '8c24cf81-de7a-435b-ab74-e90b1a7bda0a/.default'
+      ],
+    },
+  ],
+};
+
+fetch('/app-proxy/assets/some-app/resource-path/resource.json');
+```
+1. The request will be intercepted by the service worker.
+2. The service worker will post message to the main thread for authentication.
+3. The main thread will generate the authentication token for the specified scopes.
+4. The service worker will rewrite the request to `/@fusion-api/app/assets/some-app/resource-path/resource.json`.
+5. The service worker will execute the request to the rewritten path with the authentication token.
+
+> [!TIP]
+> The `Url` does not have an endpoint, it is just a path to match the request to, 
+> so that url can emulate a proxy service in the production environment.
+> The `rewrite` path is the actual endpoint to call.
+
+> [!TIP]
+> Using the `@equinor/fusion-framework-vite-plugin-api-service` plugin,
+> you can create a dynamic proxy service that will handle the request.
+> 
+> The `/@fusion-api/app` points to proxy route which can be intercepted in the dev-server. 
+> This endpoint is generated from the service discovery configuration and will dynamically proxy the request to the service discovery endpoint.  
+
+## Configuring through `.env` file
+
+The plugin can be configured through a `.env` file. The plugin will read the `.env` file and override the properties in the `generateTemplateEnv` function.
+
+The property names are prefixed with `FUSION_SPA_` and snake cased. 
+
+example:
+
+```ts
+{
+  serviceWorker: {
+    resources: [...],
+  },
+}
+// will be converted to
+FUSION_SPA_SERVICE_WORKER_RESOURCES: [...],
+
+// and accessible in the template as
+import.meta.env.FUSION_SPA_SERVICE_WORKER_RESOURCES
+```
+
+> [!TIP]
+> Prefer to use the `generateTemplateEnv` function to provide the properties.
+> The `.env` file is used to override configurations, example in an CI/CD pipeline.
+
+> [!IMPORTANT]
+> The `.env` file should be placed in the root of the project.
+> Parameters from the `.env` file overrides the parameters from the `generateTemplateEnv` function.
+
+```
+FUSION_SPA_TITLE=My App
+FUSION_SPA_PORTAL_ID=my-portal
+FUSION_SPA_SERVICE_DISCOVERY_URL=https://my-server.com/service-discovery
+FUSION_SPA_SERVICE_DISCOVERY_SCOPES=[api://my-app/scope]
+FUSION_SPA_MSAL_TENANT_ID=my-tenant-id
+FUSION_SPA_MSAL_CLIENT_ID=my-client-id
+FUSION_SPA_MSAL_REDIRECT_URI=https://my-app.com/auth-callback
+FUSION_SPA_MSAL_REQUIRES_AUTH=true
+FUSION_SPA_SERVICE_WORKER_RESOURCES=[{"url":"/app-proxy","rewrite":"/@fusion-api/app","scopes":["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default"]}]
+```
+
+## Providing a custom template
+
+> [!WARNING]
+> Your almost walking on the edge of the framework. Be careful.
+> At this point you might just define your own template and the plugin will inject the properties into the template.
+
+```ts
+const template = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <script type="module" src="./src/my-custom-bootloader"></script>
+</head>
+<body>
+  <h1>%MY_CUSTOM_PROPERTY%</h1>
+  <div id="app"></div>
+</body>
+</html>
+`;
+
+import { defineConfig } from 'vite';
+import { createViteSPAPlugin } from '@equinor/fusion-framework-vite-plugin-spa';
+
+const templateEnvPrefix = 'MY_CUSTOM_';
+
+export default defineConfig({
+  define: {
+    `import.meta.env.${templateEnvPrefix}PROPERTY`: 'my-custom-value',
+  },
+  plugins: [createViteSPAPlugin({template, templateEnvPrefix})],
+});
+```
+
+> [!TIP]
+> see [Vite documentation](https://vite.dev/guide/env-and-mode.html#html-constant-replacement) for more information about customizing the template.
+
+### Providing custom bootstrap
+
+```ts
+fusionSpaPlugin({
+  generateTemplateEnv: () => {
+    return {
+      bootstrap: 'src/my-custom-bootloader.ts',
+    }
+  }
+});
+```
+
+> [!WARNING]
+> The bootstrapping of the `ServiceWorker` is done in the the bootloader, 
+> this functionality will no longer be available, but needs to be re-implemented in the custom bootloader.
+
+
+```ts
+// custom-bootloader.ts
+import { registerServiceWorker} from '@equinor/fusion-framework-vite-plugin-spa/html';
+
+import initializeFramework from './my-custom-framework.js';
+
+registerServiceWorker(await initializeFramework());
+```
+
+

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@equinor/fusion-framework-vite-plugin-spa",
+  "version": "1.0.0-next.0",
+  "description": "Vite plugin for SPA development",
+  "type": "module",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./html": {
+      "import": "./dist/esm/html/index.js",
+      "types": "./dist/types/html/index.d.ts"
+    }
+  },
+  "directories": {
+    "dist": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/equinor/fusion-framework.git",
+    "directory": "packages/vite-plugins/spa"
+  },
+  "keywords": [
+    "vite",
+    "fusion-framework",
+    "dev-server",
+    "typescript"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "lodash.mergewith": "^4.6.2",
+    "@equinor/fusion-framework-module": "^4.4.2",
+    "@equinor/fusion-framework-module-http": "^6.3.3-next.0",
+    "@equinor/fusion-framework-module-msal": "^4.0.6",
+    "@equinor/fusion-framework-module-service-discovery": "^8.0.15-next.0",
+    "@equinor/fusion-framework-vite-plugin-api-service": "^1.0.0-next.0"
+  },
+  "devDependencies": {
+    "@types/lodash.mergewith": "^4.6.9",
+    "typescript": "^5.5.4",
+    "vite": "^6.3.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest"
+  }
+}

package/src/html/bootstrap.ts

@@ -0,0 +1,90 @@
+import { ModulesConfigurator } from '@equinor/fusion-framework-module';
+
+import { configureHttpClient, type HttpModule } from '@equinor/fusion-framework-module-http';
+import { enableMSAL, type MsalModule } from '@equinor/fusion-framework-module-msal';
+import {
+  enableServiceDiscovery,
+  type ServiceDiscoveryModule,
+} from '@equinor/fusion-framework-module-service-discovery';
+import { registerServiceWorker } from './register-service-worker.js';
+
+// @todo - add type for portal manifest when available
+type PortalManifest = {
+  build: {
+    config: Record<string, unknown>;
+    entrypoint: string;
+  };
+};
+
+// Allow dynamic import without vite
+const importWithoutVite = <T>(path: string): Promise<T> => import(/* @vite-ignore */ path);
+
+// Create Fusion Framework configurator
+const configurator = new ModulesConfigurator();
+
+configurator.logger.level = import.meta.env.FUSION_SPA_LOG_LEVEL ?? 1;
+
+const serviceDiscoveryUrl = new URL(
+  import.meta.env.FUSION_SPA_SERVICE_DISCOVERY_URL,
+  import.meta.env.FUSION_SPA_SERVICE_DISCOVERY_URL.startsWith('http')
+    ? undefined
+    : window.location.origin,
+);
+
+// define service discovery client - this is used in the service discovery module
+configurator.addConfig(
+  configureHttpClient('service_discovery', {
+    baseUri: String(serviceDiscoveryUrl),
+    defaultScopes: import.meta.env.FUSION_SPA_SERVICE_DISCOVERY_SCOPES,
+  }),
+);
+
+// setup service discovery - enable service discovery for the framework
+enableServiceDiscovery(configurator, async (builder) => {
+  builder.configureServiceDiscoveryClientByClientKey('service_discovery');
+});
+
+// setup authentication
+enableMSAL(configurator, (builder) => {
+  builder.setClientConfig({
+    tenantId: import.meta.env.FUSION_SPA_MSAL_TENANT_ID,
+    clientId: import.meta.env.FUSION_SPA_MSAL_CLIENT_ID,
+    redirectUri: import.meta.env.FUSION_SPA_MSAL_REDIRECT_URI,
+  });
+
+  builder.setRequiresAuth(Boolean(import.meta.env.FUSION_SPA_MSAL_REQUIRES_AUTH));
+});
+
+(async () => {
+  // initialize the framework - this will create the framework instance and configure the modules
+  const ref = await configurator.initialize<[ServiceDiscoveryModule, HttpModule, MsalModule]>();
+
+  // attach service discovery to the framework - append auth token to configured endpoints
+  await registerServiceWorker(ref);
+
+  // create a client for the portal service - this is used to fetch the portal manifest
+  const portalClient = await ref.serviceDiscovery.createClient('portals');
+
+  // fetch the portal manifest - this is used to load the portal template
+  const portalId = import.meta.env.FUSION_SPA_PORTAL_ID;
+  const portalTag = import.meta.env.FUSION_SPA_PORTAL_TAG ?? 'latest';
+  const portal_manifest = await portalClient.json<PortalManifest>(
+    `/portals/${portalId}@${portalTag}`,
+  );
+
+  const portal_config = await portalClient.json(`/portals/${portalId}@${portalTag}/config`);
+
+  // create a entrypoint for the portal - this is used to render the portal
+  const el = document.createElement('div');
+  document.body.innerHTML = '';
+  document.body.appendChild(el);
+
+  // @todo: should test if the entrypoint is external or internal
+  // @todo: add proper return type
+  const { render } = await importWithoutVite<Promise<{ render: (...args: unknown[]) => void }>>(
+    portal_manifest.build.entrypoint,
+  );
+
+  // render the portal - this will load the portal template and render it
+  render(el, { ref, manifest: portal_manifest, config: portal_config });
+})();

package/src/html/index.html.ts

@@ -0,0 +1,52 @@
+import { version } from '../version.js';
+
+/**
+ * Represents an HTML template string used for generating the main structure of an SPA (Single Page Application).
+ *
+ * @see {@link https://vite.dev/guide/env-and-mode.html#html-constant-replacement}
+ *
+ * The template includes placeholders for dynamic values such as:
+ * - `%FUSION_SPA_TITLE%`: The title of the SPA.
+ * - `%MODE%`: The mode of the application (e.g., development, production).
+ * - `%FUSION_SPA_BOOTSTRAP%`: The path to the bootstrap script for initializing the SPA.
+ *
+ * Additionally, it includes:
+ * - A meta tag for the plugin version, dynamically populated using the `version` variable.
+ * - A link to the Equinor font stylesheet hosted on a CDN.
+ *
+ * @constant
+ * @type {string}
+ */
+export const html = `
+  <!DOCTYPE html>
+  <html>
+    <head>
+      <title>%FUSION_SPA_TITLE%</title>
+      <meta name="mode" content="%MODE%">
+      <meta name="fusion-spa-plugin-version" content="${version}">
+      <link rel="stylesheet" href="https://cdn.eds.equinor.com/font/equinor-font.css" />
+      <script type="module" src="%FUSION_SPA_BOOTSTRAP%"></script>
+      <script>
+        // suppress console error for custom elements already defined. 
+        // WebComponents should be added by the portal, but not removed from application
+        const _customElementsDefine = window.customElements.define;
+        window.customElements.define = (name, cl, conf) => {
+          if (!customElements.get(name)) {
+            _customElementsDefine.call(window.customElements, name, cl, conf);
+          }
+        };
+      </script>
+      <style>
+        html, body {
+          margin: 0;
+          padding: 0;
+          height: 100%;
+          font-family: 'EquinorFont', sans-serif;
+        }
+      </style>
+    </head>
+    <body></body>
+  </html>
+`;
+
+export default html;

package/src/html/index.ts

@@ -0,0 +1 @@
+export { registerServiceWorker } from './register-service-worker.js';

package/src/html/register-service-worker.ts

@@ -0,0 +1,67 @@
+import type { ModulesInstance } from '@equinor/fusion-framework-module';
+import type { MsalModule } from '@equinor/fusion-framework-module-msal';
+
+export async function registerServiceWorker(framework: ModulesInstance<[MsalModule]>) {
+  if ('serviceWorker' in navigator === false) {
+    console.warn('Service workers are not supported in this browser.');
+    return;
+  }
+
+  const resourceConfigs = import.meta.env.FUSION_SPA_SERVICE_WORKER_RESOURCES;
+  if (!resourceConfigs) {
+    console.warn('Service worker config is not defined.');
+    return;
+  }
+
+  try {
+    // register the service worker
+    const registration = await navigator.serviceWorker.register('/@fusion-spa-sw.js', {
+      type: 'module',
+      scope: '/',
+    });
+
+    // wait for the service worker to be ready
+    await navigator.serviceWorker.ready;
+
+    // allow the service worker to start receiving messages
+    navigator.serviceWorker.startMessages();
+
+    // send the config to the service worker
+    registration.active?.postMessage({
+      type: 'INIT_CONFIG',
+      config: resourceConfigs,
+    });
+
+    // listen for messages from the service worker
+    navigator.serviceWorker.addEventListener('message', async (event) => {
+      if (event.data.type === 'GET_TOKEN') {
+        try {
+          // extract scopes from the event data
+          const scopes = event.data.scopes as string[];
+          if (!scopes || !Array.isArray(scopes)) {
+            throw new Error('Invalid scopes provided');
+          }
+
+          // request a token from the MSAL module
+          const token = await framework.auth.acquireToken({ scopes });
+
+          if (!token) {
+            throw new Error('Failed to acquire token');
+          }
+
+          // send the token back to the service worker
+          event.ports[0].postMessage({
+            accessToken: token.accessToken,
+            expiresOn: token.expiresOn?.getTime(),
+          });
+        } catch (error) {
+          event.ports[0].postMessage({
+            error: (error as Error).message,
+          });
+        }
+      }
+    });
+  } catch (error) {
+    console.error('Service Worker registration failed:', error);
+  }
+}

package/src/html/sw.ts

@@ -0,0 +1,211 @@
+/// <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);
+  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) => {
+      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]);
+  });
+
+  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) || {};
+  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 {
+  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', (event: ExtendableMessageEvent) => {
+  const { type, config } = event.data;
+  if (type === 'INIT_CONFIG') {
+    resourceConfigurations = config as ResourceConfiguration[];
+  }
+});
+
+// Handle fetch events
+self.addEventListener('fetch', (event: FetchEvent) => {
+  const url = new URL(event.request.url);
+  const matchedConfig = getMatchingConfig(url.toString());
+
+  // only handle requests that match the config
+  if (matchedConfig) {
+    const requestHeaders = new Headers(event.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);
+      }
+
+      // fetch the request with the modified url and headers
+      return fetch(url, { headers: requestHeaders });
+    };
+    event.respondWith(handleRequest());
+  }
+});

package/src/index.ts

@@ -0,0 +1,3 @@
+export { default, plugin as fusionSpaPlugin, type PluginOptions } from './plugin.js';
+
+export * from './types.js';

package/src/plugin.ts

@@ -0,0 +1,103 @@
+import type { Plugin } from 'vite';
+
+import mergeWith from 'lodash.mergewith';
+
+import defaultTemplate from './html/index.html.js';
+
+import { objectToEnv } from './util/object-to-env.js';
+import { loadEnvironment } from './util/load-env.js';
+
+import type { TemplateEnv, TemplateEnvFn } from './types.js';
+
+/**
+ * Represents the options for configuring a plugin.
+ *
+ * @template TEnv - The type of the template environment. Defaults to `TemplateEnv`.
+ *
+ * @property {string} [template] - The path to the template file to be used.
+ * @property {string} [templateEnvPrefix] - A prefix to filter environment variables for the template.
+ * @property generateTemplateEnv -
+ *    A function to generate the template environment. It receives the configuration environment and
+ *    a partial template environment as arguments, and returns a modified or extended partial template environment.
+ */
+export type PluginOptions<TEnv extends TemplateEnv = TemplateEnv> = {
+  template?: string;
+  templateEnvPrefix?: string;
+  generateTemplateEnv?: TemplateEnvFn<TEnv>;
+  logger?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
+};
+
+/**
+ * Represents the default environment configuration for the Fusion SPA.
+ */
+const defaultEnv: Partial<TemplateEnv> = {
+  title: 'Fusion SPA',
+  bootstrap: '/@fusion-spa-bootstrap.js',
+};
+
+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(id) {
+      // resolve resource aliases to the correct path
+      switch (id) {
+        case '/@fusion-spa-bootstrap.js':
+          return new URL('./html/bootstrap.js', import.meta.url).pathname;
+        case '/@fusion-spa-sw.js':
+          return new URL('./html/sw.js', import.meta.url).pathname;
+      }
+    },
+    config(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);
+
+      const env = mergeWith(pluginEnv, loadedEnv);
+
+      log?.debug('plugin environment\n', env);
+
+      // define environment variables
+      config.define ??= {};
+      for (const [key, value] of Object.entries(env)) {
+        config.define[`import.meta.env.${key}`] = value;
+      }
+      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

@@ -0,0 +1,54 @@
+import type { ConfigEnv } from 'vite';
+
+export type TemplateEnv = Record<string, unknown>;
+
+export type ResourceConfiguration = {
+  url: string;
+  scopes?: string[];
+  rewrite?: string;
+};
+
+/**
+ * Represents the environment configuration for a template.
+ */
+export type FusionTemplateEnv = {
+  /** Document title */
+  title: string;
+  /** Template bootstrap file path */
+  bootstrap: string;
+
+  /** Id of the portal to load */
+  portal: {
+    id: string;
+    tag?: string;
+  };
+
+  /** Service discovery configuration */
+  serviceDiscovery: {
+    url: string;
+    scopes: string[];
+  };
+
+  /** MSAL configuration */
+  msal: {
+    tenantId: string;
+    clientId: string;
+    redirectUri: string;
+    requiresAuth: string;
+  };
+  /** Service worker configuration */
+  serviceWorker: {
+    resources: ResourceConfiguration[];
+  };
+};
+
+/**
+ * A function type that generates a partial environment configuration for a template.
+ *
+ * @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.
+ */
+export type TemplateEnvFn<TEnv extends TemplateEnv> = (
+  configEnv: ConfigEnv,
+) => Partial<TEnv> | undefined;

package/src/util/load-env.ts

@@ -0,0 +1,29 @@
+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.
+ *
+ * @see {@link http://vite.dev/guide/env-and-mode.html#env-files}
+ *
+ * @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_`.
+ */
+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;

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

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * const input = {
+ *   someKey: "value",
+ *   nestedObject: {
+ *     anotherKey: 42,
+ *     deepNested: {
+ *       finalKey: true
+ *     }
+ *   }
+ * };
+ *
+ * const result = objectToEnv(input);
+ * console.log(result);
+ * // Output:
+ * // {
+ * //   SOME_KEY: "\"value\"",
+ * //   NESTED_OBJECT_ANOTHER_KEY: "42",
+ * //   NESTED_OBJECT_DEEP_NESTED_FINAL_KEY: "true"
+ * // }
+ * ```
+ */
+export function objectToEnv(obj: object, prefix = 'FUSION_SPA'): Record<string, string> {
+  return Object.entries(obj).reduce((result, [key, value]) => {
+    // Convert camelCase to snake_case and uppercase
+    const snakeKey = key.replace(/([A-Z])/g, '_$1').toUpperCase();
+
+    const newPrefix = prefix ? `${prefix.replace(/_$/, '')}_${snakeKey}` : snakeKey;
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Recursively flatten nested objects
+      return Object.assign(result, objectToEnv(value, newPrefix));
+    }
+    // Stringify non-object values
+    return Object.assign(result, { [newPrefix]: JSON.stringify(value) });
+  }, {});
+}
+
+export default objectToEnv;

package/src/version.ts

@@ -0,0 +1,2 @@
+// Generated by genversion.
+export const version = '1.0.0-next.0';

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "rootDir": "src",
+    "declarationDir": "./dist/types",
+    "baseUrl": ".",
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}