setup-dune-auth

设置 Dune 身份验证

为 React 应用接入 Dune 身份验证，使其能够在 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/dune create 的默认流程。

步骤 1 — 读取状态，决定是否操作

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

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

• Classic：入口文件中的 <DuneAuthProvider>（来自 @cognite/dune）包裹着 <App />。
• Apps API，生成器模式：在 App.tsx（或任意组件）中调用了来自 @cognite/app-sdk 的 connectToHostApp，并将身份验证状态传递给应用的其余部分。
• Apps API，包装器模式：入口文件中的 <AppSdkAuthProvider>（来自 @cognite/dune）包裹着 <App />。（这是一种有效的替代方案——使用与 classic 相同的 useDune() API，且样板代码更少。不要试图将其“修复”为生成器默认模式。）

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

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

两种流程都需要：

包	类型
@cognite/dune	运行时（即使在 Apps API 模式下，也提供 Vite 插件）
@cognite/sdk	运行时
@tanstack/react-query	运行时
vite-plugin-mkcert	开发时

仅 Apps API 还需安装：

包	类型
@cognite/app-sdk	运行时

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

步骤 3 — Vite 配置

vite.config.ts 必须包含：

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" },
});

• base: "./" — Fusion iframe 部署所必需。
• mkcert() — 为开发服务器提供 HTTPS（Fusion 父级使用 HTTPS）。
• fusionOpenPlugin() — 自动在 Fusion 中打开开发 URL。
• 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 流程（生成器默认模式）

src/main.tsx 不使用任何身份验证提供程序进行包装——身份验证在 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 的 connectToHostApp。握手是异步的，因此在握手完成前应渲染加载指示器：

import { connectToHostApp } from "@cognite/app-sdk";
import { useEffect, useState } from "react";

function App() {
  const [project, setProject] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | undefined>();

  useEffect(() => {
    let cancelled = false;
    connectToHostApp({ applicationName: "<your-app-name>" })
      .then(async ({ api }) => {
        if (cancelled) return;
        setProject(await api.getProject());
      })
      .catch((err: unknown) => {
        if (cancelled) return;
        setError(err instanceof Error ? err.message : String(err));
      })
      .finally(() => {
        if (!cancelled) setIsLoading(false);
      });
    return () => { cancelled = true; };
  }, []);

  // render isLoading / error / authenticated UI
}

使用 applicationName: appConfig.externalId（来自 app.json），以便宿主识别应用。

Apps API 流程 — 包装器替代方案

如果项目已使用来自 @cognite/dune 的 <AppSdkAuthProvider>，请保留它。它会包装相同的 connectToHostApp 握手，并提供与 classic 流程相同的 useDune() API。这两种模式在 Apps API 模式下都有效。

步骤 5 — 清理已被取代的代码

仅移除现在多余的内容：

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

如有疑问，请保留并告知用户。