@equinor/fusion-framework-dev-server 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @equinor/fusion-framework-dev-server
 
+## 1.1.5
+
+### Patch Changes
+
+- Updated dependencies [[`99a3c26`](https://github.com/equinor/fusion-framework/commit/99a3c26275c2089c3708124f5819ce383d8dc3dc)]:
+  - @equinor/fusion-framework-vite-plugin-spa@1.2.0
+
+## 1.1.4
+
+### Patch Changes
+
+- [#3532](https://github.com/equinor/fusion-framework/pull/3532) [`63ecde5`](https://github.com/equinor/fusion-framework/commit/63ecde5c29e775b341c3fac0c1eeb7123db5e2db) Thanks [@dependabot](https://github.com/apps/dependabot)! - Bump vite from 7.1.8 to 7.1.9 across development tools and plugins.
+
+  This patch update fixes bugs and improves stability in the vite dependency.
+
+- Updated dependencies [[`45954e5`](https://github.com/equinor/fusion-framework/commit/45954e5db471a2faa24e88e41fc6d6c18817d6d1), [`63ecde5`](https://github.com/equinor/fusion-framework/commit/63ecde5c29e775b341c3fac0c1eeb7123db5e2db), [`d1098f7`](https://github.com/equinor/fusion-framework/commit/d1098f7eeff04380c9e05e4a7a7d6b16e1d95884)]:
+  - @equinor/fusion-framework-vite-plugin-spa@1.1.4
+  - @equinor/fusion-framework-vite-plugin-api-service@1.2.2
+
 ## 1.1.3
 
 ### Patch Changes

package/README.md

@@ -1,108 +1,488 @@
 # Fusion Framework Dev Server
 
-This package provides a development server for Fusion Framework applications.
+A powerful development server for Fusion Framework applications, built on Vite with integrated service discovery, API proxying, and portal support.
 
-## 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.
+## Features
 
-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.
+- 🚀 **Fast Development**: Powered by Vite for lightning-fast HMR and builds
+- 🔗 **Service Discovery**: Automatic API service discovery and proxying
+- 🏠 **Portal Support**: Built-in portal development with manifest loading
+- 🔧 **API Mocking**: Easy mocking and overriding of API responses
+- 📊 **Telemetry**: Integrated logging and debugging capabilities
+- ⚙️ **Flexible Configuration**: Extensive customization options
 
-> [!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.
+## Quick Start
 
-### Basic Configuration
+Here's the minimal setup to get a Fusion Framework dev server running:
 
-The dev server requires a basic configuration object to be passed to it.
+```typescript
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
 
-```ts
 const devServer = await createDevServer({
   spa: {
     templateEnv: {
       portal: {
         id: '@equinor/fusion-framework-dev-portal',
-      }
-      title: 'My Test Dev Server',
+      },
+      title: 'My Fusion App',
       serviceDiscovery: {
-        url: 'https://location.of.your.service.discovery',
-        scopes: ['scope_required'],
+        url: 'https://service-discovery.example.com',
+        scopes: ['api://example.com/user_impersonation'],
       },
       msal: {
-        clientId: 'dev-client-id',
-        tenantId: 'dev-tenant-id',
+        clientId: 'your-client-id',
+        tenantId: 'your-tenant-id',
         redirectUri: '/authentication/login-callback',
         requiresAuth: 'true',
       },
     },
   },
+  api: {
+    serviceDiscoveryUrl: 'https://service-discovery.example.com',
+  },
 });
+
+await devServer.listen();
+devServer.printUrls();
 ```
 
-### Adding Service Discovery
+## Configuration
 
-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.
+The dev server accepts a configuration object with the following structure:
 
-```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,
-        };
+### SPA Configuration
+
+Configure the Single Page Application environment and template generation:
+
+```typescript
+{
+  spa: {
+    templateEnv: {
+      // Portal configuration
+      portal: {
+        id: 'your-portal-id', // Portal identifier
+      },
+
+      // Application title
+      title: 'My Application',
+
+      // Service discovery settings
+      serviceDiscovery: {
+        url: 'https://service-discovery.example.com',
+        scopes: ['scope1', 'scope2'],
+      },
+
+      // Authentication configuration
+      msal: {
+        clientId: 'your-client-id',
+        tenantId: 'your-tenant-id',
+        redirectUri: '/authentication/login-callback',
+        requiresAuth: 'true', // or 'false'
+      },
+
+      // Optional telemetry configuration (browser console logging)
+      telemetry: {
+        consoleLevel: 1, // 0=Debug, 1=Information, 2=Warning, 3=Error, 4=Critical
+      },
+
+      // Optional service worker configuration
+      serviceWorker: {
+        resources: [
+          {
+            url: '/api',
+            rewrite: '/api-v1',
+            scopes: ['api://example.com/user_impersonation'],
+          },
+        ],
       },
     },
-    routes: [ /** add proxy and middleware routes */]
-  }
-);
+  },
+}
 ```
 
+### API Configuration
 
-## Proxying API Requests
+Configure API proxying and service discovery:
 
-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.
+```typescript
+{
+  api: {
+    // Required: Service discovery endpoint
+    serviceDiscoveryUrl: 'https://service-discovery.example.com',
 
-see [Vite server Proxy](https://vite.dev/config/server-options#server-proxy) for more details for setting up the proxy.
+    // Optional: Custom service processing
+    processServices: (services, route) => {
+      // Process and return services with routes
+      return processServices(services, route);
+    },
 
-```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'],
+    // Optional: Additional API routes
+    routes: [
+      {
+        match: '/api/custom/*',
+        middleware: (req, res) => {
+          // Custom middleware logic
+          res.end(JSON.stringify({ custom: 'response' }));
         },
-      ],
-    }
-  }, 
-  {
-    proxy: {
-      '/api': {
-        target: 'https://api.example.com',
-        changeOrigin: true,
-        pathRewrite: { '^/api': '' },
+      },
+    ],
+  },
+}
+```
+
+### Logging Configuration
+
+Configure CLI/server-side logging levels and custom loggers:
+
+```typescript
+{
+  log: {
+    // Optional: CLI log level (0=None, 1=Error, 2=Warning, 3=Info, 4=Debug)
+    level: 3, // Default is Info level
+
+    // Optional: Custom logger instance
+    logger: new ConsoleLogger('my-dev-server'),
+  },
+}
+```
+
+> [!NOTE]
+> **Telemetry vs CLI Logging**: The `telemetry.consoleLevel` controls logging output in the browser console (visible to end users), while `log.level` controls server-side logging in the terminal/command line (visible to developers). These use different logging systems with different level mappings.
+
+### Main Functions
+
+#### `createDevServer(options, overrides?)`
+
+Creates and configures a development server instance.
+
+**Parameters:**
+- `options` (`DevServerOptions`): Configuration object for the dev server
+- `overrides` (`UserConfig`): Optional Vite configuration overrides
+
+**Returns:** `Promise<ViteDevServer>` - Configured Vite development server
+
+**Example:**
+```typescript
+const devServer = await createDevServer(config);
+await devServer.listen();
+```
+
+#### `createDevServerConfig(options, overrides?)`
+
+Creates a Vite configuration object for the dev server.
+
+**Parameters:**
+- `options` (`DevServerOptions`): Configuration object for the dev server
+- `overrides` (`UserConfig`): Optional Vite configuration overrides
+
+**Returns:** `UserConfig` - Vite configuration object
+
+### Utility Functions
+
+#### `processServices(data, args)`
+
+Processes service discovery data and generates proxy routes.
+
+**Parameters:**
+- `data` (`FusionService[]`): Array of services from service discovery
+- `args.route` (`string`): Base route for proxying
+- `args.request` (`IncomingMessage`): HTTP request object
+
+**Returns:** Object with processed services and routes
+
+### Types
+
+#### `DevServerOptions<TEnv>`
+
+Configuration options for the development server.
+
+```typescript
+type DevServerOptions<TEnv extends Partial<FusionTemplateEnv>> = {
+  spa?: {
+    templateEnv: TEnv | TemplateEnvFn<TEnv>;
+  };
+  api: {
+    serviceDiscoveryUrl: string;
+    processServices?: ApiDataProcessor<FusionService[]>;
+    routes?: ApiRoute[];
+  };
+  log?: {
+    level?: number;
+    logger?: ConsoleLogger;
+  };
+};
+```
+
+#### `FusionService`
+
+Represents a service in the Fusion ecosystem.
+
+```typescript
+type FusionService = {
+  key: string;    // Service identifier
+  uri: string;    // Service endpoint URL
+  name: string;   // Human-readable service name
+};
+```
+
+## Examples
+
+### Basic Portal Development
+
+```typescript
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
+
+const devServer = await createDevServer({
+  spa: {
+    templateEnv: {
+      portal: { id: 'my-portal' },
+      title: 'My Portal',
+      serviceDiscovery: {
+        url: 'https://service-discovery.example.com',
+        scopes: ['api://example.com/user_impersonation'],
+      },
+      msal: {
+        clientId: process.env.CLIENT_ID!,
+        tenantId: process.env.TENANT_ID!,
+        redirectUri: '/authentication/login-callback',
+        requiresAuth: 'true',
       },
     },
+  },
+  api: {
+    serviceDiscoveryUrl: 'https://service-discovery.example.com',
+  },
+});
+
+await devServer.listen();
+```
+
+### Adding Mock Services
+
+```typescript
+import { createDevServer, processServices } from '@equinor/fusion-framework-dev-server';
+
+const devServer = await createDevServer({
+  spa: { /* ... spa config ... */ },
+  api: {
+    serviceDiscoveryUrl: 'https://service-discovery.example.com',
+    processServices: (data, route) => {
+      const { data: services, routes } = processServices(data, route);
+
+      // Add mock services
+      return {
+        data: services.concat({
+          key: 'mock-api',
+          name: 'Mock API Service',
+          uri: '/mock-api',
+        }),
+        routes: routes.concat({
+          match: '/mock-api/*',
+          middleware: (req, res) => {
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({ mock: 'data' }));
+          },
+        }),
+      };
+    },
+  },
+});
+```
+
+### Custom Vite Configuration
+
+```typescript
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
+import { defineConfig } from 'vite';
+
+const devServer = await createDevServer(
+  { /* ... dev server config ... */ },
+  defineConfig({
+    server: {
+      port: 3001,
+      host: '0.0.0.0',
+    },
+    define: {
+      __DEV__: true,
+    },
+  })
+);
+```
+
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Cannot find module '@equinor/fusion-framework-dev-server'"
+
+**Solution:** Make sure the package is installed and you're using the correct import path.
+
+```bash
+pnpm add -D @equinor/fusion-framework-dev-server
+```
+
+#### Service Discovery Connection Failed
+
+**Problem:** The dev server can't connect to the service discovery endpoint.
+
+**Solutions:**
+1. Check that `serviceDiscoveryUrl` is correct and accessible
+2. Verify network connectivity to the service discovery endpoint
+3. Check for authentication requirements
+
+#### Portal Manifest Not Loading
+
+**Problem:** Portal configuration isn't loading properly.
+
+**Solutions:**
+1. Verify the portal ID is correct in the `spa.templateEnv.portal.id` field
+2. Check that the portal service is available and responding
+3. Ensure proper authentication is configured
+
+#### API Routes Not Working
+
+**Problem:** Custom API routes or service proxying isn't functioning.
+
+**Solutions:**
+1. Check the `routes` configuration in the `api` section
+2. Verify route patterns match the expected request paths
+3. Ensure middleware functions are properly implemented
+4. Check for conflicts with existing routes
+
+#### Authentication Issues
+
+**Problem:** MSAL authentication isn't working.
+
+**Solutions:**
+1. Verify `clientId` and `tenantId` are correct
+2. Check that `redirectUri` matches your application configuration
+3. Ensure the required scopes are properly configured
+4. Check browser console for authentication errors
+
+### Debug Logging
+
+Enable debug logging to troubleshoot issues:
+
+#### CLI/Server-Side Debug Logging
+```typescript
+const devServer = await createDevServer({
+  // ... config
+  log: {
+    level: 4, // Debug level (0=None, 1=Error, 2=Warning, 3=Info, 4=Debug)
+  },
+});
+```
+
+#### Browser Console Telemetry Logging
+```typescript
+{
+  spa: {
+    templateEnv: {
+      // ... other config
+      telemetry: {
+        consoleLevel: 0, // Debug level (0=Debug, 1=Information, 2=Warning, 3=Error, 4=Critical)
+      },
+    },
+  },
+}
+```
+
+## Advanced Usage
+
+### Custom Service Processing
+
+For advanced service discovery manipulation:
+
+```typescript
+import { createDevServer, processServices } from '@equinor/fusion-framework-dev-server';
+
+const devServer = await createDevServer({
+  api: {
+    serviceDiscoveryUrl: 'https://service-discovery.example.com',
+    processServices: (services, route) => {
+      const { data, routes } = processServices(services, route);
+
+      // Filter out development-only services in production
+      const filteredData = data.filter(service =>
+        process.env.NODE_ENV !== 'production' || !service.key.includes('dev')
+      );
+
+      // Add custom routes for specific services
+      const customRoutes = routes.map(route => ({
+        ...route,
+        // Add custom headers or modify proxy behavior
+      }));
+
+      return { data: filteredData, routes: customRoutes };
+    },
+  },
+});
+```
+
+### Integration with Build Tools
+
+The dev server works seamlessly with the Fusion Framework CLI:
+
+```bash
+# Use with CLI for automatic configuration
+npx @equinor/fusion-framework-cli app dev
+
+# Or portal development
+npx @equinor/fusion-framework-cli portal dev
+```
+
+### Custom Plugins
+
+Extend the dev server with custom Vite plugins:
+
+```typescript
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
+import myCustomPlugin from 'my-custom-vite-plugin';
+
+const devServer = await createDevServer(
+  { /* ... config ... */ },
+  {
+    plugins: [myCustomPlugin()],
   }
 );
 ```
+
+## Migration Guide
+
+### From Direct Vite Usage
+
+If you're migrating from a direct Vite setup:
+
+1. Replace your Vite configuration with the dev server configuration
+2. Move service discovery logic to the `api.processServices` function
+3. Configure portal settings in `spa.templateEnv`
+4. Update your start script to use `createDevServer`
+
+**Before:**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [react(), /* other plugins */],
+  server: {
+    proxy: { /* proxy config */ },
+  },
+});
+```
+
+**After:**
+```typescript
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
+
+const devServer = await createDevServer({
+  // Move your config here
+});
+```
+
+## Contributing
+
+This package is part of the Fusion Framework monorepo. See the main [contributing guide](../../CONTRIBUTING.md) for details.
+
+## License
+
+ISC

package/dist/esm/create-dev-server-config.js

@@ -14,7 +14,7 @@ const createDefaultLogger = (lvl = LogLevel.Info, title = 'dev-server') => {
  *
  * @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.spa - Optional 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.

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Generated by genversion.
-export const version = '1.1.3';
+export const version = '1.1.5';
 //# sourceMappingURL=version.js.map