@equinor/fusion-framework-cli 12.1.3 → 12.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +91 -0
- package/bin/build/bin.mjs +1 -1
- package/bin/build/cli.mjs +5 -5
- package/dist/esm/lib/index.js +1 -1
- package/dist/esm/lib/index.js.map +1 -1
- package/dist/esm/version.js +1 -1
- package/dist/types/bin/app-check.d.ts +1 -1
- package/dist/types/bin/utils/create-dev-server.d.ts +5 -1
- package/dist/types/cli/commands/app/dev.d.ts +6 -0
- package/dist/types/cli/commands/portal/dev.d.ts +6 -0
- package/dist/types/lib/index.d.ts +1 -1
- package/dist/types/version.d.ts +1 -1
- package/docs/application.md +55 -3
- package/docs/dev-server-config.md +407 -0
- package/docs/dev-server.md +8 -0
- package/package.json +9 -9
package/dist/esm/lib/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
export { resolvePackage } from './utils/resolve-package.js';
|
|
2
2
|
export { resolveEntryPoint } from './utils/resolve-source-entry-point.js';
|
|
3
|
-
export { loadDevServerConfig } from './load-dev-server-config.js';
|
|
3
|
+
export { loadDevServerConfig, defineDevServerConfig, } from './load-dev-server-config.js';
|
|
4
4
|
// Legacy imports - these will be removed in the next major version
|
|
5
5
|
// @todo - remove these imports, introduced in v11
|
|
6
6
|
export { defineAppConfig, defineAppManifest } from './legacy.js';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAwB,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,OAAO,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAwB,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GAGtB,MAAM,6BAA6B,CAAC;AAErC,mEAAmE;AACnE,kDAAkD;AAClD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}
|
package/dist/esm/version.js
CHANGED
|
@@ -27,5 +27,5 @@ type AppCheckOptions = {
|
|
|
27
27
|
* @returns A promise that resolves when the check is complete.
|
|
28
28
|
* @public
|
|
29
29
|
*/
|
|
30
|
-
export declare const checkApp: (options: AppCheckOptions) => Promise<
|
|
30
|
+
export declare const checkApp: (options: AppCheckOptions) => Promise<boolean>;
|
|
31
31
|
export default checkApp;
|
|
@@ -2,6 +2,7 @@ import type { AppManifest } from '@equinor/fusion-framework-module-app';
|
|
|
2
2
|
import type { ApiAppConfig } from '@equinor/fusion-framework-module-app/schemas.js';
|
|
3
3
|
import { type RuntimeEnv } from '@equinor/fusion-framework-cli/lib';
|
|
4
4
|
import { type UserConfig, type DevServerOptions, type FusionTemplateEnv } from '@equinor/fusion-framework-dev-server';
|
|
5
|
+
import type { ConsoleLogger } from './ConsoleLogger.js';
|
|
5
6
|
/**
|
|
6
7
|
* PortalManifest describes the minimal structure required for a portal manifest.
|
|
7
8
|
* Used for dev server portal routing and config.
|
|
@@ -45,5 +46,8 @@ export type CreateDevServerOptions = {
|
|
|
45
46
|
* @returns The complete dev server options object.
|
|
46
47
|
*/
|
|
47
48
|
export declare const createDevServerConfig: (options: CreateDevServerOptions) => DevServerOptions;
|
|
48
|
-
export declare const createDevServer: (env: RuntimeEnv, options: CreateDevServerOptions,
|
|
49
|
+
export declare const createDevServer: (env: RuntimeEnv, options: CreateDevServerOptions, args?: {
|
|
50
|
+
overrides?: UserConfig;
|
|
51
|
+
log?: ConsoleLogger | null;
|
|
52
|
+
}) => Promise<import("vite").ViteDevServer>;
|
|
49
53
|
export {};
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
* - Launches the development server for your application.
|
|
8
8
|
* - Supports custom manifest/config files, runtime environment, and port selection.
|
|
9
9
|
* - Debug mode available for verbose logging.
|
|
10
|
+
* - Automatic loading of dev-server.config.ts for API mocking and customization.
|
|
10
11
|
*
|
|
11
12
|
* Usage:
|
|
12
13
|
* $ ffc app dev [options]
|
|
@@ -18,12 +19,17 @@
|
|
|
18
19
|
* --env <environment> Runtime environment for the dev server (default: local)
|
|
19
20
|
* --port <port> Port for the development server (default: 3000)
|
|
20
21
|
*
|
|
22
|
+
* Configuration:
|
|
23
|
+
* dev-server.config.ts Optional configuration file for API mocking, service discovery,
|
|
24
|
+
* and development environment customization
|
|
25
|
+
*
|
|
21
26
|
* Example:
|
|
22
27
|
* $ ffc app dev
|
|
23
28
|
* $ ffc app dev --port 4000
|
|
24
29
|
* $ ffc app dev --manifest ./app.manifest.local.ts --config ./app.config.ts
|
|
25
30
|
*
|
|
26
31
|
* @see startAppDevServer for implementation details
|
|
32
|
+
* @see dev-server-config.md for configuration options
|
|
27
33
|
*/
|
|
28
34
|
export declare const command: import("commander").Command;
|
|
29
35
|
export default command;
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
* - Launches the development server for your portal.
|
|
8
8
|
* - Supports custom runtime environment and port selection.
|
|
9
9
|
* - Debug mode available for verbose logging.
|
|
10
|
+
* - Automatic loading of dev-server.config.ts for API mocking and customization.
|
|
10
11
|
*
|
|
11
12
|
* Usage:
|
|
12
13
|
* $ ffc portal dev [options]
|
|
@@ -16,12 +17,17 @@
|
|
|
16
17
|
* --env <environment> Runtime environment for the dev server (default: local)
|
|
17
18
|
* --port <port> Port for the development server (default: 3000)
|
|
18
19
|
*
|
|
20
|
+
* Configuration:
|
|
21
|
+
* dev-server.config.ts Optional configuration file for API mocking, service discovery,
|
|
22
|
+
* and development environment customization
|
|
23
|
+
*
|
|
19
24
|
* Example:
|
|
20
25
|
* $ ffc portal dev
|
|
21
26
|
* $ ffc portal dev --port 4000
|
|
22
27
|
* $ ffc portal dev --debug
|
|
23
28
|
*
|
|
24
29
|
* @see startPortalDevServer for implementation details
|
|
30
|
+
* @see dev-server-config.md for configuration options
|
|
25
31
|
*/
|
|
26
32
|
export declare const command: import("commander").Command;
|
|
27
33
|
export default command;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export type { RuntimeEnv } from './types.js';
|
|
2
2
|
export { resolvePackage, type ResolvedPackage } from './utils/resolve-package.js';
|
|
3
3
|
export { resolveEntryPoint } from './utils/resolve-source-entry-point.js';
|
|
4
|
-
export { loadDevServerConfig } from './load-dev-server-config.js';
|
|
4
|
+
export { loadDevServerConfig, defineDevServerConfig, type DevServerConfigExport, type DevServerConfigFn, } from './load-dev-server-config.js';
|
|
5
5
|
export { defineAppConfig, defineAppManifest } from './legacy.js';
|
package/dist/types/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const version = "12.
|
|
1
|
+
export declare const version = "12.3.0";
|
package/docs/application.md
CHANGED
|
@@ -107,7 +107,7 @@ pnpm fusion-framework-cli publish --env <environment>
|
|
|
107
107
|
pnpm fusion-framework-cli app config --publish --env <environment>
|
|
108
108
|
```
|
|
109
109
|
|
|
110
|
-
> **Tip:** For CI/CD and automation, set the `FUSION_TOKEN` environment variable. See [Authentication](
|
|
110
|
+
> **Tip:** For CI/CD and automation, set the `FUSION_TOKEN` environment variable. See [Authentication](auth.md) for details.
|
|
111
111
|
|
|
112
112
|
---
|
|
113
113
|
|
|
@@ -131,7 +131,7 @@ pnpm fusion-framework-cli app config --publish --env <environment>
|
|
|
131
131
|
- **Missing manifest/config:** Ensure `app.manifest.ts` and `app.config.ts` exist in your project root.
|
|
132
132
|
- **Environment variables:** Use `.env` files or your CI/CD system to inject secrets and config values.
|
|
133
133
|
- **Command help:** Run any command with `--help` for detailed usage and options.
|
|
134
|
-
- **Still stuck?** See [Troubleshooting](#troubleshooting--faq) or [Authentication](
|
|
134
|
+
- **Still stuck?** See [Troubleshooting](#troubleshooting--faq) or [Authentication](auth.md).
|
|
135
135
|
|
|
136
136
|
---
|
|
137
137
|
|
|
@@ -295,6 +295,7 @@ export default defineAppConfig((env, args) => {
|
|
|
295
295
|
|
|
296
296
|
The Fusion Framework CLI provides a suite of commands to support the full application lifecycle, from development to deployment. Below is an overview of all available commands with quick links to their detailed usage:
|
|
297
297
|
|
|
298
|
+
- [Create](#create) — Create new Fusion applications from templates.
|
|
298
299
|
- [Dev](#dev) — Start the development server with hot reloading.
|
|
299
300
|
- [Publish](#publish) — Build, upload, and tag your app for deployment.
|
|
300
301
|
- [Config](#config) — Generate or upload your app configuration.
|
|
@@ -304,10 +305,61 @@ The Fusion Framework CLI provides a suite of commands to support the full applic
|
|
|
304
305
|
- [Tag](#tag) — Tag a published app version for release management.
|
|
305
306
|
- [Manifest](#manifest) — Generate your app manifest file.
|
|
306
307
|
- [Check](#check) — Verify your app's registration status.
|
|
308
|
+
- [Disco](#disco) — Service discovery operations.
|
|
307
309
|
- [Aliases](#aliases) — Deprecated commands and their replacements.
|
|
308
310
|
|
|
309
311
|
Refer to each section below for detailed options, usage, and examples.
|
|
310
312
|
|
|
313
|
+
### Create
|
|
314
|
+
|
|
315
|
+
Create new Fusion applications from predefined templates. This command provides an interactive way to scaffold new projects with proper structure and configuration.
|
|
316
|
+
|
|
317
|
+
```sh
|
|
318
|
+
# Create a new app with interactive template selection
|
|
319
|
+
pnpm fusion-framework-cli create app my-app
|
|
320
|
+
|
|
321
|
+
# Create with a specific template
|
|
322
|
+
pnpm fusion-framework-cli create app my-app --template react-app
|
|
323
|
+
|
|
324
|
+
# Create in a specific directory
|
|
325
|
+
pnpm fusion-framework-cli create app my-app --directory ./projects
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
**Options:**
|
|
329
|
+
- `-t, --template <type>` - Template type to use (will prompt if not specified)
|
|
330
|
+
- `-d, --directory <path>` - Directory to create the app in (default: current directory)
|
|
331
|
+
|
|
332
|
+
For detailed information about creating applications, see [Creating Apps](creating-apps.md).
|
|
333
|
+
|
|
334
|
+
### Disco
|
|
335
|
+
|
|
336
|
+
Service discovery operations for resolving and inspecting Fusion services.
|
|
337
|
+
|
|
338
|
+
#### Resolve
|
|
339
|
+
|
|
340
|
+
Resolve and display information about a service registered in Fusion service discovery.
|
|
341
|
+
|
|
342
|
+
```sh
|
|
343
|
+
# Resolve a service in the current environment
|
|
344
|
+
pnpm fusion-framework-cli disco resolve my-service
|
|
345
|
+
|
|
346
|
+
# Resolve in a specific environment
|
|
347
|
+
pnpm fusion-framework-cli disco resolve my-service --env prod
|
|
348
|
+
|
|
349
|
+
# Silent mode for scripting
|
|
350
|
+
pnpm fusion-framework-cli disco resolve my-service --silent
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
**Options:**
|
|
354
|
+
- `--env <environment>` - Environment to use (prod, test, etc.)
|
|
355
|
+
- `--silent` - Silent mode, outputs only JSON for scripting
|
|
356
|
+
- Authentication options: `--token`, `--tenantId`, `--clientId`
|
|
357
|
+
|
|
358
|
+
**Useful for:**
|
|
359
|
+
- Finding service endpoints for API calls
|
|
360
|
+
- Debugging service connectivity issues
|
|
361
|
+
- Getting service metadata and configuration
|
|
362
|
+
|
|
311
363
|
### Dev
|
|
312
364
|
|
|
313
365
|
Start your application in development mode with hot reloading and environment-specific configuration.
|
|
@@ -609,7 +661,7 @@ pnpm fusion-framework-cli app check --env prod --debug
|
|
|
609
661
|
> - This change aligns with industry standards and prepares for future CLI enhancements.
|
|
610
662
|
> - Deprecated commands will be removed in future versions—update your scripts and workflows now to avoid breaking changes.
|
|
611
663
|
>
|
|
612
|
-
> For a full migration guide, see [Migration v10 to v11](
|
|
664
|
+
> For a full migration guide, see [Migration v10 to v11](migration-v10-to-v11.md).
|
|
613
665
|
|
|
614
666
|
The CLI will warn you and redirect to the new command when you use a deprecated alias, applying any necessary options automatically. See the table below for mappings:
|
|
615
667
|
|
|
@@ -0,0 +1,407 @@
|
|
|
1
|
+
The dev-server supports optional configuration through a `dev-server.config.ts` file in your project root. This allows you to customize how your application interacts with the Fusion Framework during development.
|
|
2
|
+
|
|
3
|
+
> [!NOTE]
|
|
4
|
+
> Basic server options like `port`, `host`, and `open` are configured via CLI flags or Vite configuration, not through `dev-server.config.ts`.
|
|
5
|
+
|
|
6
|
+
## Why Configure the Dev Server?
|
|
7
|
+
|
|
8
|
+
The default dev-server configuration works for most applications, but you may want to customize it when:
|
|
9
|
+
|
|
10
|
+
- **Testing API integrations**: Mock services or override API responses during development
|
|
11
|
+
- **Debugging service discovery**: Filter or modify discovered services for testing
|
|
12
|
+
- **Customizing the development environment**: Adjust template variables, CLI logging, or browser console logging
|
|
13
|
+
- **Isolating development scenarios**: Configure different behaviors for different development stages
|
|
14
|
+
|
|
15
|
+
## Getting Started
|
|
16
|
+
|
|
17
|
+
Create a `dev-server.config.ts` file in your project root. Start simple with object configuration:
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
// Simple object configuration
|
|
21
|
+
export default {
|
|
22
|
+
api: {
|
|
23
|
+
routes: [{
|
|
24
|
+
match: '/my-api/test',
|
|
25
|
+
middleware: (req, res) => res.end('OK')
|
|
26
|
+
}]
|
|
27
|
+
}
|
|
28
|
+
};
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
For conditional configuration based on environment or other runtime logic, use function configuration:
|
|
32
|
+
|
|
33
|
+
```typescript
|
|
34
|
+
import { defineDevServerConfig } from '@equinor/fusion-framework-cli';
|
|
35
|
+
|
|
36
|
+
export default defineDevServerConfig(({ base }) => {
|
|
37
|
+
// Access to base config and environment for advanced logic
|
|
38
|
+
const isLocalDev = process.env.USER === 'your-username'; // Example condition
|
|
39
|
+
|
|
40
|
+
return {
|
|
41
|
+
api: {
|
|
42
|
+
routes: [
|
|
43
|
+
// Different routes based on conditions
|
|
44
|
+
isLocalDev && { match: '/api/local-dev', middleware: localHandler }
|
|
45
|
+
].filter(Boolean) // Remove falsy values
|
|
46
|
+
}
|
|
47
|
+
};
|
|
48
|
+
});
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
> [!TIP]
|
|
52
|
+
> Start with object config. Use function config only when you need conditional logic or access to the base configuration.
|
|
53
|
+
|
|
54
|
+
## TypeScript Integration
|
|
55
|
+
|
|
56
|
+
For full TypeScript support and intellisense, import the configuration types:
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
import { defineDevServerConfig, type DevServerConfig } from '@equinor/fusion-framework-cli';
|
|
60
|
+
|
|
61
|
+
// Fully typed configuration
|
|
62
|
+
export default defineDevServerConfig(({ base }): DevServerConfig => ({
|
|
63
|
+
...base,
|
|
64
|
+
api: {
|
|
65
|
+
...base.api,
|
|
66
|
+
routes: [
|
|
67
|
+
{
|
|
68
|
+
match: '/api/users',
|
|
69
|
+
middleware: (req, res) => {
|
|
70
|
+
// req and res are properly typed
|
|
71
|
+
res.setHeader('Content-Type', 'application/json');
|
|
72
|
+
res.end(JSON.stringify([]));
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
]
|
|
76
|
+
}
|
|
77
|
+
}));
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The configuration object supports full TypeScript intellisense, including:
|
|
81
|
+
- Auto-completion for all configuration options
|
|
82
|
+
- Type checking for middleware functions
|
|
83
|
+
- Proper typing for service discovery responses
|
|
84
|
+
|
|
85
|
+
## Configuration Overview
|
|
86
|
+
|
|
87
|
+
The dev-server configuration supports these main areas:
|
|
88
|
+
|
|
89
|
+
| Area | Purpose | Common Use Cases |
|
|
90
|
+
|------|---------|------------------|
|
|
91
|
+
| `api.routes` | Mock API endpoints | Testing UI without backend, error scenarios |
|
|
92
|
+
| `api.processServices` | Modify service discovery | Add mock services, override endpoints |
|
|
93
|
+
| `api.serviceDiscoveryUrl` | Change discovery endpoint | Custom/dev environments |
|
|
94
|
+
| `spa.templateEnv` | Override Fusion config | Portal settings, MSAL config, telemetry |
|
|
95
|
+
| `log` | Control CLI logging verbosity | Debug dev-server issues, reduce terminal noise |
|
|
96
|
+
|
|
97
|
+
## How Configuration Works
|
|
98
|
+
|
|
99
|
+
The `dev-server.config.ts` file is designed for **overriding** the default dev-server behavior. You only specify what you want to change - the system automatically merges your overrides with the defaults.
|
|
100
|
+
|
|
101
|
+
### Object Configuration (Recommended)
|
|
102
|
+
Just export the properties you want to override:
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
export default {
|
|
106
|
+
// Only override what you need to change
|
|
107
|
+
api: {
|
|
108
|
+
routes: [{
|
|
109
|
+
match: '/api/users',
|
|
110
|
+
middleware: (req, res) => res.end(JSON.stringify([]))
|
|
111
|
+
}]
|
|
112
|
+
},
|
|
113
|
+
spa: {
|
|
114
|
+
templateEnv: {
|
|
115
|
+
telemetry: { consoleLevel: 0 } // Only override telemetry
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
};
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The dev-server automatically merges this with its default configuration.
|
|
122
|
+
|
|
123
|
+
### Function Configuration (Advanced)
|
|
124
|
+
Use functions when you need conditional logic or access to runtime values:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
export default defineDevServerConfig(({ base }) => {
|
|
128
|
+
// You have access to base config and runtime environment
|
|
129
|
+
return {
|
|
130
|
+
api: {
|
|
131
|
+
routes: [
|
|
132
|
+
// Your routes automatically merge with any existing ones
|
|
133
|
+
{ match: '/api/test', middleware: testHandler }
|
|
134
|
+
]
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
});
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
**Key Point**: You don't need to manually spread/merge anything. Just provide the overrides you want - the merging happens automatically.
|
|
141
|
+
|
|
142
|
+
## Array Merging Behavior
|
|
143
|
+
|
|
144
|
+
The dev-server uses intelligent array merging:
|
|
145
|
+
|
|
146
|
+
- **Routes**: Merged by `match` path - routes with identical paths are replaced (yours wins)
|
|
147
|
+
- **Other arrays**: Deduplicated using `Set` - removes exact duplicates
|
|
148
|
+
- **Services**: In service discovery, arrays are typically replaced rather than merged
|
|
149
|
+
|
|
150
|
+
Example route merging:
|
|
151
|
+
```typescript
|
|
152
|
+
// Base config has:
|
|
153
|
+
routes: [{ match: '/api/users', middleware: baseHandler }]
|
|
154
|
+
|
|
155
|
+
// Your config has:
|
|
156
|
+
routes: [{ match: '/api/users', middleware: yourHandler }]
|
|
157
|
+
|
|
158
|
+
// Result: yourHandler replaces baseHandler for /api/users
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Quick Start Examples
|
|
162
|
+
|
|
163
|
+
### I Need To...
|
|
164
|
+
| I want to... | Configuration | Example |
|
|
165
|
+
|--------------|---------------|---------|
|
|
166
|
+
| Mock an API endpoint | `api.routes` | `routes: [{ match: '/api/users', middleware: (req, res) => res.end('[]') }]` |
|
|
167
|
+
| Add a mock service | `api.processServices` | Add services to the service discovery response |
|
|
168
|
+
| Override MSAL config | `spa.templateEnv.msal` | `msal: { clientId: 'dev-client-id' }` |
|
|
169
|
+
| Change telemetry logging | `spa.templateEnv.telemetry` | `telemetry: { consoleLevel: 0 }` |
|
|
170
|
+
| Reduce CLI noise | `log.level` | `log: { level: 2 }` |
|
|
171
|
+
|
|
172
|
+
## Essential Configurations
|
|
173
|
+
|
|
174
|
+
### API Mocking
|
|
175
|
+
|
|
176
|
+
**When you need it**: Your application depends on backend services that aren't available during development, or you want to test specific API responses without hitting real services.
|
|
177
|
+
|
|
178
|
+
**How it works**: Add custom routes that intercept API calls and return mock data.
|
|
179
|
+
|
|
180
|
+
```typescript
|
|
181
|
+
export default defineDevServerConfig(() => ({
|
|
182
|
+
api: {
|
|
183
|
+
routes: [
|
|
184
|
+
{
|
|
185
|
+
match: '/api/users',
|
|
186
|
+
middleware: (req, res) => {
|
|
187
|
+
res.setHeader('Content-Type', 'application/json');
|
|
188
|
+
res.end(JSON.stringify([
|
|
189
|
+
{ id: 1, name: 'John Doe', role: 'developer' },
|
|
190
|
+
{ id: 2, name: 'Jane Smith', role: 'designer' }
|
|
191
|
+
]));
|
|
192
|
+
}
|
|
193
|
+
},
|
|
194
|
+
// Mock error responses
|
|
195
|
+
{
|
|
196
|
+
match: '/api/users/404',
|
|
197
|
+
middleware: (req, res) => {
|
|
198
|
+
res.statusCode = 404;
|
|
199
|
+
res.end(JSON.stringify({ error: 'User not found' }));
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
]
|
|
203
|
+
}
|
|
204
|
+
}));
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
**Benefits**: Develop UI components and user flows without backend dependencies. Test error handling scenarios easily.
|
|
208
|
+
|
|
209
|
+
### Service Discovery Customization
|
|
210
|
+
|
|
211
|
+
**When you need it**: You're developing against a service that doesn't exist yet in the remote service discovery, or you want to override service endpoints for local development.
|
|
212
|
+
|
|
213
|
+
**How it works**: Add mock services to the service discovery response that your application can use during development.
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
export default defineDevServerConfig(() => ({
|
|
217
|
+
api: {
|
|
218
|
+
processServices: (dataResponse) => {
|
|
219
|
+
const { data, routes } = dataResponse;
|
|
220
|
+
|
|
221
|
+
// Add mock services for development
|
|
222
|
+
const mockServices = [
|
|
223
|
+
{
|
|
224
|
+
key: 'my-new-service',
|
|
225
|
+
name: 'My New Service (Mock)',
|
|
226
|
+
uri: '/api/mock-service' // This will be proxied by the dev server
|
|
227
|
+
},
|
|
228
|
+
{
|
|
229
|
+
key: 'beta-feature-api',
|
|
230
|
+
name: 'Beta Feature API (Mock)',
|
|
231
|
+
uri: 'https://beta-api.example.com'
|
|
232
|
+
}
|
|
233
|
+
];
|
|
234
|
+
|
|
235
|
+
return {
|
|
236
|
+
data: [...data, ...mockServices],
|
|
237
|
+
routes
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
}));
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
**Benefits**: Develop against planned services before they're deployed. Test integration scenarios with mock endpoints.
|
|
245
|
+
|
|
246
|
+
### Template Environment Variables
|
|
247
|
+
|
|
248
|
+
**When you need it**: You need to override default Fusion Framework template configuration for development.
|
|
249
|
+
|
|
250
|
+
**How it works**: Modify the template environment variables that control the SPA bootstrap process.
|
|
251
|
+
|
|
252
|
+
```typescript
|
|
253
|
+
export default defineDevServerConfig(() => ({
|
|
254
|
+
spa: {
|
|
255
|
+
templateEnv: {
|
|
256
|
+
// Override document title
|
|
257
|
+
title: 'My Custom App Title',
|
|
258
|
+
|
|
259
|
+
// Override portal configuration
|
|
260
|
+
portal: {
|
|
261
|
+
id: 'my-custom-portal',
|
|
262
|
+
},
|
|
263
|
+
|
|
264
|
+
// Modify service discovery
|
|
265
|
+
serviceDiscovery: {
|
|
266
|
+
url: 'https://custom-service-discovery.example.com',
|
|
267
|
+
scopes: ['api://custom-scope/.default']
|
|
268
|
+
},
|
|
269
|
+
|
|
270
|
+
// Override MSAL configuration
|
|
271
|
+
msal: {
|
|
272
|
+
tenantId: 'custom-tenant-id',
|
|
273
|
+
clientId: 'custom-client-id',
|
|
274
|
+
redirectUri: 'https://localhost:3000/auth-callback',
|
|
275
|
+
requiresAuth: 'true'
|
|
276
|
+
},
|
|
277
|
+
|
|
278
|
+
// Configure telemetry logging level
|
|
279
|
+
telemetry: {
|
|
280
|
+
consoleLevel: 0 // Debug level (most verbose)
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
}));
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**Benefits**: Customize the Fusion Framework bootstrap behavior and control browser console logging verbosity for your specific development needs.
|
|
288
|
+
|
|
289
|
+
**Available telemetry levels:**
|
|
290
|
+
- `0`: Debug (shows all telemetry including debug messages)
|
|
291
|
+
- `1`: Information (shows info, warnings, errors, critical)
|
|
292
|
+
- `2`: Warning (shows warnings, errors, critical - default)
|
|
293
|
+
- `3`: Error (shows only errors and critical messages)
|
|
294
|
+
- `4`: Critical (shows only critical messages - least verbose)
|
|
295
|
+
|
|
296
|
+
### Portal Proxy Configuration
|
|
297
|
+
|
|
298
|
+
**When you need it**: You want to control how portal assets are loaded during development - either from the Fusion portal service or from locally installed portal packages.
|
|
299
|
+
|
|
300
|
+
**How it works**:
|
|
301
|
+
- **`proxy: true`**: Routes portal assets through the dev-server's `/portal-proxy` endpoint, which fetches content from the Fusion portal service
|
|
302
|
+
- **`proxy: false`** (default): Loads portal assets directly from `node_modules` (typically `@equinor/fusion-dev-server` or another portal package installed locally)
|
|
303
|
+
|
|
304
|
+
```typescript
|
|
305
|
+
export default defineDevServerConfig(() => ({
|
|
306
|
+
spa: {
|
|
307
|
+
templateEnv: {
|
|
308
|
+
portal: {
|
|
309
|
+
id: 'fusion',
|
|
310
|
+
tag: 'latest',
|
|
311
|
+
proxy: true // Load portal from Fusion portal service via /portal-proxy
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
}));
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
**Benefits**:
|
|
319
|
+
- **`proxy: true`**: Access production portal templates or custom portal deployments via the Fusion portal service
|
|
320
|
+
- **`proxy: false`**: Use locally installed portal packages for offline development or custom portal development
|
|
321
|
+
|
|
322
|
+
### CLI Logging
|
|
323
|
+
|
|
324
|
+
**When you need it**: You want to control the verbosity of dev-server output in your terminal/console.
|
|
325
|
+
|
|
326
|
+
**How it works**: Configure the logger level or provide a custom logger instance for CLI output.
|
|
327
|
+
|
|
328
|
+
```typescript
|
|
329
|
+
export default defineDevServerConfig(() => ({
|
|
330
|
+
log: {
|
|
331
|
+
// Info level (default) - shows info, warnings, and errors
|
|
332
|
+
level: 3,
|
|
333
|
+
}
|
|
334
|
+
}));
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
**Available levels:**
|
|
338
|
+
- `0`: Silent (no logging)
|
|
339
|
+
- `1`: Error (errors only)
|
|
340
|
+
- `2`: Warning (warnings and errors)
|
|
341
|
+
- `3`: Info (info, warnings, and errors - **default**)
|
|
342
|
+
- `4`: Debug (debug, info, warnings, and errors - most verbose)
|
|
343
|
+
|
|
344
|
+
**Quick reference:**
|
|
345
|
+
```typescript
|
|
346
|
+
// Quiet development (reduce noise)
|
|
347
|
+
log: { level: 2 }
|
|
348
|
+
|
|
349
|
+
// Default logging (recommended)
|
|
350
|
+
log: { level: 3 }
|
|
351
|
+
|
|
352
|
+
// Debug dev-server issues
|
|
353
|
+
log: { level: 4 }
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## Common Patterns
|
|
357
|
+
|
|
358
|
+
### Override MSAL for Local Development
|
|
359
|
+
|
|
360
|
+
```typescript
|
|
361
|
+
export default {
|
|
362
|
+
spa: {
|
|
363
|
+
templateEnv: {
|
|
364
|
+
msal: {
|
|
365
|
+
clientId: 'dev-client-id',
|
|
366
|
+
redirectUri: 'http://localhost:3000/auth-callback'
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
};
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
## Troubleshooting
|
|
377
|
+
|
|
378
|
+
### Configuration Not Loading
|
|
379
|
+
- Verify file name: `dev-server.config.ts` in project root
|
|
380
|
+
- Ensure default export: `export default { ... }`
|
|
381
|
+
- Check for TypeScript errors in config file
|
|
382
|
+
|
|
383
|
+
### Services Not Appearing
|
|
384
|
+
- Ensure `processServices` returns `{ data: Service[], routes: Route[] }`
|
|
385
|
+
- Verify you're not accidentally filtering out needed services
|
|
386
|
+
|
|
387
|
+
### Template Variables Not Available
|
|
388
|
+
- Variables are injected as `import.meta.env.FUSION_SPA_*`
|
|
389
|
+
- Access them as `import.meta.env.FUSION_SPA_MY_VAR`
|
|
390
|
+
|
|
391
|
+
## Advanced Usage
|
|
392
|
+
|
|
393
|
+
### Custom Service Discovery Endpoint
|
|
394
|
+
|
|
395
|
+
For custom environments with different service discovery URLs:
|
|
396
|
+
|
|
397
|
+
```typescript
|
|
398
|
+
export default {
|
|
399
|
+
api: {
|
|
400
|
+
serviceDiscoveryUrl: 'https://custom-discovery.example.com/api/service-discovery'
|
|
401
|
+
}
|
|
402
|
+
};
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
> [!WARNING]
|
|
406
|
+
> Only use when working with non-standard environments. The default Fusion service discovery endpoint is usually correct.
|
|
407
|
+
|
package/docs/dev-server.md
CHANGED
|
@@ -12,6 +12,8 @@ The Fusion Framework dev-server is your complete local development solution for
|
|
|
12
12
|
|
|
13
13
|
🛠️ **Flexible Configuration** - Easy setup for both applications and portals with environment-specific overrides
|
|
14
14
|
|
|
15
|
+
📝 **Configurable Development** - Optional `dev-server.config.ts` file for API mocking, service discovery customization, and environment variable overrides
|
|
16
|
+
|
|
15
17
|
## Quick Start
|
|
16
18
|
|
|
17
19
|
```bash
|
|
@@ -24,6 +26,12 @@ ffc portal dev
|
|
|
24
26
|
|
|
25
27
|
The dev-server automatically detects your project type, loads configuration files, and starts a development server with all Fusion Framework features ready to use. No complex setup required - just run the command and start building.
|
|
26
28
|
|
|
29
|
+
## Configuration
|
|
30
|
+
|
|
31
|
+
For detailed information about configuring the dev-server, see [Dev Server Configuration](dev-server-config.md).
|
|
32
|
+
|
|
33
|
+
The dev-server automatically loads configuration from a `dev-server.config.ts` file in your project root, allowing you to customize API mocking, service discovery, and development environment settings without modifying your application code.
|
|
34
|
+
|
|
27
35
|
## Key Features
|
|
28
36
|
|
|
29
37
|
- **Service Discovery Integration** - Automatically connects to Fusion service discovery and enables local API mocking
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@equinor/fusion-framework-cli",
|
|
3
|
-
"version": "12.
|
|
3
|
+
"version": "12.3.0",
|
|
4
4
|
"keywords": [
|
|
5
5
|
"Fusion",
|
|
6
6
|
"Fusion Framework",
|
|
@@ -103,13 +103,13 @@
|
|
|
103
103
|
"ora": "^9.0.0",
|
|
104
104
|
"read-package-up": "^11.0.0",
|
|
105
105
|
"simple-git": "^3.28.0",
|
|
106
|
-
"vite": "^7.1.
|
|
106
|
+
"vite": "^7.1.9",
|
|
107
107
|
"vite-tsconfig-paths": "^5.1.4",
|
|
108
108
|
"zod": "^4.1.8",
|
|
109
|
-
"@equinor/fusion-framework-dev-portal": "1.1
|
|
110
|
-
"@equinor/fusion-framework-dev-server": "1.1.3",
|
|
109
|
+
"@equinor/fusion-framework-dev-portal": "1.2.1",
|
|
111
110
|
"@equinor/fusion-framework-module-msal-node": "1.0.7",
|
|
112
|
-
"@equinor/fusion-imports": "1.1.4"
|
|
111
|
+
"@equinor/fusion-imports": "1.1.4",
|
|
112
|
+
"@equinor/fusion-framework-dev-server": "1.1.5"
|
|
113
113
|
},
|
|
114
114
|
"devDependencies": {
|
|
115
115
|
"@rollup/plugin-commonjs": "^28.0.3",
|
|
@@ -132,10 +132,10 @@
|
|
|
132
132
|
"type-fest": "^5.0.0",
|
|
133
133
|
"typescript": "^5.8.2",
|
|
134
134
|
"vitest": "^3.2.4",
|
|
135
|
-
"@equinor/fusion-framework-module": "
|
|
136
|
-
"@equinor/fusion-framework-module-
|
|
137
|
-
"@equinor/fusion-framework-module-
|
|
138
|
-
"@equinor/fusion-framework-module
|
|
135
|
+
"@equinor/fusion-framework-module-app": "7.0.2",
|
|
136
|
+
"@equinor/fusion-framework-module-http": "7.0.2",
|
|
137
|
+
"@equinor/fusion-framework-module-service-discovery": "9.0.2",
|
|
138
|
+
"@equinor/fusion-framework-module": "5.0.3"
|
|
139
139
|
},
|
|
140
140
|
"peerDependenciesMeta": {
|
|
141
141
|
"typescript": {
|