> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with Flows custom apps

> Create a new Flows custom app, install dependencies, open it in Cursor, and run it inside Cognite Data Fusion (CDF).

**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).
* **Git** — used by the Cognite CLI (`@cognite/cli`) to initialize and manage your app repository.
* A coding IDE such as Cursor or VS Code.
* A compatible coding agent. See [Supported AI development environments](/cdf/flows/concepts/skills#supported-ai-development-environments) for the full list.
* Access to a **CDF** project (organization, project name, and cluster).
* **App hosting capabilities** assigned by your administrator in CDF groups. See [Assign capabilities](/cdf/access/guides/capabilities#flows-custom-apps).
* **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](/cdf/admin/allowlist).
* A [trusted local HTTPS certificate](/cdf/flows/guides/local-https) as CDF won't load your app unless the browser trusts the dev server's certificate. Options exist  with or without admin rights.

<Note>
  **Certification for customer environments**: If you plan to develop and deploy Flows custom apps to customer environments, complete [Builder certification](/cdf/flows/guides/builder-certification) and submit each app for [application certification](/cdf/flows/guides/application-certification) before deploying to production.
</Note>

## Set up your environment

### Install Node.js

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

<CodeGroup>
  ```bash nvm (recommended) wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  # 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
  ```

  ```bash macOS (Homebrew) theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  brew install node@20
  ```

  ```bash Windows theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  # Download the installer from https://nodejs.org/
  ```
</CodeGroup>

#### Verify installation

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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:

<Tabs>
  <Tab title="Node.js upgrade">
    Use nvm or Homebrew.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    nvm install 20
    nvm use 20
    # OR if using Homebrew:
    brew install node@20
    ```
  </Tab>

  <Tab title="npm upgrade">
    Run the following command from your home directory `~` or outside your project folder to avoid local configuration conflicts.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npm install -g npm@11.10.0
    ```
  </Tab>
</Tabs>

### 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](/cdf/flows/concepts/skills#supported-ai-development-environments).

| Environment              | Install                                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| **Cursor** (recommended) | [cursor.com](https://cursor.com/)                                                              |
| **Claude Code**          | `npm install -g @anthropic-ai/claude-code`                                                     |
| **GitHub Copilot**       | [VS Code extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)        |
| **Windsurf**             | [codeium.com/windsurf](https://codeium.com/windsurf)                                           |
| **Any other agent**      | See [supported environments](/cdf/flows/concepts/skills#supported-ai-development-environments) |

<Tip>
  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.
</Tip>

### GitHub (optional)

For version control, create an account at [github.com](https://github.com/) and configure Git:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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

<Steps>
  <Step title="Create your app">
    Run:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest apps create
    ```

    Or create the app in a specific directory:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest apps create [directory]
    ```

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

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest apps create .
    ```
  </Step>

  <Step title="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](/cdf/flows/concepts/spec-driven-development). | `yes` or `no`.                              |

    <Tip title="Skip prompts with flags">
      Pass flags to skip individual prompts. This is useful in scripts or when you want to avoid interactive mode:

      ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
      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.
    </Tip>
  </Step>

  <Step title="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](/cdf/flows/guides/application-certification) requires this file.

    <Note>
      Skip this step for dev or test projects as application certification is not required there.
    </Note>
  </Step>

  <Step title="Open the project in your editor">
    Open the generated folder in your preferred editor or coding agent environment.

    <Tabs>
      <Tab title="Cursor (recommended)">
        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        cursor my-analytics-app
        ```
      </Tab>

      <Tab title="Claude Code">
        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        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.
      </Tab>

      <Tab title="VS Code">
        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        code my-analytics-app
        ```
      </Tab>
    </Tabs>

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Install and run">
    Install dependencies and start the development server:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npm install
    npm start
    ```

    <Info>
      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](/cdf/flows/guides/local-https) for the one-time `mkcert` setup, or the no-admin manual fallback.
    </Info>

    Your app opens in CDF when the dev server is ready.
  </Step>

  <Step title="Optional: Initialize Git">
    Use Cursor to initialize a Git repository and make your first commit.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    git init
    git add .
    git commit -m "Initial commit"
    ```

    You can also use the Source Control panel in Cursor.
  </Step>

  <Step title="Build your app">
    Start building your application. See the following resources and tips for help:

    * [Run your app locally](/cdf/flows/guides/running-locally) — See the UI and behavior while you develop.
    * [Flows features](/cdf/flows/concepts/features) — For a concise overview of everything the template gives you.
    * [Deploy your Flows app](/cdf/flows/guides/deploying) — See interactive and CI/CD options.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Deploy">
    When you're ready to deploy your app to CDF, run:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest apps deploy --interactive
    ```

    See [Deploy](/cdf/flows/guides/deploying) for options and CI/CD.
  </Step>
</Steps>

## Generated structure

Here is the generated structure of your app:

<Tree>
  <Tree.Folder name="my-analytics-app" defaultOpen>
    <Tree.Folder name=".agents">
      <Tree.Folder name="skills" />
    </Tree.Folder>

    <Tree.Folder name=".claude">
      <Tree.Folder name="skills" />
    </Tree.Folder>

    <Tree.Folder name="src" defaultOpen>
      <Tree.File name="App.tsx" />

      <Tree.File name="App.test.tsx" />

      <Tree.Folder name="lib">
        <Tree.File name="utils.ts" />
      </Tree.Folder>

      <Tree.File name="main.tsx" />

      <Tree.File name="styles.css" />
    </Tree.Folder>

    <Tree.File name="app.json" />

    <Tree.File name="AGENTS.md" />

    <Tree.File name="CLAUDE.md" />

    <Tree.File name="eslint.config.mjs" />

    <Tree.File name="index.html" />

    <Tree.File name="manifest.json" />

    <Tree.File name="package.json" />

    <Tree.File name="SPEC.md" />

    <Tree.File name="tsconfig.json" />

    <Tree.File name="vite.config.ts" />

    <Tree.File name="vitest.config.ts" />
  </Tree.Folder>
</Tree>

## 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](/cdf/flows/reference/api/auth)).
* **Local development** — Vite with hot module replacement and HTTPS; run commands with **npm**. See [Run your app locally](/cdf/flows/guides/running-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](/cdf/flows/guides/deploying).
* **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](/cdf/flows/reference/api/csp).

For more detail on each area (including TypeScript, examples, and build commands), see [Flows features](/cdf/flows/concepts/features).

## Further reading

* [Flows features](/cdf/flows/concepts/features) — Scaffolding, auth, Vite, tests, deploy, and data fetching at a glance.
* [Run your app locally](/cdf/flows/guides/running-locally) — Dev server, HTTPS, CDF iframe, and configuration.
* [Deploy your Flows app](/cdf/flows/guides/deploying) — Interactive and automated deployment.
* [Builder certification](/cdf/flows/guides/builder-certification) — Required to build Flows custom apps in customer environments.
* [Application certification](/cdf/flows/guides/application-certification) — Required per app before production deployment.
* [Auth API](/cdf/flows/reference/api/auth) — `connectToHostApp`, `HostAppAPI`, and helpers.
* [Content Security Policy](/cdf/flows/reference/api/csp) — Production CSP baseline and how to extend it via `manifest.json`.