setup-dune-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set Up Dune Authentication

配置Dune认证

Migrate an existing React app to Dune by installing auth dependencies, wrapping the app in

DuneAuthProvider

, and configuring the Vite plugin.

通过安装认证依赖、用

DuneAuthProvider

包裹应用并配置Vite插件，将现有React应用迁移至Dune。

Your job

你的任务

Complete these steps in order. Read each file before modifying it.

按顺序完成以下步骤。修改文件前请先阅读每个文件。

Step 1 — Understand the app

步骤1 — 了解应用

Read these files to understand the current setup:

```
package.json
```
— detect package manager (
```
packageManager
```
field or lock file) and existing deps
```
src/main.tsx
```
(or
```
src/index.tsx
```
,
```
src/main.ts
```
) — find the app entry point and root render
```
vite.config.ts
```
(or
```
vite.config.js
```
) — check for existing Vite configuration
```
src/App.tsx
```
(or equivalent) — understand the app structure

Check what's already in place:

Is
```
@cognite/dune
```
already in
```
package.json
```
?
Is
```
DuneAuthProvider
```
already wrapping the app?
Is
```
fusionOpenPlugin
```
already in the Vite config?
Is
```
@tanstack/react-query
```
already installed?

Only fix what's missing — do not duplicate existing setup.

阅读以下文件以了解当前配置：

```
package.json
```
— 检测包管理器（
```
packageManager
```
字段或锁文件）及现有依赖
```
src/main.tsx
```
（或
```
src/index.tsx
```
、
```
src/main.ts
```
） — 找到应用入口点和根渲染逻辑
```
vite.config.ts
```
（或
```
vite.config.js
```
） — 检查现有Vite配置
```
src/App.tsx
```
（或等效文件） — 了解应用结构

检查已有的配置：

```
package.json
```
中是否已存在
```
@cognite/dune
```
？
应用是否已被
```
DuneAuthProvider
```
包裹？
Vite配置中是否已存在
```
fusionOpenPlugin
```
？
是否已安装
```
@tanstack/react-query
```
？

仅修复缺失的部分 — 不要重复已有的配置。

Step 2 — Install dependencies

步骤2 — 安装依赖

Install the required packages using the app's package manager. Only install packages that are not already in

package.json

Required dependencies:

Package	Purpose
`@cognite/dune`	Auth provider, useDune hook, Vite plugin
`@cognite/sdk`	CogniteClient for CDF API access
`@tanstack/react-query`	Required peer dependency for Dune

Required dev dependencies:

Package	Purpose
`vite-plugin-mkcert`	HTTPS in local dev (required for Fusion iframe auth)

Install commands by package manager:

pnpm →

pnpm add @cognite/dune @cognite/sdk @tanstack/react-query && pnpm add -D vite-plugin-mkcert

npm →

npm install @cognite/dune @cognite/sdk @tanstack/react-query && npm install -D vite-plugin-mkcert

yarn →

yarn add @cognite/dune @cognite/sdk @tanstack/react-query && yarn add -D vite-plugin-mkcert

Skip any package that's already installed.

使用应用的包管理器安装所需包。仅安装未在

package.json

中存在的包。

必需依赖：

包名	用途
`@cognite/dune`	认证提供者、useDune钩子、Vite插件
`@cognite/sdk`	用于CDF API访问的CogniteClient
`@tanstack/react-query`	Dune所需的对等依赖

必需开发依赖：

包名	用途
`vite-plugin-mkcert`	本地开发中的HTTPS支持（Fusion iframe认证必需）

按包管理器分类的安装命令：

pnpm →

pnpm add @cognite/dune @cognite/sdk @tanstack/react-query && pnpm add -D vite-plugin-mkcert

npm →

npm install @cognite/dune @cognite/sdk @tanstack/react-query && npm install -D vite-plugin-mkcert

yarn →

yarn add @cognite/dune @cognite/sdk @tanstack/react-query && yarn add -D vite-plugin-mkcert

跳过任何已安装的包。

Step 3 — Configure Vite

步骤3 — 配置Vite

Edit

vite.config.ts

to add the

fusionOpenPlugin

and

mkcert

plugins if they are not already present.

编辑

vite.config.ts

，添加

fusionOpenPlugin

和

mkcert

插件（如果尚未存在）。

Required imports

必需导入

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

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

Required plugin entries

必需插件配置

Add

mkcert()

and

fusionOpenPlugin()

to the

plugins

array:

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

Key details:

```
base: "./"
```
is required for Fusion iframe deployment
```
mkcert()
```
enables HTTPS locally, which is required for Fusion iframe communication
```
fusionOpenPlugin()
```
opens the app inside Fusion during
```
pnpm dev
```
for auth to work
```
server.port: 3001
```
is the conventional Dune dev port (optional but recommended)
```
worker.format: "es"
```
is needed if web workers are used (optional but recommended)

Only add what's missing. Do not remove existing plugins.

将

mkcert()

和

fusionOpenPlugin()

添加到

plugins

数组：

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

关键细节：

```
base: "./"
```
是Fusion iframe部署的必需配置
```
mkcert()
```
启用本地HTTPS支持，这是Fusion iframe通信的必需条件
```
fusionOpenPlugin()
```
会在
```
pnpm dev
```
时将应用在Fusion中打开，确保认证正常工作
```
server.port: 3001
```
是Dune开发的常规端口（可选但推荐）
```
worker.format: "es"
```
在使用Web Worker时是必需的（可选但推荐）

