Back to Details

migrate-app-to-flows

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate App to Flows Infrastructure

将应用迁移至Flows基础设施

Orchestrates the full migration of a legacy Dune app to the new Flows app hosting (
appsApi
). Works through each area in order, skipping any already in the correct state.
统筹将旧版Dune应用迁移至新的Flows应用托管（
appsApi
）的完整流程。按顺序处理各个环节，跳过已处于正确状态的部分。

Step 1 — Audit current state

步骤1 — 审核当前状态

Read 
app.json
, 
package.json
, 
vite.config.ts
, and 
manifest.json
(if present).
Report a concise summary before making any changes:
Migration audit:
✗ app.json: missing infra field → will add "infra": "appsApi"
✗ Auth: DuneAuthProvider in use → will run setup-flows-auth
✗ manifest.json: missing → will create
✓ Deploy script: already uses @cognite/cli
Then proceed through Steps 2–5.
读取
app.json
、
package.json
、
vite.config.ts
以及
manifest.json
（如果存在）。
在进行任何更改前生成简洁的审核报告：
Migration audit:
✗ app.json: missing infra field → will add "infra": "appsApi"
✗ Auth: DuneAuthProvider in use → will run setup-flows-auth
✗ manifest.json: missing → will create
✓ Deploy script: already uses @cognite/cli
然后继续执行步骤2至步骤5。

Step 2 — Update 
app.json

步骤2 — 更新
app.json

If 
infra
is already 
"appsApi"
, skip this step. Otherwise, add or update the field:
json
{
  "name": "My App",
  "externalId": "my-app",
  "versionTag": "0.0.1",
  "infra": "appsApi",
  "deployments": [...]
}
如果
infra
字段已设置为
"appsApi"
，则跳过此步骤。否则，添加或更新该字段：
json
{
  "name": "My App",
  "externalId": "my-app",
  "versionTag": "0.0.1",
  "infra": "appsApi",
  "deployments": [...]
}

Step 3 — Set up Flows auth

步骤3 — 配置Flows认证

Run the 
setup-flows-auth
skill now. It handles everything auth-related: package installation, Vite plugin updates, entry file changes, and wiring up 
connectToHostApp
.
立即运行
setup-flows-auth
工具。它会处理所有与认证相关的事宜：包安装、Vite插件更新、入口文件修改，以及配置
connectToHostApp
。

Step 4 — Create or update 
manifest.json

步骤4 — 创建或更新
manifest.json

The Flows host uses 
manifest.json
to enforce a Content Security Policy for the app. It must exist at the repo root.
Create if missing:
json
{
  "manifestVersion": 1,
  "permissions": {
    "network": []
  }
}
Populate network permissions by scanning for outbound calls to external domains:
bash
grep -rn "fetch\|axios\|new XMLHttpRequest" src/ --include="*.ts" --include="*.tsx"
For each group of external URLs found, add an entry to the 
network
array using the 
sources
/
directives
shape:
json
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://api.example.com", "https://maps.googleapis.com"],
        "directives": ["connect-src"]
      }
    ]
  }
}
Rules:
  • Use full origin (scheme + hostname) in 
    sources
    , not just the hostname.
  • "connect-src"
    covers 
    fetch
    /
    XMLHttpRequest
    . Use 
    "img-src"
    for image URLs, 
    "font-src"
    for fonts.
  • The CDF cluster URL is allowed automatically; do not list it.
  • If no external calls exist, leave 
    "network": []
    .
  • Flag any dynamic URLs the user needs to verify manually.
Flows宿主环境使用
manifest.json
为应用强制执行内容安全策略。该文件必须存在于仓库根目录。
若文件缺失则创建：
json
{
  "manifestVersion": 1,
  "permissions": {
    "network": []
  }
}
通过扫描外部域名的出站调用填充网络权限：
bash
grep -rn "fetch\|axios\|new XMLHttpRequest" src/ --include="*.ts" --include="*.tsx"
对于找到的每一组外部URL，使用
sources
/
directives
格式将条目添加至
network
数组：
json
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://api.example.com", "https://maps.googleapis.com"],
        "directives": ["connect-src"]
      }
    ]
  }
}
规则：
  • 在
    sources
    中使用完整源（协议+主机名），而非仅主机名。
  • "connect-src"
    覆盖
    fetch
    /
    XMLHttpRequest
    。图片URL使用
    "img-src"
    ，字体URL使用
    "font-src"
    。
  • CDF集群URL会自动被允许；无需列出。
  • 若不存在外部调用，保留
    "network": []
    。
  • 标记任何需要用户手动验证的动态URL。

Step 5 — Update deploy scripts

步骤5 — 更新部署脚本

Replace any 
dune deploy
or 
npx @cognite/dune
commands in 
package.json
:
json
{
  "scripts": {
    "deploy": "npx @cognite/cli@latest apps deploy --interactive --published",
    "deploy-preview": "npx @cognite/cli@latest apps deploy --interactive"
  }
}
Keep all other scripts (
start
, 
build
, 
test
, etc.) unchanged.
替换
package.json
中所有
dune deploy
或
npx @cognite/dune
命令：
json
{
  "scripts": {
    "deploy": "npx @cognite/cli@latest apps deploy --interactive --published",
    "deploy-preview": "npx @cognite/cli@latest apps deploy --interactive"
  }
}
保留所有其他脚本（
start
、
build
、
test
等）不变。

Step 6 — Final check

步骤6 — 最终检查

bash
grep -rn "DuneAuthProvider\|useDune\|@cognite/dune" src/ vite.config.ts 2>/dev/null
List any remaining hits for the user to resolve. Then report:
Migration complete:
✓ app.json: infra set to "appsApi"
✓ Auth: setup-flows-auth applied
✓ manifest.json: network permissions set
✓ Deploy scripts: updated to @cognite/cli
bash
grep -rn "DuneAuthProvider\|useDune\|@cognite/dune" src/ vite.config.ts 2>/dev/null
列出所有剩余匹配项供用户解决。然后生成报告：
Migration complete:
✓ app.json: infra set to "appsApi"
✓ Auth: setup-flows-auth applied
✓ manifest.json: network permissions set
✓ Deploy scripts: updated to @cognite/cli