Getting started with Flows custom apps

Flows (@cognite/cli) scaffolds React applications for CDF so you can focus on product features instead of wiring authentication and build tooling. The generated stack uses TypeScript, Vite, the Cognite SDK through React hooks, and paths to deploy to CDF.

Prerequisites

Before you begin, ensure you have the following:

Node.js 20.19 or later (npm 11.10.0 or later required).
Cursor (recommended) or another editor for TypeScript and React.
Access to a CDF project (organization, project name, and cluster).
App hosting capabilities assigned by your administrator in CDF groups. See Assign capabilities.
Access to cogniteappsdata.com in your network allowlist. If your organization uses a firewall or proxy that restricts domains, ensure this domain is allowlisted. For other URLs CDF may require, see Allowlist URLs.
A trusted local HTTPS certificate as CDF won’t load your app unless the browser trusts the dev server’s certificate. Options exist with or without admin rights.

Certification for customer environments: If you plan to develop and deploy Flows custom apps to customer environments, complete Builder certification and submit each app for application certification before deploying to production.

Set up your environment

Install Node.js

It’s recommended to use nvm (Node Version Manager) to install and manage Node.js versions.

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Load nvm (or restart your terminal):
. "$HOME/.nvm/nvm.sh"

# Install Node.js:
nvm install 20.19.5

Verify installation

node --version  # Should be v20.19.0 or higher
npm --version   # Should be v11.10.0 or higher

If you need to upgrade your Node.js or npm versions:

Node.js upgrade
npm upgrade

Use nvm or Homebrew.

nvm install 20
nvm use 20
# OR if using Homebrew:
brew install node@20

Run the following command from your home directory ~ or outside your project folder to avoid local configuration conflicts.

npm install -g npm@11.10.0

Choose your AI development environment

Flows apps work with any modern AI coding agent. Install your preferred environment before creating your app. For the full list of supported environments, see Supported AI development environments.

Environment	Install
Cursor (recommended)	cursor.com
Claude Code	`npm install -g @anthropic-ai/claude-code`
GitHub Copilot	VS Code extension
Windsurf	codeium.com/windsurf
Any other agent	See supported environments

All environments listed above detect skills without manual setup. Open the generated project folder as the workspace root and your agent will find the skill files automatically.

GitHub (optional)

For version control, create an account at github.com and configure Git:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Cognite Data Fusion (CDF) access

You need:

Your organization name (for example, your-org-name).
Your project name (for example, your-project-name).
Your cluster (for example, your-cluster-name).

Contact your Cognite administrator if you need access.

Create and run your app

Create your app

Run:

npx @cognite/cli@latest apps create

Or create the app in a specific directory:

npx @cognite/cli@latest apps create [directory]

Or create in the current directory by using a special . syntax:

npx @cognite/cli@latest apps create .

Fill out the parameters

You are prompted for information such as app name (pre-filled if you provided a directory), display name, description, org, project, cluster, base URL, and whether to enable spec-driven development.

Prompt	Description	Example
App name	Kebab-case identifier.	`my-analytics-app`
Display name	Human-readable name.	`My Analytics App`
Description	Brief description.	`Analytics dashboard`
Org	Your Cognite organization.	`your-org-name`
Project	Your CDF project.	`your-project-name`
Cluster	Cluster subdomain.	`your-cluster-name`
Base URL	CDF cluster base URL, pre-filled from your cluster but can be changed. For private-link setups, replace with your internal URL.	`https://your-cluster-name.cognitedata.com`
Enable spec-driven development	Adds a `SPEC.md` file and spec-kit slash commands to your app for structured feature planning. See Spec-driven development.	`yes` or `no`.

Pass flags to skip individual prompts. This is useful in scripts or when you want to avoid interactive mode:

npx @cognite/cli@latest apps create my-app \
  --display-name "My App" \
  --description "Analytics dashboard" \
  --org your-org-name \
  --project your-project-name \
  --cluster your-cluster-name \
  --base-url https://your-cluster-name.cognitedata.com \
  --no-spec-kit

