fusion-developer-portal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fusion Developer Portal

Fusion开发者门户

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

本指南指导Fusion门户壳的开发——门户壳是在共享界面框架（头部、上下文选择器、导航）中加载、路由和渲染Fusion应用的宿主应用。

When to use

适用场景

User wants to scaffold a new Fusion portal
User asks about
```
portal.manifest.ts
```
or
```
ffc portal dev
```
User wants to configure portal-level framework modules (telemetry, analytics, navigation, services, app module)
User wants to build a custom app loader or portal shell
User wants to add portal-level routing (
```
/apps/:appKey/*
```
)
User asks about the
```
Apploader
```
component or
```
useApploader
```
hook for embedding apps
User wants to wire up a portal header, context selector, or bookmark side sheet
User asks how portals load and initialize Fusion apps at runtime
User wants to add portal-level analytics or telemetry
User asks about portal deployment (
```
ffc portal build
```
,
```
ffc portal upload
```
)

用户想要搭建新的Fusion门户脚手架
用户询问
```
portal.manifest.ts
```
或
```
ffc portal dev
```
相关问题
用户想要配置门户级框架模块（遥测、分析、导航、服务、应用模块）
用户想要构建自定义应用加载器或门户壳
用户想要添加门户级路由（
```
/apps/:appKey/*
```
）
用户询问
```
Apploader
```
组件或用于嵌入应用的
```
useApploader
```
钩子
用户想要配置门户头部、上下文选择器或书签侧边栏
用户询问门户如何在运行时加载和初始化Fusion应用
用户想要添加门户级分析或遥测
用户询问门户部署（
```
ffc portal build
```
、
```
ffc portal upload
```
）

When not to use

不适用场景

App-level feature development inside a Fusion app → use
```
fusion-app-react-dev
```
Backend service changes → separate repository
Fusion Help Center integration → use
```
fusion-help-integration
```
Skill authoring → use
```
fusion-skill-authoring
```
Issue authoring → use
```
fusion-issue-authoring
```

Fusion应用内的应用级功能开发 → 请使用
```
fusion-app-react-dev
```
后端服务变更 → 请使用单独的代码库
Fusion帮助中心集成 → 请使用
```
fusion-help-integration
```
技能创作 → 请使用
```
fusion-skill-authoring
```
问题创作 → 请使用
```
fusion-issue-authoring
```

Required inputs

必要输入

Mandatory

必填项

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

构建目标：搭建门户脚手架、添加门户功能、配置模块或了解门户架构
门户上下文：从零开始创建新门户，或修改现有门户

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

搭建脚手架时的门户名称/ID
配置认证时的MSAL客户端ID和服务发现URL
要启用的特定模块（分析、遥测、书签、功能标志、AG Grid）
门户是否需要自定义应用加载器，还是默认的
```
Apploader
```
即可满足需求

Instructions

操作步骤

Step 1 — Classify the portal task

步骤1 — 分类门户任务

Determine what the user needs:

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

When Fusion MCP is available, prefer

mcp_fusion_search_framework

with queries like

"portal manifest definePortalManifest ffc portal"

"createFrameworkProvider PortalModuleInitiator portal configure"

to retrieve the latest API surface. Label any guidance not confirmed by MCP as fallback.

确定用户的需求：

搭建新门户脚手架 → 进入步骤2
配置门户模块 → 进入步骤3
应用加载与路由 → 进入步骤4
门户界面框架（头部、上下文、书签） → 进入步骤5
分析与遥测 → 进入步骤6
构建与部署 → 进入步骤7

当Fusion MCP可用时，优先使用

mcp_fusion_search_framework

，并使用类似

"portal manifest definePortalManifest ffc portal"

或

"createFrameworkProvider PortalModuleInitiator portal configure"

的查询来获取最新的API接口。所有未被MCP确认的指导内容均标记为备用方案。

Step 2 — Scaffold a new portal

步骤2 — 搭建新门户脚手架

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:

typescript

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

使用Fusion Framework CLI：

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

创建所需文件：

portal.manifest.ts
— 门户元数据与配置：

typescript

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
（可选）— 配置验证 schema
src/index.tsx
— 门户入口文件（请参阅references/portal-architecture.md）

启动开发服务器：

pnpm fusion-framework-cli portal dev

or: ffc portal dev

或：ffc portal dev

undefined

undefined

Step 3 — Configure portal modules

步骤3 — 配置门户模块

Portal-level configuration uses

FrameworkConfigurator

(not

AppModuleInitiator

like apps). Enable modules in your configure callback:

typescript

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 the portal level and inherited by apps.

See references/portal-architecture.md for the full module configuration pattern and the

portal-analytics

cookbook reference.

门户级配置使用

FrameworkConfigurator

（而非应用所用的

AppModuleInitiator

）。在配置回调中启用模块：

typescript

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, { /* ... */ });
};

与应用配置的关键区别：门户配置

FrameworkConfigurator

，其模块会被提升到所有子应用中。MSAL/认证在门户级别配置，并由应用继承。

有关完整的模块配置模式和

portal-analytics

参考手册，请参阅references/portal-architecture.md。

Step 4 — App loading and routing

步骤4 — 应用加载与路由

The portal routes

