@cognite/dune

Build and deploy React apps to Cognite Data Fusion.

Quick start

Scaffold a new app — AI skills are pulled automatically:

npx @cognite/dune apps create

This prompts for your app name, org, project, and cluster, then generates a fully configured React + TypeScript project.

Top-level commands (dune create, dune deploy, dune deploy:interactive, dune skills) still work as deprecated aliases that print a one-line warning. Migrate to dune apps <verb>.

Authentication

New apps created with npx @cognite/dune apps create depend on @cognite/app-sdk — not @cognite/dune — for auth and host integration. @cognite/dune is the CLI used to scaffold, develop, and deploy the app; the generated app itself talks to the Fusion app host via @cognite/app-sdk's Comlink handshake. The template wires this up for you.

Legacy apps (--classic)

Apps created with --classic use the older Files API path and wrap their root in DuneAuthProvider from @cognite/dune/auth:

import { DuneAuthProvider, useDune } from '@cognite/dune/auth';

function App() {
  const { sdk, isLoading } = useDune();
  if (isLoading) return <div>Loading...</div>;
  return <MyApp sdk={sdk} />;
}

export default function Root() {
  return (
    <DuneAuthProvider>
      <App />
    </DuneAuthProvider>
  );
}

Deployment

Deploy interactively via browser OAuth:

npx @cognite/dune apps deploy --interactive

For CI, set your client secret as an environment variable and run:

pnpm deploy

Deployment targets are configured in app.json at the project root.

AI skills

Skills guide your AI agent (Claude Code, Cursor, etc.) through Dune-specific tasks like adding auth, building chat UIs, or reviewing code. They are pulled automatically on npx @cognite/dune apps create and can be synced later:

npx @cognite/dune apps skills pull

Browse available skills at cognitedata/builder-skills.

Requirements

• Node.js ≥ 20
• React ≥ 18 (optional peer dependency — only needed for auth components)

Development

Running tests

pnpm test           # run once
pnpm test:watch     # watch mode

Testing the CLI against a mock server

A local mock of the App Hosting API lets you run the real CLI against a controlled server without hitting a real CDF cluster.

Terminal 1 — start the mock server:

pnpm mock:server

Terminal 2 — run the deploy command against it:

pnpm mock:deploy

mock:deploy builds and deploys apps/mock-app — a minimal workspace app that serves as the standard CLI test target. Under the hood it sets two env vars that work from any app directory too:

| Env var | Purpose | |---|---| | COGNITE_BASE_URL=http://localhost:9090 | Overrides baseUrl from app.json — all API calls go to the mock | | COGNITE_TOKEN=test-token | Skips OAuth entirely — no real client secret needed |

To test against your own app instead of the fixture:

cd apps/my-app
COGNITE_TOKEN=test-token COGNITE_BASE_URL=http://localhost:9090 pnpm exec dune deploy --skip-build

Simulating error scenarios

Pass MOCK_SCENARIO to the server to force a specific HTTP error:

MOCK_SCENARIO=403 pnpm mock:server

| MOCK_SCENARIO | Step that fails | |---|---| | 409 | ensureApp — app already exists (CLI should recover) | | 403 | ensureApp — missing AppHosting:WRITE capability | | 500 | ensureApp — internal server error | | upload-409 | uploadVersion — version already published, cannot overwrite (hard failure) | | upload-413 | uploadVersion — payload too large (50 MB limit) | | upload-403 | uploadVersion — missing AppHosting:WRITE capability | | upload-500 | uploadVersion — internal server error | | publish-403 | publishAndActivate — missing AppHosting:WRITE capability | | publish-500 | publishAndActivate — internal server error | | republish | ensureApp recovers (409), then uploadVersion fails (409 — version already published) |

The mock server and MSW handlers live in cli/testing/msw/. The same handlers are used by the Vitest integration tests in src/deploy/apphosting-deployer.msw.test.ts.

Maintenance

Updating the spec-kit vendor snapshot

The AI skill commands under _vendor/spec-kit/ are generated by spec-kit and checked in. To update to a new release, pass the target tag (requires uv, which provides uvx):

pnpm --filter @cognite/dune refresh-spec-kit v0.9.0

The refresh script stages the generated commands, templates, and shell scripts before replacing _vendor/spec-kit/. Then review the diff under _vendor/spec-kit/ and commit it.