Any flag you omit will still be prompted interactively.

Optional. Capture the application brief

If you plan to deploy this app to a customer production environment, run /flows-app-brief before you start building.The skill coaches you through persona, problem, and success criteria, then writes App-Brief.md in the repository root. Application certification requires this file.

Skip this step for dev or test projects as application certification is not required there.

Open the project in your editor

Open the generated folder in your preferred editor or coding agent environment.

Cursor (recommended)
Claude Code
VS Code

cursor my-analytics-app

claude my-analytics-app

You can run Claude Code in the terminal only, or through VS Code or any IDE with the Claude plugin installed.

code my-analytics-app

Ensure the app folder is the workspace root. Your coding agent (Cursor, Claude Code, Copilot, etc.) detects rules, MCP configuration, and skills from the project root. Opening a parent directory or subfolder causes the agent to miss the skill files.

Install and run

Install dependencies and start the development server:

npm install
npm start

The dev server serves your app over HTTPS using a self-signed certificate. On the first run, the browser will show a warning and CDF will display Failed to connect to Fusion host until you trust the certificate. See Trust the local HTTPS certificate for the one-time mkcert setup, or the no-admin manual fallback.

Your app opens in CDF when the dev server is ready.

Optional: Initialize Git

Use Cursor to initialize a Git repository and make your first commit.

git init
git add .
git commit -m "Initial commit"

You can also use the Source Control panel in Cursor.

Build your app

Start building your application. See the following resources and tips for help:

Run your app locally — See the UI and behavior while you develop.
Flows features — For a concise overview of everything the template gives you.
Deploy your Flows app — See interactive and CI/CD options.

When you start building:

Aura — Ensure @cognite/aura is listed under dependencies in package.json (for example "@cognite/aura": "0.1.1"). If it is missing, ask your coding agent to add that dependency and install it.
SPEC.md — Keep product intent in the app root so you and the AI share the same requirements as you iterate.
SDK and data — Call CDF through connectToHostApp() from @cognite/app-sdk; TanStack Query is already set up for loading and error handling around SDK calls.

Deploy

When you’re ready to deploy your app to CDF, run:

npx @cognite/cli@latest apps deploy --interactive

See Deploy for options and CI/CD.

Generated structure

Here is the generated structure of your app:

my-analytics-app

.agents

.claude

src

App.tsx

App.test.tsx

lib

main.tsx

styles.css

app.json

AGENTS.md

CLAUDE.md

eslint.config.mjs

index.html

manifest.json

package.json

SPEC.md

tsconfig.json

vite.config.ts

vitest.config.ts

What the template includes

The tree above shows where files live. When you run npx @cognite/cli@latest apps create, the generator also wires in the following capabilities (not only folders and config files):

Project scaffolding — Application layout, app.json, configuration files, and skills for AI-assisted development.
CDF authentication — Use connectToHostApp() from @cognite/app-sdk to get an authenticated Cognite SDK inside CDF (see Auth API).
Local development — Vite with hot module replacement and HTTPS; run commands with npm. See Run your app locally.
Data fetching — TanStack Query (React Query) is included to use with connectToHostApp() for SDK calls.
Tests and quality — Vitest and React Testing Library, plus linting/formatting via your template’s scripts in package.json.
Deployment — Interactive deploy from your machine or automation in CI/CD. See Deploy your Flows app.
Manifest and CSP — manifest.json declares your app’s metadata and permissions.network for allowed origins under a strict Content Security Policy. See Content Security Policy.

For more detail on each area (including TypeScript, examples, and build commands), see Flows features.

​Prerequisites

​Set up your environment

​Install Node.js

​Verify installation

​Choose your AI development environment

​GitHub (optional)

​Cognite Data Fusion (CDF) access

​Create and run your app

​Generated structure

​What the template includes

​Further reading

Prerequisites

Set up your environment

Install Node.js

Verify installation

Choose your AI development environment

GitHub (optional)

Cognite Data Fusion (CDF) access

Create and run your app

Generated structure

What the template includes

Further reading