/apps/:appKey/*

to an app loader. Two approaches:

Simple embed — use the built-in

Apploader

component:

tsx

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:

tsx

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

门户将

/apps/:appKey/*

路由到应用加载器。有两种实现方式：

简单嵌入 — 使用内置的

Apploader

组件：

tsx

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

<Apploader appKey="my-app" />

警告：
Apploader
是实验性的POC。嵌入的应用可能存在路由和上下文问题。最适合PowerBI或PowerApps视图等简单应用。

自定义应用加载器 — 用于完全控制加载状态、错误处理和挂载。使用

useFramework<[AppModule]>

()，监听

fusion.modules.app.current$

，并调用

app.initialize()

。有关带注释的自定义AppLoader模式，请参阅references/portal-architecture.md。

门户路由通常通过导航模块使用

react-router-dom

：

tsx

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

Step 5 — Portal chrome

步骤5 — 门户界面框架

Portal-level UI typically includes:

Header — top bar with Fusion logo, context selector, bookmarks, person settings
Context selector — wired to the current app's context module via
```
useCurrentContext
```
or
```
useContextSelector
```
Bookmark side sheet — toggle via the navigation module
App navigation — sidebar or top-level nav for switching between hosted apps

These components are portal-specific. Apps do not build their own header — they receive it from the portal shell.

门户级UI通常包括：

头部 — 包含Fusion标志、上下文选择器、书签、个人设置的顶部栏
上下文选择器 — 通过
```
useCurrentContext
```
或
```
useContextSelector
```
连接到当前应用的上下文模块
书签侧边栏 — 通过导航模块切换
应用导航 — 用于在托管应用之间切换的侧边栏或顶级导航

这些组件是门户特有的。应用无需构建自己的头部——它们从门户壳中获取头部。

Step 6 — Analytics and telemetry

步骤6 — 分析与遥测

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

typescript

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.

门户级分析捕获应用生命周期事件。通过适配器和收集器启用：

typescript

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());
});

有关遥测（OpenTelemetry / Application Insights）的信息，请参阅references/portal-architecture.md。

Step 7 — Build and deploy

步骤7 — 构建与部署

undefined

undefined

Build the portal template

构建门户模板

ffc portal build

Upload to the Fusion portal service (authenticate via

az login

or FUSION_TOKEN env var)

上传到Fusion门户服务（通过

az login

或FUSION_TOKEN环境变量进行身份验证）

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 the `FUSION_TOKEN` environment variable for CI pipelines.

ffc portal tag --portal-id <id> --tag latest --version <version>


> **请勿直接在命令中粘贴令牌。** 对于交互式认证，请使用`az login`；对于CI流水线，请设置`FUSION_TOKEN`环境变量。

Step 8 — Validate

步骤8 — 验证

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

```
ffc portal dev
```
启动无错误
应用在
```
/apps/:appKey
```
路径下正确加载
上下文选择器和头部正确渲染
TypeScript编译无错误
应用加载/选择时触发分析事件（如果已启用）

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

具备应用加载、路由和界面框架的可用门户壳
使用正确
```
FrameworkConfigurator
```
的门户级模块配置
处理应用初始化的加载和错误状态
对创建或更改内容的简要总结

Helper agents

辅助Agent

This skill uses the same companion infrastructure as

fusion-app-react-dev

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

When Fusion MCP is available, prefer

mcp_fusion_search_framework

for portal-specific lookups.

本技能与

fusion-app-react-dev

使用相同的配套基础设施：

fusion-research
— 当门户行为不确定时，用于基于源代码的Fusion生态系统研究
fusion-code-conventions
— 用于命名、TSDoc和代码风格检查

当Fusion MCP可用时，优先使用

mcp_fusion_search_framework

进行门户相关查询。

Safety & constraints

安全与约束

MSAL is portal-level — never configure auth in individual apps; it is hoisted from the portal
Do not 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
Do not modify the production Fusion portal — this skill covers custom portal development only
Conventional commits for all changes

MSAL是门户级配置 — 切勿在单个应用中配置认证；认证从门户继承
请勿发明门户API — 仅引用MCP确认或参考文档中记录的API
Apploader
是实验性的 — 建议应用嵌入时，务必提及路由/上下文限制
源代码中不得包含机密信息 — MSAL客户端ID必须来自环境变量，而非硬编码
请勿修改生产环境的Fusion门户 — 本技能仅涵盖自定义门户开发
所有变更均需遵循约定式提交规范

fusion-developer-portal

Original

Translation

Fusion Developer Portal

Fusion开发者门户

When to use

适用场景

When not to use

不适用场景

Required inputs

必要输入

Mandatory

必填项

Conditional

条件项

Instructions

操作步骤

Step 1 — Classify the portal task

步骤1 — 分类门户任务

Step 2 — Scaffold a new portal

步骤2 — 搭建新门户脚手架

or: ffc portal dev

或：ffc portal dev

Step 3 — Configure portal modules

步骤3 — 配置门户模块

Step 4 — App loading and routing

步骤4 — 应用加载与路由

Step 5 — Portal chrome

步骤5 — 门户界面框架

Step 6 — Analytics and telemetry

步骤6 — 分析与遥测

Step 7 — Build and deploy

步骤7 — 构建与部署

Build the portal template

构建门户模板

Upload to the Fusion portal service (authenticate via az login or FUSION_TOKEN env var)

上传到Fusion门户服务（通过az login或FUSION_TOKEN环境变量进行身份验证）

Tag a specific version

为特定版本打标签

Step 8 — Validate

步骤8 — 验证

Expected output

预期输出

Helper agents

辅助Agent

Safety & constraints

安全与约束

Upload to the Fusion portal service (authenticate via
`az login`
or FUSION_TOKEN env var)

上传到Fusion门户服务（通过
`az login`
或FUSION_TOKEN环境变量进行身份验证）