setup-flows-auth

Flows 認証のセットアップ

React アプリを Flows 認証に対応させ、Fusion 内の CDF と通信できるようにします。フローは 2 種類あります。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 のデフォルトです。

Step 1 — 状態を確認し、対応するか判断する

package.json、src/main.tsx（または src/index.tsx）、vite.config.ts、app.json を読み込みます。

次のいずれかに該当する場合、セットアップはすでに有効です。その場合は何もせず、対応不要と報告してください。

• Classic：エントリーファイルで、@cognite/dune の <DuneAuthProvider> が <App /> をラップしている。
• Apps API、プロバイダーパターン：@cognite/app-sdk/react の <CogniteSdkProvider> がアプリをラップしており（App.tsx または main.tsx）、ネストされたコンポーネントが useCogniteSdk() でクライアントを使用している。@cognite/app-sdk >= 0.5.1 が必要です。

ロックファイルからパッケージマネージャーを検出します（pnpm-lock.yaml → pnpm、yarn.lock → yarn、それ以外は npm）。

Step 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 を指定します）。

Step 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 を使用します。

Step 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 では認証プロバイダーでラップしません。認証は 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 を使用します。プロバイダーは 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>
  );
}

useCogniteSdk() は CogniteSdkProvider の外部で呼び出すと例外をスローします。必ず内部にネストしてください。

Step 5 — 不要になったコードを整理する

現在不要になったものだけを削除します。

• カスタム CDF 認証プロバイダー／フック
• CogniteClient の手動インスタンス化
• OIDC／トークン管理コード
• CDF 環境変数（VITE_CDF_PROJECT、VITE_CDF_CLUSTER など）— Flows／ホストがこれらを提供します

判断に迷う場合はそのまま残し、ユーザーに伝えてください。