仅添加缺失的内容，不要移除现有插件。

Step 4 — Wrap the app in DuneAuthProvider

步骤4 — 用DuneAuthProvider包裹应用

Edit the entry file (

src/main.tsx

or equivalent) to wrap the app with

DuneAuthProvider

and

QueryClientProvider

编辑入口文件（

src/main.tsx

或等效文件），用

DuneAuthProvider

和

QueryClientProvider

包裹应用。

Target structure

目标结构

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

Important rules:

```
DuneAuthProvider
```
must be inside
```
QueryClientProvider
```
```
DuneAuthProvider
```
must be outside (wrapping) the
```
<App />
```
component
Keep any existing providers the app already has — nest
```
DuneAuthProvider
```
around the app content but inside
```
QueryClientProvider
```
If
```
QueryClientProvider
```
already exists, just add
```
DuneAuthProvider
```
inside it
If
```
DuneAuthProvider
```
already wraps the app, do nothing

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

重要规则：

```
DuneAuthProvider
```
必须在
```
QueryClientProvider
```
内部
```
DuneAuthProvider
```
必须在
```
<App />
```
组件外部（包裹组件）
保留应用已有的所有提供者 — 将
```
DuneAuthProvider
```
嵌套在
```
QueryClientProvider
```
内部，包裹应用内容
如果
```
QueryClientProvider
```
已存在，只需在其内部添加
```
DuneAuthProvider
```
如果应用已被
```
DuneAuthProvider
```
包裹，则无需操作

Step 5 — Wire up useDune in components

步骤5 — 在组件中接入useDune

Search the app for any existing CogniteClient instantiation or auth setup (e.g. manual

new CogniteClient(...)

, custom auth contexts, or OIDC flows) and replace them with the

useDune

hook.

搜索应用中所有现有的CogniteClient实例化或认证配置（例如手动

new CogniteClient(...)

、自定义认证上下文或OIDC流程），并将其替换为

useDune

钩子。

The hook API

钩子API

tsx

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

function MyComponent() {
  const { sdk, isLoading, error } = useDune();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  // sdk is an authenticated CogniteClient — use it directly
  // e.g. sdk.timeseries.list(), sdk.assets.list(), etc.
}

Return values:

Field	Type	Description
`sdk`	`CogniteClient`	Authenticated Cognite SDK instance
`isLoading`	`boolean`	`true` during initial auth handshake
`error`	`string \| undefined`	Error message if auth fails

If the app has no existing CDF auth code to replace, skip this step.

tsx

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

function MyComponent() {
  const { sdk, isLoading, error } = useDune();

  if (isLoading) return <div>加载中...</div>;
  if (error) return <div>错误: {error}</div>;

  // sdk是已认证的CogniteClient — 可直接使用
  // 例如 sdk.timeseries.list(), sdk.assets.list(), 等等
}

返回值说明：

字段	类型	描述
`sdk`	`CogniteClient`	已认证的Cognite SDK实例
`isLoading`	`boolean`	初始认证握手期间为 `true`
`error`	`string \| undefined`	认证失败时的错误信息

如果应用没有需要替换的现有CDF认证代码，则跳过此步骤。

Step 6 — Clean up old auth code

步骤6 — 清理旧认证代码

If the app previously used a custom auth setup, remove it:

Delete custom auth context providers or hooks that are now replaced by
```
DuneAuthProvider
```
/
```
useDune
```
Remove manual
```
CogniteClient
```
instantiation from entry files
Remove OIDC/token management code that
```
DuneAuthProvider
```
now handles
Remove any environment variables for CDF credentials (e.g.
```
VITE_CDF_PROJECT
```
,
```
VITE_CDF_CLUSTER
```
) — Dune handles this via Fusion iframe messaging

Only remove code that is clearly superseded. If unsure, leave it and flag it to the user.

如果应用之前使用自定义认证配置，请移除相关代码：

删除已被
```
DuneAuthProvider
```
/
```
useDune
```
替代的自定义认证上下文提供者或钩子
移除入口文件中手动的
```
CogniteClient
```
实例化代码
移除现在由
```
DuneAuthProvider
```
处理的OIDC/令牌管理代码
移除CDF凭证相关的环境变量（例如
```
VITE_CDF_PROJECT
```
、
```
VITE_CDF_CLUSTER
```
）— Dune通过Fusion iframe消息传递处理这些内容

仅移除明显被替代的代码。若不确定，请保留代码并向用户标注。

Done

完成

The app should now:

Have

@cognite/dune

@cognite/sdk

, and

@tanstack/react-query

installed

Have
```
DuneAuthProvider
```
wrapping the app in the entry file
Have
```
fusionOpenPlugin()
```
and
```
mkcert()
```
in the Vite config
Use
```
useDune()
```
to access the authenticated
```
CogniteClient
```

Run

pnpm dev

(or the app's dev command) — it should open in Fusion and authenticate automatically.

应用现在应具备以下特性：

已安装

@cognite/dune

、

@cognite/sdk

和

@tanstack/react-query

入口文件中已用
```
DuneAuthProvider
```
包裹应用
Vite配置中已添加
```
fusionOpenPlugin()
```
和
```
mkcert()
```
使用
```
useDune()
```
访问已认证的
```
CogniteClient
```

运行

pnpm dev

（或应用的开发命令）— 应用应在Fusion中打开并自动完成认证。