setup-flows-auth

设置 Flows 身份验证

为 React 应用接入 Flows 身份验证，使其能够在 Fusion 中与 CDF 通信。共有两种流程，请根据 app.json 选择。

选择流程

如果存在 app.json，请读取：

app.json infra	流程	身份验证来源	额外的软件包
"appsApi"	Apps API（新版 Fusion 应用宿主）	来自 @cognite/app-sdk 的 connectToHostApp	@cognite/app-sdk
缺失／其他	Classic（旧版 Files API）	来自 @cognite/dune 的 DuneAuthProvider + useDune()	—

如果没有 app.json，请询问用户。默认选择 Apps API——这是 npx @cognite/cli@latest apps create 的默认流程。

第 1 步 — 读取状态并决定是否操作

读取 package.json、src/main.tsx（或 src/index.tsx）、vite.config.ts、app.json。

如果满足以下任一条件，则表示已存在有效配置——此时不要执行任何操作，并报告未进行更改：

• Classic：入口文件中的 <DuneAuthProvider>（来自 @cognite/dune）包裹了 <App />。
• Apps API，Provider 模式：<CogniteSdkProvider>（来自 @cognite/app-sdk/react）包裹了应用（位于 App.tsx 或 main.tsx 中），且嵌套组件通过 useCogniteSdk() 使用客户端。需要 @cognite/app-sdk >= 0.5.1。

根据锁文件检测包管理器（pnpm-lock.yaml → pnpm，yarn.lock → yarn，否则使用 npm）。

第 2 步 — 安装缺少的依赖项

Classic 流程：

软件包	类型
@cognite/dune	运行时
@cognite/sdk	运行时
@tanstack/react-query	运行时
vite-plugin-mkcert	开发

Apps API 流程：

软件包	类型
@cognite/app-sdk	运行时
@cognite/sdk	运行时
@tanstack/react-query	运行时
vite-plugin-mkcert	开发

跳过 package.json 中已有的依赖项。使用检测到的包管理器（pnpm add、npm install、yarn add；开发依赖使用 -D / --save-dev）。

第 3 步 — Vite 配置

只添加缺少的配置。不要移除现有插件。

Classic 流程

import { fusionOpenPlugin } from "@cognite/dune/vite";
import mkcert from "vite-plugin-mkcert";

export default defineConfig({
  base: "./",
  plugins: [react(), mkcert(), fusionOpenPlugin(), /* ... */],
  server: { port: 3001 },
  worker: { format: "es" },
});

Apps API 流程

// or see @cognite/cli/_templates/app/new/config/vite.config.ts.ejs.t source file for newest config
import { fusionOpenPlugin, manifestCspPlugin } from "@cognite/app-sdk/vite";
import mkcert from "vite-plugin-mkcert";

export default defineConfig({
  base: "./",
  // manifestCspPlugin() must be first — its middleware sets the CSP header before any HTML response
  plugins: [manifestCspPlugin(), react(), mkcert(), fusionOpenPlugin(), /* ... */],
  server: { port: 3001 },
  worker: { format: "es" },
});

• base: "./" — Fusion iframe 部署所必需。
• mkcert() — 为开发服务器提供 HTTPS（Fusion 父级使用 HTTPS）。
• fusionOpenPlugin() — 自动在 Fusion 中打开开发 URL。
• manifestCspPlugin()（仅限 Apps API）— 强制执行 manifest.json 中声明的 CSP；必须放在第一位。
• server.port: 3001 — 约定端口；如果未设置端口，插件会回退到 3001。

第 4 步 — 接入入口文件和组件

Classic 流程

src/main.tsx：

import { DuneAuthProvider } from "@cognite/dune";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";

const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: 5 * 60 * 1000, gcTime: 10 * 60 * 1000 } },
});

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <DuneAuthProvider>
        <App />
      </DuneAuthProvider>
    </QueryClientProvider>
  </React.StrictMode>
);

在组件中使用 useDune()：

import { useDune } from "@cognite/dune";

const { sdk, isLoading, error } = useDune();
// sdk is an authenticated CogniteClient

Apps API 流程（生成器默认配置，@cognite/app-sdk >= 0.5.1）

src/main.tsx 不会使用任何身份验证 Provider 包裹应用——身份验证在 App.tsx 内部处理：

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";

const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: 5 * 60 * 1000, gcTime: 10 * 60 * 1000 } },
});

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </React.StrictMode>
);

src/App.tsx 使用来自 @cognite/app-sdk/react 的 CogniteSdkProvider。Provider 会在内部处理 Comlink 握手、加载和错误状态。嵌套组件通过 useCogniteSdk() 读取客户端：

import { CogniteSdkProvider, useCogniteSdk } from "@cognite/app-sdk/react";

function AppContent() {
  const client = useCogniteSdk();
  // client is an authenticated CogniteClient
  return <div>{client.project}</div>;
}

function App() {
  return (
    <CogniteSdkProvider
      loadingFallback={<div>Loading...</div>}
      errorFallback={<div>Failed to connect to Fusion</div>}
    >
      <AppContent />
    </CogniteSdkProvider>
  );
}

如果在 CogniteSdkProvider 外部调用，useCogniteSdk() 会抛出错误——请务必将其置于该 Provider 内部。

第 5 步 — 清理不再需要的代码

只移除现在已多余的内容：

• 自定义 CDF 身份验证 Provider／钩子
• 手动实例化 CogniteClient
• OIDC／令牌管理代码
• CDF 环境变量（VITE_CDF_PROJECT、VITE_CDF_CLUSTER 等）——这些由 Flows／宿主提供

如果不确定，请保留代码并告知用户。