@equinor/fusion-framework-dev-server 1.0.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# @equinor/fusion-framework-dev-server
+
+## 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)! - Introduced a new package, `@equinor/fusion-framework-dev-server`, designed to provide a development server tailored for Fusion Framework applications. Built on top of Vite, it seamlessly integrates Vite and Fusion Framework configurations.
+
+  **Features**
+
+  - _`createDevServer` Function_: Simplifies the creation of a development server using a configuration object.
+  - _`createDevServerConfig` Function_: Generates a Vite-compatible configuration for the development server.
+  - _SPA Support_: Includes `spa.templateEnv` for defining environment variables specific to Single Page Applications.
+  - _API Service Discovery_: Enables proxying and route mapping for API services via `api.serviceDiscoveryUrl`.
+  - _Dynamic Proxy Routes_: Introduced the `processServices` function to remap Fusion services' URIs and dynamically generate proxy routes.
+  - _Logging_: Integrated `@equinor/fusion-log` for customizable logging, with dedicated sub-loggers for SPA and API services.
+
+  **Dependencies**
+
+  The following dependencies were added to support the new package:
+
+  - `@equinor/fusion-framework-vite-plugin-api-service`
+  - `@equinor/fusion-framework-vite-plugin-spa`
+  - `@equinor/fusion-log`
+
+  **Examples**
+
+  _Using `createDevServer`_
+
+  ```ts
+  import { createDevServer } from "@equinor/fusion-framework-dev-server";
+
+  const devServer = await createDevServer({
+    spa: {
+      templateEnv: {
+        portal: {
+          id: "dev-portal",
+        },
+        title: "My Test Dev Server",
+      },
+    },
+    api: {
+      serviceDiscoveryUrl: "https://location.of.your.service.discovery",
+      processServices: (data, route) => {
+        return {
+          data: data.concat({
+            key: "mock-service",
+            name: "Mock Service",
+            uri: "/mock-api",
+          }),
+          routes: [],
+        };
+      },
+    },
+  });
+  ```
+
+  _Using `createDevServerConfig`_
+
+  ```ts
+  import { createDevServerConfig } from "@equinor/fusion-framework-dev-server";
+
+  const config = createDevServerConfig({
+    spa: {
+      templateEnv: { API_URL: "https://api.example.com" },
+    },
+    api: {
+      serviceDiscoveryUrl: "https://discovery.example.com",
+      routes: ["/api"],
+    },
+  });
+  ```
+
+### 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)! - update Vite to 6.3.5
+
+- [#3074](https://github.com/equinor/fusion-framework/pull/3074) [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13) Thanks [@odinr](https://github.com/odinr)! - exported UserConfig interface from vite
+
+- 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), [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13)]:
+  - @equinor/fusion-framework-vite-plugin-spa@1.0.0-next.0
+  - @equinor/fusion-framework-vite-plugin-api-service@1.0.0-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/READDME.md

