fusion-developer-portal

name	fusion-developer-portal
description	Guides development of Fusion portal shells — scaffolding, module configuration, app loading, routing, header/context integration, analytics, and deployment using the Fusion Framework CLI portal commands. USE FOR: create portal, scaffold portal, configure portal modules, portal app loading, portal routing, portal header, context selector, portal analytics, portal telemetry, portal manifest, ffc portal dev, portal deployment, embed apps in portal. DO NOT USE FOR: app-level feature development (use fusion-app-react-dev), backend service changes, Fusion Help Center integration, skill authoring.
license	MIT
compatibility	Requires @equinor/fusion-framework-cli for portal scaffolding and dev server. Requires @equinor/fusion-framework and @equinor/fusion-framework-react for portal runtime.
metadata	{"version":"0.0.2","status":"active","owner":"@equinor/fusion-core","skills":["fusion-research","fusion-code-conventions"],"tags":["fusion-portal","portal-development","app-loader","portal-shell","micro-frontend","fusion-framework-cli","portal-manifest","context-selector","portal-routing"],"mcp":{"suggested":["fusion"]}}

Fusion Developer Portal

Guide development of Fusion portal shells — host applications that load, route, and render Fusion apps inside shared chrome (header, context selector, navigation).

When to use

• Scaffold new Fusion portal
• portal.manifest.ts or ffc portal dev questions
• Configure portal-level modules (telemetry, analytics, navigation, services, app module)
• Build custom app loader or portal shell
• Add portal-level routing (/apps/:appKey/*)
• Apploader component or useApploader hook for embedding apps
• Wire up portal header, context selector, or bookmark side sheet
• Understand how portals load/initialize Fusion apps at runtime
• Add portal-level analytics or telemetry
• Portal deployment (ffc portal build, ffc portal upload)

When not to use

• App-level feature development → fusion-app-react-dev
• Backend service changes → separate repo
• Fusion Help Center integration → fusion-help-integration
• Skill authoring → fusion-skill-authoring
• Issue authoring → fusion-issue-authoring

Required inputs

Mandatory

• What to build: scaffold a portal, add a feature, configure a module, or understand portal architecture
• Portal context: new from scratch or modifying existing

Conditional

• Portal name/ID when scaffolding
• MSAL client ID and service discovery URL when configuring auth
• Specific modules to enable (analytics, telemetry, bookmarks, feature flags, AG Grid)
• Whether the portal needs a custom app loader or the default Apploader suffices

Instructions

Step 1 — Classify the portal task

Determine what the user needs:

• Scaffold new portal → step 2
• Configure portal modules → step 3
• App loading and routing → step 4
• Portal chrome (header, context, bookmarks) → step 5
• Analytics and telemetry → step 6
• Build and deploy → step 7

When Fusion MCP is available, prefer mcp_fusion_search_framework with queries like "portal manifest definePortalManifest ffc portal" or "createFrameworkProvider PortalModuleInitiator portal configure" for latest API surface. Label guidance not confirmed by MCP as fallback.

Step 2 — Scaffold a new portal

Use the Fusion Framework CLI:

mkdir my-fusion-portal && cd my-fusion-portal
pnpm init
pnpm add -D @equinor/fusion-framework-cli

Create the required files:

• portal.manifest.ts — portal metadata and configuration:

import { definePortalManifest } from '@equinor/fusion-framework-cli/portal';

export default definePortalManifest((env, { base }) => ({
  name: 'my-portal',
  version: '1.0.0',
  entry: './src/index.tsx',
}));

• portal.schema.ts (optional) — configuration validation schema
• src/index.tsx — portal entry point (see references/portal-architecture.md)

Start the dev server:

pnpm fusion-framework-cli portal dev
# or: ffc portal dev

Step 3 — Configure portal modules

Portal-level configuration uses FrameworkConfigurator (not AppModuleInitiator like apps). Enable modules in your configure callback:

import type { FrameworkConfigurator } from '@equinor/fusion-framework';
import { enableAppModule } from '@equinor/fusion-framework-module-app';
import { enableNavigation } from '@equinor/fusion-framework-module-navigation';
import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';

const configure = (configurator: FrameworkConfigurator) => {
  enableAppModule(configurator);
  enableNavigation(configurator, '/');
  enableAnalytics(configurator, { /* ... */ });
};

