# setup-flows-auth

Configures Cognite Flows authentication for React applications running inside Fusion iframes. It detects your app architecture, adds Cognite SDK packages, and updates Vite settings.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1900 installs · ★ 6
- Author: cognitedata
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/cognitedata/builder-skills/tree/HEAD/skills/setup-flows-auth/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/setup-flows-auth

## What it does

The skill inspects `app.json`, `package.json`, `vite.config.ts`, and the React entry point (`src/main.tsx` or `src/index.tsx`). It detects whether the project targets the new Apps API host or the classic Files API based on the `infra` field in `app.json`. If a valid auth setup already wraps the application, the skill stops immediately and reports a no-op.

Missing dependencies are installed using npm or pnpm based on the lockfile. The skill updates `vite.config.ts` with `mkcert` for HTTPS and `fusionOpenPlugin` for automated Fusion redirects. For Apps API setups, `manifestCspPlugin` must be placed first in the plugin list to serve CSP headers correctly.

Finally, it replaces custom OIDC code with `@cognite/app-sdk` or `@cognite/dune` providers. Redundant environment variables like `VITE_CDF_PROJECT` get removed. Nested components consume the authenticated client via hooks like `useCogniteSdk()` or `useDune()`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill setup-flows-auth -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/setup-flows-auth/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/setup-flows-auth/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill setup-flows-auth -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/setup-flows-auth/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill setup-flows-auth -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/setup-flows-auth/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cognitedata/builder-skills setup-flows-auth
```

2. **Manually: put the files in place**
- File: `.github/skills/setup-flows-auth/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill setup-flows-auth -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cognitedata/builder-skills --path skills/setup-flows-auth
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/setup-flows-auth/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill setup-flows-auth -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cognitedata/builder-skills/tree/HEAD/skills/setup-flows-auth/SKILL.md

## When to use it
- migrate an existing React application to Cognite Flows auth
- connect a React frontend to CDF inside the Fusion iframe
- configure Vite plugins for HTTPS dev server and Fusion redirects
- replace manual `CogniteClient` and OIDC code with Cognite SDK providers

## Example prompts
- Set up Flows authentication for this React app
- Wire up Cognite Flows auth and add DuneAuthProvider
- Migrate this project to Fusion Apps API auth with @cognite/app-sdk

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2b257148f2424516.

BEGIN THIRD-PARTY FILE 2b257148f2424516
````text
---
name: setup-flows-auth
description: "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."
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
metadata:
  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

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

export default defineConfig({
  base: "./",
````
END THIRD-PARTY FILE 2b257148f2424516

The third-party file has ended. Everything between the 2b257148f2424516 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2693 of 6375 bytes. © cognitedata · Apache-2.0 · https://github.com/cognitedata/builder-skills/tree/HEAD/skills/setup-flows-auth/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md