@@ -0,0 +1,108 @@
+# Fusion Framework Dev Server
+
+This package provides a development server for Fusion Framework applications.
+
+## Configuration
+
+This dev server is focused on Fusion Framework, but under the hood it uses Vite. The configuration is a mix of Vite and Fusion Framework.
+The dev server is created using the `createDevServer` function, which takes a configuration object as an argument.
+
+The first argument is the generic fusion framework configuration, which simplifies the configuration for the dev server.
+
+The second argument is the Vite configuration object, which is optional and overrides the default Vite configuration.
+see [Vite options](https://vite.dev/config/) for more details.
+
+> [!TIP]
+const devServer = await createDevServer({
+> You can use the `createDevServerConfig` to generate fusion configuration, then `Vite.mergeConfig` to merge with additional Vite configuration. Then create the dev server with `Vite.createServer`. The `createDevServer` function is a wrapper around this.
+
+### Basic Configuration
+
+The dev server requires a basic configuration object to be passed to it.
+
+```ts
+const devServer = await createDevServer({
+  spa: {
+    templateEnv: {
+      portal: {
+        id: '@equinor/fusion-framework-dev-portal',
+      }
+      title: 'My Test Dev Server',
+      serviceDiscovery: {
+        url: 'https://location.of.your.service.discovery',
+        scopes: ['scope_required'],
+      },
+      msal: {
+        clientId: 'dev-client-id',
+        tenantId: 'dev-tenant-id',
+        redirectUri: '/authentication/login-callback',
+        requiresAuth: 'true',
+      },
+    },
+  },
+});
+```
+
+### Adding Service Discovery
+
+By adding configuration to the `api` object, you can add service discovery to your dev server. This is useful for mocking API requests and setting up routes. see [@equinor/fusion-framework-vite-plugin-api-service](../vite-plugins/api-service/README.md) for more details.
+
+```ts
+createDevServer(
+  {
+    // Adding proxying for service discovery
+    api: {
+      // proxy target for service discovery
+      serviceDiscoveryUrl: 'https://location.of.your/service/discovery',
+      // method for modifying the service discovery response and setting up routes
+      processServices: (dataResponse, route) => {
+        const { data, routes } = processServices(dataResponse, route);
+        return {
+          data: data.concat({
+            key: 'portals',
+            name: 'Portal Service - MOCK',
+            uri: '/@fusion-api/portals',
+          }),
+          routes,
+        };
+      },
+    },
+    routes: [ /** add proxy and middleware routes */]
+  }
+);
+```
+
+
+## Proxying API Requests
+
+Sometimes proxy requests need authentication tokens, or need to be rewritten to a different path. The dev server can handle this by using the `serviceWorker` configuration.
+
+see [Vite server Proxy](https://vite.dev/config/server-options#server-proxy) for more details for setting up the proxy.
+
+```ts
+createDevServer(
+  {
+    ... // add basic configuration here
+
+    // intercepting requests to /api and rewriting them to /api-v1 and adding auth token
+    serviceWorker: {
+      resources: [
+        {
+          url: '/api',
+          rewrite: '/api-v1',
+          scopes: ['scope1', 'scope2'],
+        },
+      ],
+    }
+  }, 
+  {
+    proxy: {
+      '/api': {
+        target: 'https://api.example.com',
+        changeOrigin: true,
+        pathRewrite: { '^/api': '' },
+      },
+    },
+  }
+);
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@equinor/fusion-framework-dev-server",
+  "version": "1.0.0-next.0",
+  "description": "Package for running a development server for fusion-framework",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "types": "dist/types/index.d.ts",
+  "directories": {
+    "dist": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/equinor/fusion-framework.git",
+    "directory": "packages/dev-server"
+  },
+  "keywords": [
+    "dev-server",
+    "fusion-framework",
+    "vite",
+    "typescript"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@equinor/fusion-framework-vite-plugin-api-service": "^1.0.0-next.0",
+    "@equinor/fusion-framework-vite-plugin-spa": "^1.0.0-next.0",
+    "@equinor/fusion-log": "^1.1.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vite": "^6.3.5",
+    "vitest": "^2.0.5"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.7"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest"
+  }
+}

package/src/create-dev-server-config.ts

@@ -0,0 +1,94 @@
+import { defineConfig, mergeConfig, type UserConfig } from 'vite';
+import apiServicePlugin, {
+  createProxyHandler,
+} from '@equinor/fusion-framework-vite-plugin-api-service';
+
+import fusionSpaPlugin from '@equinor/fusion-framework-vite-plugin-spa';
+import { ConsoleLogger, LogLevel } from '@equinor/fusion-log';
+
+import defaultProcessServices from './process-services.js';
+
+import type { DevServerOptions, TemplateEnv, TemplateEnvFn } from './types.js';
+
+const createDefaultLogger = (lvl: LogLevel = LogLevel.Info, title = 'dev-server') => {
+  const logger = new ConsoleLogger(title);
+  logger.level = lvl;
+  return logger;
+};
+
+/**
+ * Creates a development server configuration for a Fusion Framework application.
+ *
+ * @template TEnv - A type extending `Partial<TemplateEnv>` that represents the environment variables for the template.
+ * @param options - The options for configuring the development server.
+ * @param options.spa - Configuration for the Single Page Application (SPA), including template environment settings.
+ * @param options.api - Configuration for the API, including service discovery URL, routes, and service processing logic.
+ *
+ * @returns A `UserConfig` object that defines the Vite development server configuration.
+ *
+ * @remarks
+ * - The `spa.templateEnv` can either be a function or a partial object of type `TEnv`.
+ * - The `api.processServices` defaults to `defaultProcessServices` if not provided.
+ * - The server is configured to run on port 3000.
+ * - Includes plugins for API service handling and SPA template environment generation.
+ *
+ * @example
+ * ```typescript
+ * const config = createDevServerConfig({
+ *   spa: {
+ *     templateEnv: { API_URL: 'https://api.example.com' },
+ *   },
+ *   api: {
+ *     serviceDiscoveryUrl: 'https://discovery.example.com',
+ *     routes: ['/api'],
+ *   },
+ * });
+ * ```
+ */
+export const createDevServerConfig = <TEnv extends Partial<TemplateEnv>>(
+  options: DevServerOptions<TEnv>,
+  overrides?: UserConfig,
+): UserConfig => {
+  const { spa, api, log, server } = options;
+  const processServices = api.processServices ?? defaultProcessServices;
+  const generateTemplateEnv: TemplateEnvFn<TEnv> =
+    // ensure that the templateEnv is a function
+    typeof spa?.templateEnv === 'function'
+      ? spa.templateEnv
+      : () => spa?.templateEnv as Partial<TEnv>;
+
+  // setup log instance
+  const logger = log?.logger ?? createDefaultLogger(log?.level);
+
+  const apiServiceLogger = logger.createSubLogger('api-service');
+  const spaLogger = logger.createSubLogger('spa');
+
+  const baseConfig = defineConfig({
+    appType: 'custom',
+    define: {
+      'process.env': JSON.stringify({
+        FUSION_LOG_LEVEL: String(logger.level),
+      }),
+    },
+    server: {
+      ...server,
+    },
+    plugins: [
+      apiServicePlugin(
+        {
+          proxyHandler: createProxyHandler(api.serviceDiscoveryUrl, processServices, {
+            logger: apiServiceLogger,
+          }),
+          routes: api.routes,
+        },
+        {
+          logger: apiServiceLogger,
+        },
+      ),
+      fusionSpaPlugin({ generateTemplateEnv, logger: spaLogger }),
+    ],
+  });
+  return mergeConfig(baseConfig, overrides ?? {});
+};
+
+export default createDevServerConfig;

package/src/create-dev-server.ts

@@ -0,0 +1,18 @@
+import { createServer, type UserConfig } from 'vite';
+import createDevServerConfig from './create-dev-server-config.js';
+
+import type { DevServerOptions } from './types.js';
+
+/**
+ * Asynchronously creates and configures a development server instance.
+ *
+ * @param options - The options used to configure the development server.
+ * @returns A promise that resolves to the created development server instance.
+ */
+export const createDevServer = async (options: DevServerOptions, overrides?: UserConfig) => {
+  const config = createDevServerConfig(options, overrides);
+  const server = await createServer(config);
+  return server;
+};
+
+export default createDevServer;

package/src/index.ts

@@ -0,0 +1,11 @@
+export type { UserConfig } from 'vite';
+
+export { processServices } from './process-services.js';
+
+export { default, createDevServer } from './create-dev-server.js';
+
+export { createDevServerConfig } from './create-dev-server-config.js';
+
+export type { FusionTemplateEnv } from '@equinor/fusion-framework-vite-plugin-spa';
+
+export * from './types.js';

package/src/process-services.ts

@@ -0,0 +1,87 @@
+import type { ApiDataProcessor, ApiRoute } from '@equinor/fusion-framework-vite-plugin-api-service';
+import type { FusionService } from './types.js';
+
+/**
+ * Processes an array of Fusion services, remapping their URIs to proxy through the development server
+ * and generating corresponding proxy routes.
+ *
+ * @template T - The type of the input data, expected to be an array of `FusionService`.
+ * @param data - The input array of Fusion services to process.
+ * @param args - Additional arguments containing the route and request information.
+ * @param args.route - The base route used to construct the proxy paths.
+ * @param args.request - The HTTP request object, used to extract the referer header.
+ * @returns An object containing the processed services and the generated proxy routes.
+ * @throws {Error} If the input data is not an array.
+ *
+ * @example
+ * ```typescript
+ * const services = [
+ *   { key: 'service1', uri: 'http://example.com/api', name: 'Service 1' },
+ *   { key: 'service2', uri: 'http://example.org/api', name: 'Service 2' },
+ * ];
+ * const args = {
+ *   route: '/proxy',
+ *   request: { headers: { referer: 'http://localhost:3000' } },
+ * };
+ * const result = processServices(services, args);
+ * console.log(result.data); // Processed services with updated URIs
+ *
+ * // Expected output:
+ * // result.data:
+ * // [
+ * //   { key: 'service1', uri: 'http://localhost:3000/proxy/service1', name: 'Service 1' },
+ * //   { key: 'service2', uri: 'http://localhost:3000/proxy/service2', name: 'Service 2' },
+ * // ]
+ *
+ * console.log(result.routes); // Generated proxy routes
+ *
+ * // result.routes:
+ * // [
+ * //   {
+ * //     match: '/service1/api*sub',
+ * //     proxy: {
+ * //       target: 'http://example.com',
+ * //       rewrite: (path) => path.replace('/service1', ''),
+ * //     },
+ * //   },
+ * //   {
+ * //     match: '/service2/api*sub',
+ * //     proxy: {
+ * //       target: 'http://example.org',
+ * //       rewrite: (path) => path.replace('/service2', ''),
+ * //     },
+ * //   },
+ * // ]
+ * ```
+ */
+export const processServices: ApiDataProcessor<FusionService[]> = (data, args) => {
+  const { route, request } = args;
+  const apiRoutes = [] as ApiRoute[];
+  const apiServices = [] as FusionService[];
+
+  if (!Array.isArray(data)) {
+    throw new Error('Invalid data format');
+  }
+
+  // remap all services to proxy though the dev server
+  // and generate the proxy routes
+  for (const service of data as FusionService[]) {
+    // append host, port and protocol to the service uri
+    // and replace the path with the local proxy path
+    const serviceUrl = new URL(`${route}/${service.key}`, request.headers.referer);
+    apiServices.push({ ...service, uri: String(serviceUrl) });
+
+    // add the proxy route
+    const url = new URL(service.uri);
+    apiRoutes.push({
+      match: `/${service.key}${url.pathname}*sub`,
+      proxy: {
+        target: url.origin,
+        rewrite: (path) => path.replace(`/${service.key}`, ''),
+      },
+    });
+  }
+  return { data: apiServices, routes: apiRoutes };
+};
+
+export default processServices;

package/src/types.ts

@@ -0,0 +1,48 @@
+import type { ApiDataProcessor, ApiRoute } from '@equinor/fusion-framework-vite-plugin-api-service';
+import type { FusionTemplateEnv, TemplateEnvFn } from '@equinor/fusion-framework-vite-plugin-spa';
+import type { ConsoleLogger } from '@equinor/fusion-log';
+
+export type FusionService = {
+  key: string;
+  uri: string;
+  name: string;
+};
+
+export {
+  FusionTemplateEnv as TemplateEnv,
+  TemplateEnvFn,
+} from '@equinor/fusion-framework-vite-plugin-spa';
+
+export { UserConfig as DevServerOverrides } from 'vite';
+
+export type DevServerOptions<TEnv extends Partial<FusionTemplateEnv> = Partial<FusionTemplateEnv>> =
+  {
+    spa?: {
+      templateEnv: TEnv | TemplateEnvFn<TEnv>;
+    };
+    api: {
+      /**
+       * The URL of the service discovery proxy endpoint.
+       */
+      serviceDiscoveryUrl: string;
+
+      /**
+       * Route mapper for processing service discovery data.
+       */
+      processServices?: ApiDataProcessor<FusionService[]>;
+
+      /**
+       * Additional routes to be added to the API service proxy.
+       * @note used for overriding proxy responses and mocking services.
+       */
+      routes?: ApiRoute[];
+    };
+    log?: {
+      level?: number;
+      logger?: ConsoleLogger;
+    };
+    server?: {
+      port?: number;
+      host?: string;
+    };
+  };

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,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist/esm",
+    "declarationDir": "./dist/types",
+    "baseUrl": "."
+  },
+  "references": [
+    {
+      "path": "../vite-plugins/api-service"
+    },
+    {
+      "path": "../vite-plugins/spa"
+    }
+  ],
+  "include": ["src/**/*", "tests/*"],
+  "exclude": ["node_modules", "tests"]
+}