Key difference from app configuration: the portal configures FrameworkConfigurator and its modules are hoisted to all child apps. MSAL/auth is configured at portal level and inherited by apps.

See references/portal-architecture.md for full module configuration and portal-analytics cookbook reference.

Step 4 — App loading and routing

The portal routes /apps/:appKey/* to an app loader. Two approaches:

Simple embed — use the built-in Apploader component:

import { Apploader } from '@equinor/fusion-framework-react-app/apploader';

<Apploader appKey="my-app" />

Warning: Apploader is an experimental POC. Embedded apps may have routing and context issues. Best for simple apps like PowerBI or PowerApps views.

Custom app loader — for full control over loading states, error handling, and mounting. Use useFramework<[AppModule]>(), observe fusion.modules.app.current$, and call app.initialize(). See references/portal-architecture.md for the annotated custom AppLoader pattern.

Portal routing typically uses react-router-dom via the navigation module:

const Router = () => {
  const framework = useFramework();
  const router = framework.modules.navigation.router;
  return <RouterProvider router={router} />;
};

Step 5 — Portal chrome

Portal-level UI typically includes:

• Header — top bar with Fusion logo, context selector, bookmarks, person settings
• Context selector — wired to app context module via useCurrentContext or useContextSelector
• Bookmark side sheet — toggled via navigation module
• App navigation — sidebar or top-level nav for switching apps

Apps don't build their own header — they receive it from the portal shell.

Step 6 — Analytics and telemetry

Portal-level analytics capture app lifecycle events. Enable with adapters and collectors:

import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
import { AppLoadedCollector, AppSelectedCollector } from '@equinor/fusion-framework-module-analytics/collectors';

enableAnalytics(configurator, (builder) => {
  builder.addAdapter(new ConsoleAnalyticsAdapter());
  builder.addCollector(new AppLoadedCollector());
  builder.addCollector(new AppSelectedCollector());
});

For telemetry (OpenTelemetry / Application Insights), see references/portal-architecture.md.

Step 7 — Build and deploy

# Build the portal template
ffc portal build

# Upload to the Fusion portal service (authenticate via `az login` or FUSION_TOKEN env var)
ffc portal upload --portal-id <id>

# Tag a specific version
ffc portal tag --portal-id <id> --tag latest --version <version>

Never paste tokens directly into commands. Use az login for interactive auth or set FUSION_TOKEN env var for CI pipelines.

Step 8 — Validate

1. ffc portal dev starts without errors
2. Apps load at /apps/:appKey
3. Context selector and header render properly
4. TypeScript compiles with no errors
5. Analytics events fire on app load/select (if enabled)

Expected output

• Working portal shell with app loading, routing, and chrome
• Portal-level module configuration with correct FrameworkConfigurator usage
• Loading and error states handled for app initialization
• Brief summary of what was created or changed

Helper agents

Same companion infrastructure as fusion-app-react-dev:

• fusion-research — source-backed Fusion ecosystem research when portal behavior is uncertain
• fusion-code-conventions — naming, TSDoc, and code style checks

When Fusion MCP is available, prefer mcp_fusion_search_framework for portal-specific lookups.

Safety & constraints

• MSAL is portal-level — never configure auth in apps; it is hoisted from the portal
• Don't invent portal APIs — only reference APIs confirmed by MCP or documented in references
• Apploader is experimental — always mention routing/context limitations when advising on app embedding
• No secrets in source — MSAL client IDs must come from environment variables, not hardcoded
• Don't modify the production Fusion portal — this skill covers custom portal development only
• Conventional commits for all changes