md-files/.claude/skills/setup-flows-auth/SKILL.md

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
setup-flows-auth	MUST be used when migrating an existing React app to Flows, or when no Flows auth is wired up. Detects classic vs Apps API flow from `app.json` `infra` field, installs the right packages, and wires up the entry file. No-op when a valid auth setup is already in place. Triggers: migrate to Flows, add Flows auth, DuneAuthProvider, AppSdkAuthProvider, connectToHostApp, useDune, Flows setup, setup auth, missing auth provider, CDF authentication, Fusion iframe auth.	Read, Glob, Grep, Edit, Write, Bash	argument-hint

Set Up Flows Authentication

Wire a React app for Flows auth so it can talk to CDF inside Fusion. Two flows exist; pick one based on app.json.

Pick the flow

Read app.json if present:

app.json infra	Flow	Auth source	Extra package
"appsApi"	Apps API (new Fusion app host)	connectToHostApp from @cognite/app-sdk	@cognite/app-sdk
missing / other	Classic (legacy Files API)	DuneAuthProvider + useDune() from @cognite/dune	—

No app.json? Ask the user. Default to Apps API — it's the default for npx @cognite/cli@latest apps create.

Step 1 — Read state, decide whether to act

Read package.json, src/main.tsx (or src/index.tsx), vite.config.ts, app.json.

A valid setup already exists if any of these is true — in which case do nothing and report no-op:

• Classic: <DuneAuthProvider> from @cognite/dune wraps <App /> in the entry file.
• Apps API, provider pattern: <CogniteSdkProvider> from @cognite/app-sdk/react wraps the app (in App.tsx or main.tsx), and nested components consume the client via useCogniteSdk(). Requires @cognite/app-sdk >= 0.5.1.

Detect the package manager from the lock file (pnpm-lock.yaml → pnpm, yarn.lock → yarn, otherwise npm).

Step 2 — Install missing deps

Classic flow:

Package	Type
@cognite/dune	runtime
@cognite/sdk	runtime
@tanstack/react-query	runtime
vite-plugin-mkcert	dev

Apps API flow:

Package	Type
@cognite/app-sdk	runtime
@cognite/sdk	runtime
@tanstack/react-query	runtime
vite-plugin-mkcert	dev

Skip anything already in package.json. Use the detected package manager (pnpm add, npm install, yarn add; -D / --save-dev for dev deps).

Step 3 — Vite config

Add only what's missing. Don't remove existing plugins.

Classic flow

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 flow

// 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: "./" — required for Fusion iframe deployment.
• mkcert() — provides HTTPS for the dev server (the Fusion parent is HTTPS).
• fusionOpenPlugin() — opens the dev URL inside Fusion automatically.
• manifestCspPlugin() (Apps API only) — enforces the CSP declared in manifest.json; must be first.
• server.port: 3001 — convention; the plugin falls back to 3001 if no port is set.

Step 4 — Wire up the entry file and component

Classic flow

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

In components, use useDune():

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

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

Apps API flow (generator default, @cognite/app-sdk >= 0.5.1)

src/main.tsx does not wrap in any auth provider — auth is handled inside 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 uses CogniteSdkProvider from @cognite/app-sdk/react. The provider handles the Comlink handshake, loading, and error states internally. Nested components read the client via 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() throws if called outside CogniteSdkProvider — always nest it inside.

Step 5 — Clean up superseded code

Remove only what's now redundant:

• Custom CDF auth providers/hooks
• Manual CogniteClient instantiation
• OIDC/token-management code
• CDF env vars (VITE_CDF_PROJECT, VITE_CDF_CLUSTER, etc.) — Flows/the host provide these

If unsure, leave it and flag to the user.