OAuth relay

User	Action	Capability	Description
End-user	Create and edit extraction pipelines	`extractionpipelines:write`	Gives access to create and edit individual pipelines and edit notification settings. Ensure that the pipeline has `read` access to the data set being used by the extraction pipeline.
View extraction pipelines	`extractionpipelines:read`	Gives access to list and view metadata of the pipeline.
Create and edit extraction configurations	`extractionconfigs:write`	Gives access to create and edit an extractor configuration in an extraction pipeline.
View extraction configurations	`extractionconfigs:read`	Gives access to view an extractor configuration in an extraction pipeline.
View extraction logs	`extractionruns:read`	Gives access to view run history reported by the extraction pipeline runs.
Extractor	Read extraction configurations	`extractionconfigs:read`	Gives access to read an extractor configuration from an extraction pipeline.
Post extraction logs	`extractionruns:write`	Gives access to post run history reported by the extraction pipeline runs.
Third-party actors	Create and edit extraction pipelines	`extractionpipelines:write`	Gives access to create and edit individual pipelines and edit notification settings. Ensure that the pipeline has `read` access to the data set being used by the extraction pipeline.
Create and edit extraction configurations	`extractionconfigs:write`	Gives access to create and edit the extractor configuration from an extraction pipeline.

User

Action

Capability

Description

End-user

Create and edit extraction pipelines

extractionpipelines:write

Gives access to create and edit individual pipelines and edit notification settings. Ensure that the pipeline has read access to the data set being used by the extraction pipeline.

View extraction pipelines

extractionpipelines:read

Gives access to list and view metadata of the pipeline.

Create and edit extraction configurations

extractionconfigs:write

Gives access to create and edit an extractor configuration in an extraction pipeline.

View extraction configurations

extractionconfigs:read

Gives access to view an extractor configuration in an extraction pipeline.

View extraction logs

extractionruns:read

Gives access to view run history reported by the extraction pipeline runs.

Extractor

Read extraction configurations

extractionconfigs:read

Gives access to read an extractor configuration from an extraction pipeline.

Post extraction logs

extractionruns:write

Gives access to post run history reported by the extraction pipeline runs.

Third-party actors

Create and edit extraction pipelines

extractionpipelines:write

Gives access to create and edit individual pipelines and edit notification settings. Ensure that the pipeline has read access to the data set being used by the extraction pipeline.

Create and edit extraction configurations

extractionconfigs:write

Gives access to create and edit the extractor configuration from an extraction pipeline.

`. * **Anything explicitly requested.** If a requirement, ticket, or review comment calls something out, it is not optional. For certification scoring on design and accessibility, see [Flows custom apps quality guidelines](/cdf/flows/guides/quality-guidelines). ## State: choosing the right tool Use the table below to pick the right state tool. It prevents most over- and under-engineering before you read the patterns. | State type | Tool | | - | - | | Local to one component | `useState` | | Stable global value (the CDF client, current user, feature flags) | React Context | | Frequently-updating shared state (selections, filters, wizard drafts) | Zustand | | Anything fetched from CDF | React Query — never copy into `useState` | React Context is the right default for stable globals. The Flows custom app scaffold already provides the CDF client via `CogniteSdkProvider`, so you thin-wrap its hook. Reach for Zustand when state changes frequently across many components or causes re-render storms. To reset all state in a component when an entity changes (for example, switching between contacts in an edit form), pass the entity's ID as `key`. React treats components with different keys as separate instances and resets their state automatically. No `useEffect` required. ```tsx wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // No useEffect needed to reset form state when selectedContact changes ``` ## Recommended folder shape Group code by feature, not by technical type. Instead of top-level `hooks/`, `components/`, and `services/` folders that mix unrelated concerns, each feature gets its own folder with everything it needs: data, state, schema, and UI. ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} src/ features/ alert-triage/ ui/ # presentational components specific to alert-triage context/ # context providers specific to alert-triage hooks/ # hooks specific to alert-triage useTriageVM.ts # view-model hook (owns data + commands) useAlerts.ts # query hook for this feature store.ts # Zustand: client state for alert-triage schema.ts # Zod validation schemas for alert-triage index.ts # public API of the feature context/ # Shared context providers hooks/ # Shared hooks stores/ # Shared Zustand store ui/ # Shared UI components ErrorState.tsx # one shared error surface App.tsx # shell + ErrorBoundary + QueryClientProvider ``` ## Patterns This section covers areas where Flows custom apps can drift as they grow. Where a pattern has a clear counterpart to avoid, a side-by-side example shows both. ### Use React Query for all server state A common pattern in growing Flows custom apps is fetching data with `useState` + `useEffect`. Developers often add a manual loading flag, a cancelled ref to handle race conditions, and a counter to force refetches. This hand-rolled loop is roughly what React Query does — except without caching, deduplication, background refresh, or retries. React Query ships with every Flows custom app; use it for all CDF reads and writes. See [TanStack Query in Flows](/cdf/flows/concepts/features#data-fetching-with-tanstack-query) for how the scaffold wires data fetching to CDF. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function useWellList(startDate: string, endDate: string) { return useQuery({ queryKey: ["wells", startDate, endDate], queryFn: async () => { const [wells, deferments] = await Promise.all([ fetchWells(), fetchDeferments(), ]); return joinWellData(wells, deferments); }, staleTime: 60_000, }); // caching, dedup, retries, background refetch: included } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function useWellList(startDate: string, endDate: string) { const [rows, setRows] = useState([]); const [isLoading, setIsLoading] = useState(true); const [error, setError] = useState(null); const [fetchKey, setFetchKey] = useState(0); // refetch hack useEffect(() => { let cancelled = false; setIsLoading(true); setError(null); Promise.all([fetchWells(), fetchDeferments()]) .then(([w, d]) => { if (!cancelled) setRows(joinWellData(w, d)); }) .catch((e) => { if (!cancelled) setError(e); }) .finally(() => { if (!cancelled) setIsLoading(false); }); return () => { cancelled = true; }; }, [fetchKey, startDate, endDate]); const refetch = () => setFetchKey((k) => k + 1); // no cache, no dedup, no bg refresh, no retry } ``` Query keys must be unique and specific to avoid cache collisions — a collision silently serves wrong data and is difficult to debug in production. Always include the resource type and all relevant parameters. Keys should mirror the shape of the underlying API request: a `GET /projects?userId=123&status=active` call maps to `["projects", userId, status]`. `useState` is intended for local UI state (modals, form inputs, toggles). React Query handles server state and API data — never copy query data into `useState`, which opts out of background updates and causes the UI cache to drift from the server. ### Parse at the SDK boundary with Zod CDF instance properties are loosely typed by nature. Without an explicit parse step, that looseness leaks into the rest of your Flows custom app: every component that needs a value ends up re-asserting the same assumptions with `as` casts and ad-hoc coercers. Parse the response into a known shape once, at the point where it enters your Flows custom app, and downstream code can trust the type without re-asserting it. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // schema.ts — one schema per view; z.infer is the type const WellSchema = z.object({ name: z.string().optional(), uwi: z.string().nullish(), latitudeWGS84: z.coerce.number().default(0), longitudeWGS84: z.coerce.number().default(0), }); type Well = z.infer; function mapNode(node: NodeDefinition): Well { const raw = node.properties?.[VIEW.space]?.[KEY] ?? {}; return WellSchema.parse(raw); // wrong shape → throws here, surfaced as a query error // not silently wrong data } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function getViewProps(node: NodeDefinition) { const bySpace = (node.properties as Record>) ?.[VIEW.space]; return (bySpace?.[KEY] as Record) ?? {}; } function mapNode(node: NodeDefinition): Well { const p = getViewProps(node); return { name: (p.name as string) ?? node.externalId, uwi: p.uwi as string, latitudeWGS84: Number(p.latitudeWGS84) || 0, // if latitudeWGS84 is renamed upstream, this silently // becomes 0 — no error, ever }; } ``` Parse at exactly two seams: SDK → app (responses) and form → SDK (writes). Downstream functions receive a real typed value, not `unknown`. ### Keep data access thin It's tempting to wrap CDF calls in service classes with interfaces for testability, but for a read-mostly UI, the overhead rarely pays off. An interface, a class, a ServicesContext, and a per-hook DepsContext to perform a single `list()` means touching four files for what should be one hook. A typed query hook is sufficient. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // useAlerts.ts — one obvious place per resource export function useAlerts() { const client = useCogniteSdk(); return useQuery({ queryKey: ["alerts"], queryFn: async () => { const res = await client.instances.list(ALERT_SOURCE); return res.items.map((node) => { const raw = node.properties?.[VIEW.space]?.[KEY] ?? {}; return AlertSchema.parse(raw); // consumers receive Alert[] — never unknown }); }, }); } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // services/cpv-plan-service.ts export interface CpvPlanService { listPlans(): Promise; } export class ApiCpvPlanService implements CpvPlanService { /* ... */ } // contexts/services-context.tsx const defaultServices = { cpvPlanService: new MockCpvPlanService(), // mock as the default! }; export const useServices = () => useContext(ServicesContext); // + a per-hook DepsContext just to inject a mock in tests ``` A service class earns its place when there's real logic — pagination, joining, write-shaping — or a genuine need to swap implementations. Start with a typed query hook; promote only when the body actually grows. All CDF API calls must go through the SDK via `useCogniteSdk()`. Never make raw `fetch` or `axios` requests to CDF endpoint URLs. The SDK handles token refresh, retries on rate-limit errors (429s), typed error responses, and consistent request tracing — none of which you get from a plain fetch. ### Choose the right home for client state React Context and Zustand solve different problems. Context re-renders every consumer when its value changes, which suits values that rarely change. Zustand re-renders only components that subscribe to the changed slice, which suits values that change frequently. Use Context for app-shell configuration that is set once and read everywhere, for example, the CDF client, current user, and feature flags. Use Zustand for state that updates during user interaction, such as selections, filters, and wizard drafts, or that many unrelated components read. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // store.ts — colocated with the feature // Use Zustand for state that changes often (filters, selection) export const useTriageStore = create((set) => ({ selectedId: null, filters: defaultFilters, select: (id) => set({ selectedId: id }), setFilters: (f) => set((s) => ({ filters: { ...s.filters, ...f } })), })); // Components subscribe only to the slice they need function Row({ id }: { id: string }) { const selected = useTriageStore((s) => s.selectedId === id); const select = useTriageStore((s) => s.select); // re-renders only when this row's selected state changes } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // State threaded through every level as props // Or a hand-rolled Context per concern const Ctx = createContext(null); function Provider({ children }) { const [sel, setSel] = useState(null); return {children}; } // Every consumer re-renders when any value in the context changes ``` Start with `useState` for local state. Lift to Context when a stable value needs to be available across the tree. Reach for Zustand when that value starts changing frequently, when you're prop-drilling beyond 3 levels, or when Context re-renders become noticeable. ### Separate data from display When components grow past a few hundred lines, they are usually doing too much: fetching their own data, computing derived values, and rendering in one place. That makes them harder to test in isolation and easier to break with unrelated edits. Extract data and logic into a view-model hook instead, and let the component focus on rendering. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // hook owns data & commands — testable in isolation function usePipelineRun() { const run = useMutation({ mutationFn: runPipeline }); return { run: run.mutate, isPending: run.isPending, error: run.error }; } // component is a thin binding to the design system function PipelinePanel() { const { run, isPending, error } = usePipelineRun(); return ( {error && {error.message}} ); } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function PipelinePanel({ sdk }: { sdk: CogniteClient }) { const [loading, setLoading] = useState(false); const [error, setError] = useState(null); // dozens more useState, inline service calls, business logic… return (

{error &&

{error}

}

); } ``` ### No business logic in UI components This extends the view-model pattern above. When agents or developers add features quickly, business logic accumulates in components: a `useQuery` call here, a `useEffect` fetch there, an inline command handler that should live in a hook. Over time the component becomes the source of truth for data fetching and commands that belong in hooks. Keep components responsible for rendering and local UI state only; everything else belongs in a hook instead. ```tsx Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function FormUI() { // business logic lives in the hook const { data, isLoading, addData } = useFormBusinessLogic(); // UI state stays in the component const [modalOpen, setModalOpen] = useState(false); // simple UI events are fine const handleChange = (e: ChangeEvent) => { // ... }; return

...

; } ``` ```tsx Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function FormUI() { // BAD: data fetching in the component const { data } = useQuery({ queryKey: ["form"], queryFn: fetchFormData }); const { mutate } = useMutation({ mutationFn: submitForm }); // BAD: business command defined in the component body useEffect(() => { api.fetch().then(setState); }, []); const addData = useCallback(() => { api.addData(); }, []); return

...

; } ``` Modal open/close, hover, and resize observers are UI state. Keep them in the component. ### Compute derived values during rendering When a value can be computed from existing props or state, the temptation is to store a copy in `useState` and keep it in sync with `useEffect`. This is unnecessary: React re-runs the component on every relevant state change anyway, and an inline `const` is always up to date. The `useEffect` version causes two renders: one with the stale value, one after the Effect fires, and adds a copy that can drift from its source. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // Always up to date — no Effect needed const filtered = items.filter((i) => i.active); // For genuinely expensive transforms, memoize const sorted = useMemo(() => items.slice().sort(byDate), [items]); ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // Extra state that can drift from its source const [filtered, setFiltered] = useState([]); useEffect(() => { setFiltered(items.filter((i) => i.active)); }, [items]); // Causes two renders: one with the stale value, one after the Effect fires ``` The [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) React article covers the full range of cases where `useEffect` is the wrong tool: derived state, event handlers, parent notification, and more. ### Keep hooks single-purpose As features grow, hooks often return unrelated values together: query data, derived fields, and callbacks in one object. A component that uses only one of those values still re-renders when any other value changes. Split hooks by responsibility, not by feature area. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // Split into focused hooks — each component subscribes to what it needs const useUserStats = () => { // ... return { userStats }; }; const useChartData = () => { // ... return { chartData }; }; function UserStatsComponent() { const { userStats } = useUserStats(); // only re-renders when userStats changes return

{userStats.total}

; } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} const useDashboardLogic = () => { // lots of unrelated logic return { userStats, chartData, recentActivity, settings }; }; function UserStatsComponent() { // re-renders when chartData or recentActivity change, // even though this component only uses userStats const { userStats } = useDashboardLogic(); return

{userStats.total}

; } ``` Signal to split: multiple components call the same hook but destructure completely different values. ### Expose a narrow interface from hooks Returning the full `query` or `mutation` object from a hook is tempting, but it leaks React Query internals to every caller. If you later change how data is fetched, such as swapping a query for a subscription or adding a transformation, you must update every component that destructures the raw object. Expose only what callers need: data, a loading flag, and named command functions. ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function useFormBusinessLogic() { const query = useQuery({ queryKey: ["form"], queryFn: fetchFormData }); const mutation = useMutation({ mutationFn: submitForm }); // wrap mutations in named command functions const addData = (data: DataType) => mutation.mutate(data); // derive cheap values inline const itemCount = query.data?.length ?? 0; // memoize only when profiling shows a real cost const sortedItems = useMemo( () => query.data?.slice().sort(byDate), [query.data] ); return { data: query.data, isLoading: query.isLoading, addData, itemCount, sortedItems, }; } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function useFormBusinessLogic() { const query = useQuery({ queryKey: ["form"], queryFn: fetchFormData }); const mutation = useMutation({ mutationFn: submitForm }); const store = useMyStore(); // raw store exposed directly // returning full objects leaks internals to every caller return { query, mutation, store }; } ``` ### Make impure dependencies injectable Hooks that call `useQuery`, `useMutation`, routing hooks, or SDK clients are impure. Hard-coded imports make them difficult to test without `vi.mock`. That workaround is path-coupled and not type-checked. It can also break silently when you rename or move a file. There are two ways to make dependencies injectable. Choose based on the unit's depth in the tree, and be consistent within a unit: * For shallow units, add a `deps` prop with real implementations as the default. Tests pass a typed substitute directly, no mocking needed. * For containers and nested trees, put dependencies in a `.context.tsx` file with real defaults so production code needs no Provider. Tests inject via ``. ```tsx Do — Default-Props DI wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // tasks.tsx import { useTasks as useTasksImpl } from "../services/use-tasks"; import type { Task } from "../types"; type TasksDeps = { useTasks: () => { isLoading: boolean; tasks: Task[] }; }; const defaultDeps: TasksDeps = { useTasks: useTasksImpl }; export const Tasks = ({ deps = defaultDeps }: { deps?: TasksDeps }) => { const { isLoading, tasks } = deps.useTasks(); if (isLoading) return ; return

)}

; }; // tasks.spec.tsx — no vi.mock needed const deps: ComponentProps["deps"] = { useTasks: vi.fn(() => ({ isLoading: false, tasks: [{ id: "1", text: "a" }] })), }; render(); ``` ```tsx Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // Discouraged for first-party modules: path-coupled, not type-checked. // Renaming use-tasks.ts breaks this test without a type error. import { useTasks } from "../services/use-tasks"; vi.mock("../services/use-tasks", () => ({ useTasks: () => ({ isLoading: false, tasks: [] }), })); ``` `vi.mock` remains appropriate for third-party and external libraries. For first-party code, prefer a typed seam. If you find yourself prop-drilling `deps` through intermediate components, switch to Context DI instead. ### Use Aura instead of inline styles Inline `style={{}}` objects bypass the `aura/no-overriding-styles` ESLint guardrail and guarantee visual drift from the [Aura design system](/cdf/aura). They also signal that the component is doing too much: they often appear in oversized components that also mix in data fetching and business logic. If you need to customize the appearance or styling, follow this order of priority: 1. Use the component props and variants available in the design system. 2. Use [Tailwind utility classes](https://tailwindcss.com/docs/styling-with-utility-classes) for additional styling. 3. If neither option is sufficient, raise a support ticket with the Aura team. For details on supported customization options, see the [Aura customization documentation](/cdf/aura/developer-guide/customization). ```tsx Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function StatusCard({ status }: { status: "ok" | "error" }) { return ( {status} ); } ``` ```tsx Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} function StatusCard({ status }: { status: "ok" | "error" }) { return (

{status}

); } ``` The `aura/no-overriding-styles` ESLint rule enforces this automatically. Don't disable or suppress it. Browse [Aura primitives](/cdf/aura/primitives) for layout and feedback components — for example [Card](/cdf/aura/primitives/card) and [Badge](/cdf/aura/primitives/badge) — instead of styled HTML elements. ### Centralize your data model config Do not scatter view IDs, space names, and property keys as string literals across your codebase. When you port a Flows custom app to another CDF project, or rename a space or view, you must find and replace every occurrence by hand. Keep all identifiers in `config/model.ts` and import from there instead. For batching and concurrency when you read and write instances, use the `dm-limits-and-best-practices` builder skill ([About builder skills](/cdf/flows/concepts/skills)). ```typescript Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // config/model.ts — one place for all CDF view identifiers export const MODEL = { space: "my-solution-space", views: { well: { externalId: "Well", version: "1" }, }, properties: { well: { name: "name", uwi: "uwi", lat: "latitudeWGS84" }, }, } as const; // Changing the space name means editing one line here. // All usages across the codebase update automatically. function useWells() { const client = useCogniteSdk(); return useQuery({ queryKey: ["wells"], queryFn: () => client.instances.list({ sources: [{ source: { type: "view", ...MODEL.views.well, space: MODEL.space } }], }), }); } ``` ```typescript Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} // useWells.ts function useWells() { const client = useCogniteSdk(); return useQuery({ queryKey: ["wells"], queryFn: () => client.instances.list({ sources: [{ source: { type: "view", externalId: "Well", version: "1", space: "my-solution-space" } }], }), }); } // useWellFilters.ts — same literals, different file const filter = { equals: { property: ["my-solution-space", "Well/1", "uwi"], value: uwi } }; // WellDetail.tsx — and again const lat = node.properties?.["my-solution-space"]?.["Well/1"]?.["latitudeWGS84"]; // Rename the space or bump the view version and you'll miss at least one. ``` ### Handle errors in two layers Without a defined error strategy, each component handles failures differently. Some store error text in state and render a red `

`. Others fail silently with an empty screen. An uncaught render error can crash the whole iframe. Use two layers for most cases.


  ```tsx Do wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  // App.tsx — one boundary at the shell catches render crashes
  }>
    
      
    
  

  // Per view — use the query's own error state
  const { data, error, isError, refetch } = usePlans();
  if (isError) return ;

  //  is one shared component used everywhere
  ```

  ```tsx Don't wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  // Per-component string + red pre
  try {
    const data = await svc.load();
    setData(data);
  } catch (e) {
    setError(e instanceof Error ? e.message : String(e));
  }

  {error && {error}}
  // A render crash takes down the whole iframe.
  // Retry = reload the page.
  ```


## Quick reference

The following table summarizes the patterns on this page.

| Stop doing | Start doing |
| - | - |
| Fetching with `useState` + `useEffect` + `fetchKey` | All CDF reads and writes behind `useQuery`/`useMutation` in a dedicated hook |
| Chained `as` casts at every call site | One Zod schema per view; `parse()` at both seams; type via `z.infer` |
| Interface + class + two context layers for a single `list()` | Typed `use*` hook with `useQuery` inline |
| Prop-drilling shared state beyond 3 levels | Zustand for frequently-updating state; Context for stable globals |
| Components that fetch, compute, and render | View-model hook + thin Aura-built component; `useQuery`/`useMutation` only in hooks, never in `.tsx` files |
| Hooks that return full `query`/`mutation` objects | Narrow return: `{ data, isLoading, addData }` |
| One hook returning everything for a domain | Focused single-purpose hooks per concern |
| `vi.mock` on first-party modules to bypass missing seams | Typed DI (Default-Props or Context) |
| Inline `style={{}}` objects | Aura/Tailwind primitives enforced by `aura/no-overriding-styles` |
| View IDs and space names scattered as string literals | Central `config/model.ts` |
| Per-component error strings / red `` | One `` at the shell + shared `` |

## Related topics

* [About Flows custom app features](/cdf/flows/concepts/features) — Scaffolding, TanStack Query, auth, and what ships with every Flows custom app.
* [Auth API](/cdf/flows/reference/api/auth) — `connectToHostApp` and authenticated SDK access.
* [Host App API](/cdf/flows/reference/api/host-app-api) — Navigation, state, sidebar visibility, fullscreen, and agent integration.
* [About spec-driven development](/cdf/flows/concepts/spec-driven-development) — Checked-in specs for you and your agent.
* [About builder skills](/cdf/flows/concepts/skills) — Skills including `design`, `dm-limits-and-best-practices`, and `security`.
* [Flows custom apps quality guidelines](/cdf/flows/guides/quality-guidelines) — Certification rubric including Aura consistency.
* [Aura design system](/cdf/aura) — Components, tokens, and patterns for Flows custom app UIs.
* [Get started with Flows](/cdf/flows/guides/getting-started) — Create a project and run it in CDF.


# About Flows custom app features
Source: https://docs.cognite.com/cdf/flows/concepts/features

Overview of Flows features for building custom apps for Cognite Data Fusion (CDF): scaffolding, authentication, Vite local development, TanStack Query, testing, code quality, TypeScript, and deployment.

**Flows** (`@cognite/cli`) is a CLI for building production-ready React apps that run inside **CDF**. You get project scaffolding, authenticated access to the Cognite SDK, Vite-based local development, and paths to deploy without assembling those pieces yourself.

For a hands-on path from install to first run, see [Get started with Flows](/cdf/flows/guides/getting-started).

## Scaffolding

You create a full app layout, configuration, and recommended tooling with a single command:

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

The generator captures org, project, and cluster in `app.json` and sets up **Cursor** rules when you use Cursor as your editor. See [Get started with Flows](/cdf/flows/guides/getting-started#create-and-run-your-app) for prompts and folder layout.

## UI with Aura

Generated apps include **`@cognite/aura`**. Use the [Aura design system](/cdf/aura) for foundations, primitives, and patterns, and [Installing Aura](/cdf/aura/guides/installation) to add or upgrade the package.

## Authentication in CDF

Flows integrates with CDF sign-in when your app runs in the CDF iframe. Call **`connectToHostApp()`** from **`@cognite/app-sdk`** to get a **`HostAppAPI`** instance, then use `getProject()`, `getBaseUrl()`, and `getAccessToken()` to construct an authenticated **`CogniteClient`**.

See the [Flows Auth API](/cdf/flows/reference/api/auth) for props, loading and error, and return values.

To start an additional Microsoft Entra ID sign-in from within a Flows custom app, see [Signing in with an additional Microsoft Entra ID account](/cdf/flows/guides/oauth-relay).

## Local development with Vite

Templates use **Vite** with **hot module replacement (HMR)**, **HTTPS** on localhost (locally trusted certificates), and optional **auto-open in CDF** via `fusionOpenPlugin`. With auto-open, you run the dev build inside the CDF iframe and hit the same sign-in flow and URLs you get when the app is published.

See [Run your app locally](/cdf/flows/guides/running-locally) and the [Vite plugin API](/cdf/flows/reference/api/vite).

## Build and deploy

Deploy to **CDF** directly:

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

Preview deployments for pull requests:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
npm run deploy-preview
```

For interactive deploy and CI/CD, see [Deploy your Flows app](/cdf/flows/guides/deploying).

## Testing

Generated custom apps include **Vitest** and **React Testing Library**. From your app directory, run:

```bash wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
npm test           # Run tests
npm run test:watch # Watch mode
npm run test:ui    # Visual UI
```

Script names are defined in `package.json`.

## Code quality

The template ships with **ESLint** configuration (`eslint.config.mjs`) and npm scripts for linting and formatting. From your app directory, run:

```bash wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
npm run lint       # Check for issues
npm run lint:fix   # Auto-fix issues
```

Script names are defined in `package.json`.

## Data fetching with TanStack Query

**TanStack Query (React Query)** is included so you can pair cached, declarative data loading with an authenticated SDK from `connectToHostApp()`:

```tsx wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { useQuery } from "@tanstack/react-query";
import { CogniteClient } from "@cognite/sdk";

function Assets({ sdk }: { sdk: CogniteClient }) {

  const { data, isLoading } = useQuery({
    queryKey: ["assets"],
    queryFn: () =>
      sdk.instances.list({
        instanceType: "node",
        limit: 10,
        sources: [
          {
            source: {
              type: "view",
              space: "cdf_cdm",
              externalId: "CogniteAsset",
              version: "v1",
            },
          },
        ],
      }),
  });

  if (isLoading) return Loading assets...;

  return (
    
      {data?.items.map((asset) => (
        
          {asset.properties?.["cdf_cdm"]?.["CogniteAsset/v1"]?.name}
        
      ))}
    
  );
}
```

## TypeScript

Apps are **TypeScript-first**, with strict settings suited to app development. Types from **`@cognite/sdk`** (for example, resources such as assets) work with your components and hooks as you build out the UI.

```tsx wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import type { Asset } from "@cognite/sdk";

function AssetCard({ asset }: { asset: Asset }) {
  return (
    
      {asset.name}
      {asset.description}
    
  );
}
```

## Further reading

* [Get started with Flows](/cdf/flows/guides/getting-started) — Create a project and run it in CDF.
* [Aura design system](/cdf/aura) — Foundations, primitives, and patterns for Flows custom app UI.
* [Run your app locally](/cdf/flows/guides/running-locally) — Dev server, HTTPS, and troubleshooting.
* [Signing in with an additional Microsoft Entra ID account](/cdf/flows/guides/oauth-relay) — Additional Microsoft Entra ID sign-in via the App Hosting OAuth relay.
* [Deploy your Flows app](/cdf/flows/guides/deploying) — Interactive deploy and CI/CD.


# About Flows custom apps
Source: https://docs.cognite.com/cdf/flows/concepts/index

Understand the core concepts of Flows custom apps, from built-in features and AI skills to spec-driven development for Cognite Data Fusion (CDF) apps.

Learn what **Flows** (`@cognite/cli`) gives you out of the box and how to align your team around specs before you dive into procedures and APIs.


  
    Scaffolding, auth, Vite, tests, deploy, and data fetching at a glance.
  

  
    Agent-agnostic AI skills that ship with every Flows custom app.
  

  
    Plan features in checked-in specs your team and agent both work from.
  

  
    Draft vs published versions and how the active version works.
  

  
    Patterns and pitfalls for keeping Flows apps well-structured as they grow.
  



# About builder skills
Source: https://docs.cognite.com/cdf/flows/concepts/skills

Learn about builder skills, how they ship with every app, which AI development environments are supported, and how to keep skills up to date.

**Skills** extend AI agent capabilities with specialized knowledge and workflows. The Flows builder skills help your AI coding agents build and deploy Flows custom apps for **Cognite Data Fusion (CDF)**. They capture Cognite best practices, API guidance, and opinionated workflows so agents such as Claude Code, Cursor, GitHub Copilot, Windsurf, and any agent that follows the [Agent Skills](https://agentskills.io/home) standard stay aligned from the first prompt.

## How skills are delivered

When you run `npx @cognite/cli@latest apps create`, the CLI fetches skills automatically from the [`cognitedata/builder-skills`](https://github.com/cognitedata/builder-skills) repository and writes them into your app. No extra install or configuration — compatible agents read the skill files from your workspace.

The generated app places skills in two directories so that compatible agents can locate them automatically:

| Directory | Supported coding agents |
| - | - |
| `.agents/skills/` | Cursor, Windsurf, Cline, Continue.dev, Aider, OpenHands, Devin, and any agent following the [Agent Skills](https://agentskills.io/home) standard |
| `.claude/skills/` | **Claude Code** (Anthropic) — dedicated path for Claude Code skill files |

In addition, two root-level context files give agents project-wide instructions at the start of each session:

| File | Supported coding agents |
| - | - |
| `AGENTS.md` | Cursor, GitHub Copilot, Windsurf, Cline, Aider, OpenHands, Devin, and most other agents |
| `CLAUDE.md` | **Claude Code** — project memory file loaded at the start of every Claude Code session |

## Keep skills up to date

Cognite updates the `builder-skills` repository regularly. To pull the latest skills into an existing app, run:

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

To pull a specific skill:

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


  Pull skills after upgrading `@cognite/cli` or when starting new work that touches authentication, data modeling, or Atlas agents — areas where Cognite updates skills most often.


## Example skills

The following table lists skills that ship with new apps.

| Skill | Purpose |
| - | - |
| `setup-flows-auth` | Wire up `connectToHostApp` and authenticated CDF access. |
| `integrate-atlas-chat` | Add a streaming **Atlas Agent** chat interface to your app. |
| `create-client-tool` | Generate an `AtlasTool` and integrate it with `useAtlasChat`. |
| `design` | Apply **[Aura](/cdf/aura)** UI components, tokens, layouts, and accessibility guidance. |
| `dm-limits-and-best-practices` | Follow **CDF** data modeling concurrency and batching guidance. |
| `performance` | Optimize for speed, render counts, and bundle size. |
| `security` | Review for credentials, user input, and external data vulnerabilities. |
| `flows-app-brief` | Coach you through the App Brief before you build. |
| `flows-code-review` | Run the technical review and surface Must Fix items. |
| `flows-design-review` | Score the app against the 10 design quality questions. |
| `flows-external-app-submit` | Verify all artifacts and submit for [Application certification](/cdf/flows/guides/application-certification). |

For the full list and the source of each skill, see [`cognitedata/builder-skills`](https://github.com/cognitedata/builder-skills).

## Supported AI development environments

Flows custom apps work with **any modern AI coding agent**. Every generated app includes builder skills that agents detect and use automatically without manual configuration.


  **Claude Code is fully supported.** Every generated app includes a dedicated `.claude/skills/` directory and a `CLAUDE.md` project context file, giving Claude Code immediate, structured access to Cognite development guidelines.


The table below shows which environments are supported, where each agent reads skills from, and what project context file it uses. If your preferred environment is not listed, it can still work via `AGENTS.md`.

| Agent / Environment | Vendor | Skills directory | Project context file | MCP support | Status |
| - | - | - | - | - | - |
| **Cursor** | Anysphere | `.agents/skills/` | `AGENTS.md` | Yes (`.cursor/mcp.json`) | Recommended |
| **Claude Code** | Anthropic | `.claude/skills/` | `CLAUDE.md` | Yes | Fully supported |
| **GitHub Copilot** | Microsoft / GitHub | `.agents/skills/` | `AGENTS.md` | Limited (VS Code only) | Supported |
| **Windsurf** | Codeium | `.agents/skills/` | `AGENTS.md` | Yes | Supported |
| **Google Gemini (Antigravity)** | Google | `.agents/skills/` | `AGENTS.md` | Planned | Supported |
| **Amazon Q Developer** | Amazon | `.agents/skills/` | `AGENTS.md` | Limited | Supported |
| **Continue.dev** | Continue | `.agents/skills/` | `AGENTS.md` | Yes | Supported |
| **Cline** | Community / Anthropic | `.agents/skills/` | `AGENTS.md` | Yes | Supported |
| **Aider** | Aider-chat | `.agents/skills/` | `AGENTS.md` | No | Supported |
| **OpenHands** | All Hands AI | `.agents/skills/` | `AGENTS.md` | No | Supported |
| **Devin** | Cognition AI | `.agents/skills/` | `AGENTS.md` | No | Supported |
| **JetBrains AI Assistant** | JetBrains | `.agents/skills/` | `AGENTS.md` | No | Partial |
| **Zed AI** | Zed Industries | `.agents/skills/` | `AGENTS.md` | Yes | Partial |
| **VS Code (Copilot Chat)** | Microsoft | `.agents/skills/`. | `AGENTS.md` | Limited | Supported |
| **Gemini CLI** | Google | `.agents/skills/` | `AGENTS.md` | Yes | Supported |
| **Amp** | Sourcegraph | `.agents/skills/` | `AGENTS.md` | Yes | Supported |

**Column legend:**

* **Skills directory** — where the agent reads builder skill files from the generated app
* **Project context file** — the root-level file the agent reads for project-wide instructions
* **MCP support** — whether the environment supports Model Context Protocol tool servers, useful for connecting to CDF APIs directly from your agent


  Skills are included in both `.agents/skills/` (for Cursor and the [Agent Skills](https://agentskills.io/home) standard) and `.claude/skills/` (for Claude Code). To update skills, run `npx @cognite/cli@latest apps skills pull`.


## Further reading

* [Get started with Flows](/cdf/flows/guides/getting-started) — Create an app and see skills land in your workspace.
* [Flows features](/cdf/flows/concepts/features) — Everything the template gives you at a glance.


# About spec-driven development
Source: https://docs.cognite.com/cdf/flows/concepts/spec-driven-development

Learn how spec-driven development works in Cognite Flows: a checked-in SPEC.md for each app, or optional spec-kit slash commands for structured per-feature planning before you write code.

In Flows, you treat checked-in specs as the source of truth for a feature: they align your team and give your agent the same brief every time you return to the repo.

## Specs vs. plan mode

**Plan mode** (for example in Claude Code, or similar in-session planning in other AI coding tools) fits **one conversation**: you think through the task now, and your agent can act on that plan immediately.

**Repo-native specs** live in **git**, survive across sessions, can go through **review** like code, and travel with the feature from first sketch to release. You refine the spec as you learn, share it with collaborators, and reuse it as **stable context** whenever you open the project with your agent.

The approaches stack. You can use plan mode **inside** a spec-kit flow — for example, reason in-session, then run `/speckit.tasks`. Specs anchor **what** you are building; in-session planning helps with **how** you execute the next slice.

## Two modes in Flows

When you run `npx @cognite/cli@latest apps create`, the CLI asks how you want to plan your app.

| Mode | When to use |
| - | - |
| **Lightweight `SPEC.md` (default)** | One structured `SPEC.md` at the repository root. No spec-kit bundle or slash commands. Solo work, small apps, early ideation, or a single spec for the whole app. |
| **[Spec-kit](#spec-kit) (opt-in)** | Per-feature specs under `specs/-/` and slash commands in Claude Code and Cursor, using a curated, vendored subset of [spec-kit](https://github.com/github/spec-kit). Teams, multi-session work, or several distinct features. |


  The spec-kit prompt defaults to **No**. If you skip it and want spec-kit later, there is no retrofit command — you would need to re-scaffold or manually copy the [spec-kit files](#spec-kit) into your app.


## Lightweight SPEC.md

By default, your Flows custom app includes `SPEC.md` at the repository root. Use it as a living product spec: the template captures user intent, requirements, and how the app integrates with CDF data models.

The following table describes each section.

| Section | Purpose |
| - | - |
| **User Stories** | Who uses the app, what they want, and why. |
| **Acceptance Scenarios** | Given / When / Then statements. |
| **Functional Requirements** | Numbered FRs (FR-001, FR-002, …) plans and tasks can reference. |
| **Success Criteria** | Measurable, user-visible outcomes. |
| **Clarifications** | Open questions before planning starts. |
| **Assumptions** | Scoping decisions and out-of-scope items. |
| **Data Models & CDF Integration** | Existing views, new views, and spaces *(mandatory)*. |

**Example**: a populated excerpt for a **Production Accounting dashboard**. This is a CDF app that shows oil balance KPIs and a hierarchical reconciliation tree with quality-flagged flow components:


  ```markdown wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  ## User Stories

  ### User Story 1 — View at-a-glance production KPIs (Priority: P1)

  A production accountant opens the dashboard to get an immediate snapshot
  of oil balance health. The KPI bar surfaces four headline metrics —
  Gross Production, Net Export, Imbalance, and Closure % — so the
  accountant can tell at a glance whether the period is closing within
  acceptable tolerance.

  ### User Story 2 — Explore the Balance Reconciliation Tree (Priority: P2)

  The accountant needs to trace the source and destination of production volumes. The Balance Reconciliation Tree is a hierarchical table
  of flow components (Wellhead Production → Field Gross → Terminal
  Receipts → Pipeline Export → Losses). Each row shows the component
  name, a numeric value with a unit, a source tag, and a quality badge
  (Verified / Estimated / Manual).

  ## Functional Requirements

  - FR-001: The dashboard MUST display a KPI bar with four metrics:
    Gross Production (Mbbl), Net Export (Mbbl), Imbalance (Mbbl),
    and Closure (%). Imbalance MUST be derived from tree data;
    Closure % MUST equal Net Export / Gross Production × 100.
  - FR-004: The Balance Reconciliation Tree MUST render as a 
    hierarchical table with collapsible parent rows and child rows.
  - FR-006: Quality badges MUST support exactly three states:
    Verified (success tone), Estimated (warning tone),
    Manual (neutral tone).

  ## Edge Cases

  - A flow component with no source tag MUST render an em-dash (—)
    placeholder, never a blank cell.
  - When Imbalance is exactly zero, the Imbalance KPI MUST render in a
    neutral success tone (fully balanced).
  - When Closure % exceeds 100%, the value MUST render as-is in a
    warning tone (over-allocation).

  ## Success Criteria

  - SC-001: The KPI bar renders within 1 second of load.
  - SC-003: A user can locate any flow component in the tree in under
    30 seconds using expand/collapse and the quality filter.
  - SC-005: The tree supports at least 3 levels of hierarchy without
    layout breakage.

  ## Assumptions

  - Each balance covers a single reporting period; a period picker is
    out of scope for v1.
  - Volumes are in Mbbl (thousand barrels); Closure is a percentage.
  - The app embeds in the Cognite Data Fusion iframe; auth is delegated to
    the host. Export and print are out of scope for v1.

  ## Data Models & CDF Integration

  ### Existing views

  - `cdf_cdm.CogniteTimeSeries:v1` — meter readings and production rates
    behind each source tag (for example, `FLD-GROSS-001`, `LIFT-TOT-001`).

  ### New views

  - `production_accounting.FlowComponent:v1` — one node per balance line.
    Properties: name (string), parent (direct relation to FlowComponent),
    value (float64), unit (string), sourceTag (string),
    quality (enum: Verified | Estimated | Manual).
  - `production_accounting.BalancePeriod:v1` — a reporting period and its
    rollup KPIs. Properties: periodStart (timestamp), periodEnd (timestamp),
    grossProduction (float64), netExport (float64).

  ### Spaces

  - `production_accounting` — the app's own data model space.
  - `cdf_cdm` — read-only; Cognite's core data model space.
  ```


Your agent reads `SPEC.md` before making feature decisions and keeps it in sync with code changes as directed by `AGENTS.md`.

## Spec-kit

When you opt into spec-kit during `apps create`, the CLI installs a curated vendor bundle. The following list describes what is added to your repository.

* **`.specify/`** — templates, bash scripts, and configuration (`branch_numbering: sequential`).
* **`.claude/commands/speckit.*.md`** — slash commands for Claude Code.
* **`.cursor/commands/speckit.*.md`** — slash commands for Cursor.
* **`.specify/memory/constitution.md`** — a symlink to `AGENTS.md`, so spec-kit commands pick up your app's coding standards automatically.

Specs are stored at `specs/-/spec.md`, one directory per feature. Numbering is sequential: `001-production-accounting`, `002-export-report`, and so on.

For a full worked run of `/speckit.specify`, `/speckit.clarify`, and `/speckit.plan`, including the exact commands, the clarification questions and answers, and the generated plan, see [Plan a dashboard app with spec-kit](/cdf/flows/guides/spec-kit-walkthrough). The sections below summarize each command with a short example.

### `/speckit.specify`

The `/speckit.specify` command generates a new feature spec directory from a short description. It creates `specs/-/spec.md` pre-populated with the spec-kit template, including a Flows-specific **Data Models & CDF Integration** section.

```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
/speckit.specify Build an Oil Balance Detail dashboard called 'Production Accounting' with a KPI bar and a Balance Reconciliation Tree of flow components with quality badges. Read data from CDF data models. React + Tailwind.
```

This example creates `specs/001-production-accounting/spec.md`. Complete the template sections before the next step, with **Data Models & CDF Integration** as the highest priority.

### `/speckit.clarify`

The `/speckit.clarify` command reads the current spec, surfaces questions that would block planning, and does not generate code.

The command runs an internal coverage scan (functional scope, data model, integration, edge cases, and more), then asks up to five targeted questions, each with a recommendation and options. For the Production Accounting dashboard, it surfaced questions such as:

* Is the Imbalance value derived from the tree, or independent of it?
* Is the Imbalance warning threshold hardcoded or user-configurable?
* Which UI state, if any, should persist in the CDF URL?

You answer each question in your agent session, and the answers are written directly back into the **Clarifications** section of `spec.md`, so the choices are recorded in git.

### `/speckit.plan`

The `/speckit.plan` command reads the clarified spec and generates a numbered implementation plan inside the feature directory — typically a summary, a technical context block, a constitution check against your `AGENTS.md` coding standards, and a project structure:

```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
specs/001-production-accounting/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── tasks.md        # created later by /speckit.tasks
```

If you prefer not to run `/speckit.plan`, you can plan the implementation another way — for example, with your agent's in-session plan mode — and still produce a numbered implementation plan in the feature directory.

When you run `/speckit.tasks`, it decomposes that implementation plan into the ordered list in `tasks.md` (see `/speckit.tasks`). The plan can come from `/speckit.plan` or from your own write-up, as long as the steps are numbered and ordered clearly enough to split into tasks.

### `/speckit.tasks`

The `/speckit.tasks` command writes an ordered task list to `tasks.md` in the feature directory, next to `spec.md`, following the pattern `specs/-/tasks.md` (this guide uses `specs/001-production-accounting/tasks.md`). Each task maps back to a functional requirement so your agent can track progress against the spec.

### `/speckit.implement`

The `/speckit.implement` command runs the tasks in order, using both the spec and task list as context. It works through the Production Accounting feature — scaffolding the KPI bar, building the reconciliation tree with collapsible rows and quality badges, wiring the quality filter, and integrating with the CDF host via `@cognite/app-sdk`. It stops at each task to confirm before continuing.

## Where do specs live?

Specs live in your repository alongside your code. Check them in with your changes so behavior, intent, and data model choices stay traceable in the same history as the implementation. Review spec updates in pull requests and keep them versioned in git under the same ownership model you use for source files.

## Spec-driven development vs. waterfall

Classic waterfall runs into trouble when design is fixed for a long time before code ships. This workflow is different: you record enough to start building, then tighten the spec as you learn from implementation.

The target is a *good enough* plan — clarity without endless prework. Ten minutes capturing intent in a spec often saves hours of repeated clarification with an agent that still lacks shared context.

You won't write a perfect spec, and that is expected. Unknowns stay open until you resolve them, and when requirements change, you update the document and keep going. The spec is not a contract locked at kickoff; it is a living document that lowers the cost of change as you learn.

## Next steps

* [Plan a dashboard app with spec-kit](/cdf/flows/guides/spec-kit-walkthrough) — Run through specify, clarify, and plan on a real example.
* [Get started with Flows](/cdf/flows/guides/getting-started) — Create an app and see `SPEC.md` land in your workspace.
* [Flows skills](/cdf/flows/concepts/skills) — Agent-agnostic skills that ship alongside your spec in every Flows custom app.
* [spec-kit on GitHub](https://github.com/github/spec-kit) — Upstream project and full command reference.


# Integrating AI agents with Flows
Source: https://docs.cognite.com/cdf/flows/guides/ai_agent_integration

Step-by-step guide to integrating Atlas AI agents with Cognite Flows custom apps in Cognite Data Fusion (CDF) using @cognite/app-sdk.

This guide is for developers building **Flows** custom apps in **Cognite Data Fusion (CDF)**. You will connect your app to any agent built with [Atlas AI](/cdf/atlas_ai) in CDF: expose app state as resources, register actions the agent can call, and send messages from your UI. Complete the [prerequisites](#prerequisites) before you follow the integration steps.

With `@cognite/app-sdk@0.3.1` or later, you can:

* **Let the agent see your Flows custom app.** Expose the app's content and state as resources the agent can add to its context.
* **Let the agent interact with your Flows custom app.** Register actions as tools the agent can use to perform tasks in your app on the user's behalf.
* **Send messages from your Flows custom app to the agent.** Trigger context-aware prompts when the user clicks a button or reaches a key point in a workflow.

## Prerequisites

Before you start, ensure you have:

* Access to **Cognite Data Fusion (CDF)** with appropriate capabilities. See [Assign capabilities](/cdf/access/guides/capabilities#flows-custom-apps) for more information.

* A **Flows** development environment set up. See [Get started with Flows](/cdf/flows/guides/getting-started).

* `@cognite/app-sdk@0.3.1` or later installed. This version adds the agent panel, messaging, and server registration APIs used in this guide.

  ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  npm install @cognite/app-sdk
  ```

* A `HostAppAPI` instance from `connectToHostApp` on mount:

  ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  import { connectToHostApp } from '@cognite/app-sdk';

  const { api } = await connectToHostApp({ applicationName: 'my-app' });
  ```


  `connectToHostApp` only works when your Flows app runs **inside CDF** (embedded in a CDF page with a parent host window). If you open only the Vite dev URL, for example, `https://localhost:3001`, without loading the app through CDF, there is no host to connect to and the promise rejects.

  Wrap the call in `try`/`catch`. When connect fails, skip `registerAgentServer` and other agent APIs, and hide or disable buttons that open the agent panel or send messages. See [Development and production behavior](#development-and-production-behavior) for an example.


## Integrate the agent

Use your `HostAppAPI` instance to control the Atlas AI agent panel, send messages from your app, and register an agent server with the resources and actions the agent can use.


  
    Call `api.sendAgentLayoutMode` to change the visibility or layout of the agent panel.

    ```typescript theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    await api.sendAgentLayoutMode({ mode: 'sidebar' });
    ```

    **AgentLayoutPayload options:**

    | **Field** | **Type** | **Description** |
    | - | - | - |
    | `mode` | `'sidebar' \| 'fullscreen' \| 'closed'` | Target panel layout. |
    | `conversationId` | `string?` | Resume a specific existing conversation. |
    | `agentExternalId` | `string?` | Target a specific registered agent. |
    | `source` | `AgentSource?` | Surface identifier; omit unless required by your host. |

    `{ mode: 'sidebar' }` is the most common call, typically wired to a persistent toolbar button that opens the assistant at any time.
  

  
    Call `api.sendAgentMessage` to inject text into the agent's chat, optionally starting a fresh session. Use `sendAgentMessage` to pre-populate the agent with context when the user clicks a contextual trigger in your app.

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    await api.sendAgentMessage({
      message: 'Summarize the current state and highlight any risks.',
      newSession: true,
    });
    ```

    **AgentMessagePayload options:**

    | **Field** | **Type** | **Description** |
    | - | - | - |
    | `message` | `string` | Text to inject into the chat. |
    | `newSession` | `boolean?` | Clear the existing conversation before injecting. |

    Call `sendAgentLayoutMode` before `sendAgentMessage`. The agent panel must be open for the user to see the injected message.

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    await api.sendAgentLayoutMode({ mode: 'sidebar' });
    await api.sendAgentMessage({
      message: `Analyze the schedule for "${tarName}" and suggest how to reduce the total duration.`,
      newSession: true,
    });
    ```

    Use `newSession: true` for contextual entry points where the user is starting a new task. Omit it when continuing an existing conversation.
  

  
    An agent server exposes resources (read-only context the agent can request) and actions (tools the agent can call). Register it once on mount, and unregister it on unmount.

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    import { createAgentServer, registerAgentServer } from '@cognite/app-sdk';

    const server = createAgentServer({
      uri: 'my-app://agent-server-unique-id',           // namespaced by CDF with the instance ID
      actions: [...],
      resources: [...],
    });

    await registerAgentServer(api, server);

    // On unmount:
    await api.unregisterAgentServer('my-app://agent-server-unique-id');
    ```

    In React, manage the lifecycle with `useEffect`:

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    useEffect(() => {
      if (!api) return;

      const server = createAgentServer({ uri: 'my-app://agent-server-unique-id', actions, resources });
      void registerAgentServer(api, server);

      return () => {
        void api.unregisterAgentServer('my-app://agent-server-unique-id');
      };
    }, [api]);
    ```

    
      `uri` must be unique within the current app. Different apps can reuse the same `uri`; CDF namespaces it with the instance ID. If the same app registers another server with that `uri`, the new server replaces the existing one.
    
  

  
    Resources are read-only data the agent reads to understand the current app state. Each resource has a URI, a name, and a `read` function that returns content.

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    import { createAgentResource } from '@cognite/app-sdk';

    createAgentResource({
      uri: 'my-app://current-state',
      name: 'Current application state',
      description: 'Describes what data the agent will receive and when it should read this resource.',
      async read() {
        const data = getStateFromSomewhere();
        return [{ type: 'json', data }];
      },
    })
    ```

    The `read` function returns an array of content parts. Each element is one of:

    * `{ type: 'json', data: unknown }` — structured data. The agent reasons over JSON directly; prefer this format when you can.
    * `{ type: 'text', text: string }` — free-form text.

    The `description` field is visible to the agent. Use it to explain what the resource contains and when to read it. Treat it like a function docstring.

    ### Example: TAR planner resources

    The TAR planner application exposes two resources. Both are populated from `TARStorageService` (localStorage) and the critical path algorithm, giving the agent a live view of what the user is managing.

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    createAgentResource({
      uri: 'tar-planner://current-tar',
      name: 'Current TARs',
      description: 'All TARs with name, facility, scope, dates, status, and work order count.',
      async read() {
        return [{ type: 'json', data: storage.getAllTars() }];
      },
    });

    createAgentResource({
      uri: 'tar-planner://schedule-summary',
      name: 'Schedule summary',
      description: 'Per-TAR computed schedule with critical path flags and float.',
      async read() {
        return [{ type: 'json', data: computeScheduleSummary(storage) }];
      },
    });
    ```
  

  
    Actions are tools the agent can invoke. They can be read-only queries or mutating operations. Define parameters with a Zod schema. The `.describe()` call on each field is the agent's documentation for that parameter.

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    import { createAgentAction } from '@cognite/app-sdk';
    import { z } from 'zod';

    createAgentAction({
      name: 'tar-planner://get_item_details',           // snake_case; shown to the agent as the tool name
      description: 'What this does, what it returns, and when to call it.',
      parameters: z.object({
        item_id: z.string().describe('The ID of the item to retrieve'),
        include_history: z.boolean().optional().describe('Whether to include audit history'),
      }),
      async handler({ item_id, include_history }) {
        const item = await myService.getItem(item_id, { history: include_history });
        return {
          content: [{ type: 'json', data: item }],
        };
      },
    })
    ```

    ### Mutating actions

    Mutating actions can write to your app's state.

    
      The agent does not currently confirm with the user before calling mutating actions. Use mutating actions with caution and make the agent's responsibility explicit in the action's `description`.
    

    ```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    createAgentAction({
      name: 'tar-planner://add_work_order_to_tar',
      description:
        'Add a maintenance order to a TAR. Call this ONLY when the user has explicitly approved. The app UI updates immediately.',
      parameters: z.object({
        tar_id: z.string().describe('The TAR to add the work order to'),
        maintenance_order_external_id: z.string().describe('The externalId of the order'),
      }),
      async handler({ tar_id, maintenance_order_external_id }) {
        storage.saveEntry({ tarId: tar_id, maintenanceOrderExternalId: maintenance_order_external_id, ... });
        return { content: [{ type: 'json', data: { success: true } }] };
      },
    })
    ```

    After a mutating action writes to your state layer, the UI updates on the next render cycle if your components read from the same state. No extra signaling is required.
  


## Verify integration

Load your Flows custom app **inside CDF** (through the CDF development URL, not only `https://localhost:3001`). Confirm the following:

1. Open the agent panel from your UI control or a `sendAgentLayoutMode` call.
2. Send a test message and confirm it appears in the agent chat.
3. Ask the agent a question that should use a registered resource and confirm the answer reflects your app state.
4. If you registered mutating actions, test them only after you understand the risks in [Mutating actions](#mutating-actions).


  When integration works, the agent panel opens from your app, messages appear in chat, and resource-backed answers match the state your app exposes.


## Recommended project structure

Separate the registration lifecycle from the action and resource definitions to test both independently.

```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
src/features/agent/
  agentActions.ts     — pure factory: (deps) => Action[]
  agentResources.ts   — pure factory: (deps) => Resource[]
  useAgentServer.ts   — useEffect lifecycle hook; calls the factories and registers
```

Inject services as parameters rather than importing them directly. That approach lets you unit test actions and resources with mock services.

```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
// agentActions.ts
export function buildAgentActions(
  storage: StorageService,
  dataService: DataService,
): AgentActions {
  return [
    createAgentAction({ ..., async handler({ id }) { return storage.get(id); } }),
  ];
}

// useAgentServer.ts
export function useAgentServer(api: HostAppAPI | null): void {
  const storage = useStorageService();    // injected via React context
  const dataService = useDataService();

  useEffect(() => {
    if (!api) return;
    const server = createAgentServer({
      uri: 'tar-planner://planning-server',
      actions: buildAgentActions(storage, dataService),
      resources: buildAgentResources(storage, dataService),
    });
    void registerAgentServer(api, server);
    return () => { void api.unregisterAgentServer('tar-planner://planning-server'); };
  }, [api, storage, dataService]);
}
```

To test `buildAgentActions`, pass mock service implementations and call `handler` directly without mounting the hook.

## Development and production behavior

`connectToHostApp` behaves differently depending on where your app runs:

| **Environment** | **`connectToHostApp` behavior** | **Effect** |
| - | - | - |
| Inside CDF | Resolves with `{ api }` | Full agent integration functionality. |
| Standalone development (`vite dev`) | Rejects | Agent features disabled; hide or disable agent UI triggers. |

Use the following pattern to handle both environments: catch rejections from `connectToHostApp` and disable agent features when your app isn't running inside CDF.

```typescript wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
let api: HostAppAPI | null = null;
try {
  ({ api } = await connectToHostApp({ applicationName: 'my-app' }));
} catch {
  // Not running inside CDF: agent features disabled
}
```

In React, hold `api` in state or context. When the host connection succeeds, your registration effect runs and UI components can show or hide agent triggers.

## Further reading

* [Get started with Flows](/cdf/flows/guides/getting-started)
* [Flows authentication](/cdf/flows/reference/api/auth)
* [About Atlas AI agents](/cdf/atlas_ai/concepts)
* [Atlas AI agent building](/cdf/atlas_ai/guides/atlas_ai_agent_building)
* [Using Atlas AI agents via API and SDK](/cdf/atlas_ai/guides/atlas_ai_agent_api_sdk)
* [CDF SDK documentation](/dev/sdks/)


# Certifying a Flows custom app for production
Source: https://docs.cognite.com/cdf/flows/guides/application-certification

Run the four skill-driven steps that certify a Flows custom app to publish it to a production environment.

**Application certification** authorizes a specific Flows custom app version for a production environment. The application certification signature is required for production publish in addition to your developer signature. The process confirms the app meets the same security, data, and UX standards that builders are trained against in [Builder certification](/cdf/flows/guides/builder-certification), and it applies to every app independently.


  Application certification is required for **every** Flows custom app published to a production CDF project, even when built by a certified builder. Each app version is certified independently, and **every code change** (new feature, bug fix, refactor, dependency bump) requires re-certification before you deploy and publish a new version to production.


## When you need it

| You're publishing to ... | Application certification |
| - | - |
| A **production** project, first publish | **Required** before publish |
| A **production** project, **any code change** (feature, bug fix, refactor, dependency bump) | **Required** before publishing a new version to production |
| A CDF project with [**Dev status**](/cdf/flows/guides/dev-status) | Not required. You still need a developer signature before you publish. See [Code signing](/cdf/flows/guides/code-signing). |

[Request Dev status](/cdf/flows/guides/dev-status) before you publish to a non-production project.

**Prerequisites**:

* Active [Builder certification](/cdf/flows/guides/builder-certification) (valid, not expired).
* Enterprise license to **Cursor**, **Claude Code**, or another agentic coding tool (required to run the certification skills).
* A Flows custom app created with `npx @cognite/cli@latest apps create`.


  **The flow is skill-driven.** Each step is a slash command in your agentic coding tool. The skills generate artifacts in your app's repository, and the final submit skill verifies that every prior artifact exists before packaging the build for submission.


## How the certification flow works


  
    Run `/flows-app-brief` immediately after creating the app, **before** you start building.

    The skill acts as a certification coach: it pre-scans `app.json` and any spec files for context, then asks targeted questions about your user, the problem the app solves, the one-sentence value statement, and how you'll measure success. It writes `App-Brief.md` at the repo root.

    `App-Brief.md` is the user-context document reviewers read first. The final submit skill blocks submission until every required field is populated.
  

  
    Develop your app using the latest Flows template. Follow the [Get started with Flows](/cdf/flows/guides/getting-started) guide for setup.

    Pull skills as you go (`npx @cognite/cli@latest apps skills pull`) so AI coding agents stay aligned with current Cognite best practices.
  

  
    Run `/flows-code-review` to perform the technical review.

    The skill produces three artifacts under `reviews/code-review/feedback-round-N/`:

    * `code-review-report.md` — scored report covering correctness, SDK usage, dependencies, test coverage, dead code, patterns, Data Modeling Service (DMS) query efficiency, pagination, rate limiting, and Aura usage.
    * `review-files.md` — per-file inventory.
    * `review-packages.md` — dependency audit including `npm audit` results.

    The report's `Summary` block reports a `Must Fix open:` count. Re-run the skill (it creates a new `feedback-round-N`) until the count is **0**.
  

  
    Run `/flows-design-review` to score the app against the [10 design quality questions](/cdf/flows/guides/quality-guidelines).

    The skill is semi-automated: for each question it runs concrete repo probes (grep, lint, build) and proposes a draft 1–5 score. You confirm or override each score after walking your tasks end-to-end in the running app. It writes `design-review-report.md` under `reviews/design-review/feedback-round-N/`.

    Target overall average: **3.8 or higher**.
  

  
    Before running this skill, ensure you have run:

    * `npx @cognite/cli@latest apps deploy` — builds the app automatically (`npm run build`) and uploads it, creating the deploy bundle at `.cognite-bundles/-.zip`
    * `npx @cognite/cli@latest apps sign` — signs the bundle and writes `.dev.sig`

    
      Ensure your working tree is clean (`git status` shows nothing uncommitted) before running `apps deploy`. The build runs automatically and the source archive must match the deployed bundle exactly. See [Deploy a Flows custom app](/cdf/flows/guides/deploying) for build options.
    

    Run `/flows-external-app-submit`. The skill verifies five gates before packaging anything:

    | Gate | Required |
    | - | - |
    | `App-Brief.md` complete (required fields: `appName`, `customer`, `tier`, `owner`, `userRole`, `currentProblem`, `oneSentenceStory`, `successCriteria`, `userEvidence`) | Yes |
    | Latest `code-review-report.md` reports `Must Fix open: 0` | Yes |
    | Latest `design-review-report.md` reports `Average score: 3.8` or higher | Yes |
    | No secrets in tracked files (`.env*`, `.pem`, `.key`, `.p12`, etc.) | Blocked |
    | Working tree clean | Blocked |

    On all-pass, the skill runs `npx @cognite/cli@latest apps submit`, which collects the source archive (`src-.zip`) and the deploy bundle into `dist/certification/`, then prompts you to add your screen recording to that folder before opening the pre-filled Zendesk form.
  

  
    Open the [Cognite Zendesk submission form](https://cognite.zendesk.com/hc/en-us/requests/new?ticket_form_id=360001234312\&tf_priority=normal\&tf_subject=App+Review+Request%3A+%5BApp+name%5D\&tf_360015295097=cognite_flows\&tf_description=Dear+Cognite+Platform+Team%2C%3Cbr%3E%3Cbr%3EI+would+like+to+submit+my+Flows+app+for+review+and+certification.%3Cbr%3E%3Cbr%3EApp+name%3A+%5BApp+name%5D%3Cbr%3EApp+external+ID%3A+%5BexternalId%5D%3Cbr%3EVersion%3A+%5BversionTag%5D%3Cbr%3E%3Cbr%3E%60npx+%40cognite%2Fcli+apps+submit%60+verified+App-Brief.md%2C%3Cbr%3Ecode-review-report.md%2C+and+design-review-report.md+are+committed%3Cbr%3Eand+present+in+the+source+archive.%3Cbr%3E%3Cbr%3EAttached%3A%3Cbr%3E%5B+%5D+Source+archive+%28.zip%29+generated+by+%60npx+%40cognite%2Fcli+apps+submit%60%3Cbr%3E%5B+%5D+Screen+recording+of+the+application+%28required+for+design+review%29%3Cbr%3E%3Cbr%3EBest+regards%2C%3Cbr%3E%5BYour+name%5D). The form, subject, description, and **Cognite Flows** product field are pre-filled. Update the placeholders with your app's details.

    Place your screen recording in `dist/certification/` (the CLI prompts you to do this), then attach all files from that folder:

    * **`src-.zip`** — source archive (committed code only; `design-review-report.md` is included inside)
    * **`-.zip`** — deploy bundle; required for signature verification
    * **Screen recording** of the application walking through the primary tasks (required for the design review)

    Submit the ticket. Your submission is reviewed manually.
  

  
    You'll receive one of two outcomes from the Zendesk review:

    * **Feedback:** Address reviewer comments, re-run the relevant skills, commit the updated artifacts, and reply in the same Zendesk ticket with a fresh `dist/certification/` folder (new `src-.zip`, deploy bundle, and updated screen recording if the UI changed).
    * **Approval:** Download the `.cert.sig` from the [Yopass](https://yopass.se/) link in the ticket. Place it alongside your `.dev.sig` file, run `npx @cognite/cli@latest apps publish`, then `npx @cognite/cli@latest apps activate`.

    
      No committed SLA at launch. Reviews are first-in, first-out as the team scales the process.
    
  


## App tiers

The App Brief asks you to pick a tier so reviewers can calibrate expectations. Pick the closest match; "not sure" is fine, and the reviewer can adjust.

| Tier | Scope | Examples |
| - | - | - |
| **Tier 1: Monitoring & reporting** | Read-only dashboards, asset/equipment overviews, KPI reports | Asset health dashboard, production KPI overview |
| **Tier 2: Operational support** | Interactive workflows that support an operator's day, typically single user group | Work-order triage, data validation, shift handover |
| **Tier 3: Business critical** | Multi-step workflows, multiple roles, write-back into systems of record | Approval workflows, multi-user collaboration with state changes |

## Submission requirements

| Item | Source |
| - | - |
| Source archive `src-.zip` | `dist/certification/` — created by `npx @cognite/cli@latest apps submit` |
| Deploy bundle `-.zip` | `dist/certification/` — copied from `.cognite-bundles/` by `apps submit`; must match the signed hash |
| Screen recording of the application | `dist/certification/` — placed there by the builder; should cover the primary user tasks named in `App-Brief.md` |
| `App-Brief.md` (inside `src-.zip`) | Generated by `/flows-app-brief` |
| Latest `code-review-report.md` (inside `src-.zip`) | Generated by `/flows-code-review` |
| Latest `design-review-report.md` (inside `src-.zip`) | Generated by `/flows-design-review` |

## Self-check before submitting

Run this checklist immediately before you open the Zendesk ticket:

* [ ] The app is targeting a **production** project without [Dev status](/cdf/flows/guides/dev-status) (skip certification for Dev status projects).
* [ ] `App-Brief.md` exists at the repo root and every required field is populated.
* [ ] The latest `reviews/code-review/feedback-round-N/code-review-report.md` reports `Must Fix open: 0`.
* [ ] The latest `reviews/design-review/feedback-round-N/design-review-report.md` reports `Average score:` of **3.8** or higher.
* [ ] All skill-generated artifacts (`App-Brief.md` and the latest `reviews/` reports) are committed to git (`git add` + `git commit`); the submit skill packages only committed files.
* [ ] `npx @cognite/cli@latest apps deploy` has been run; deploy bundle exists at `.cognite-bundles/`.
* [ ] `npx @cognite/cli@latest apps sign` has been run; `.dev.sig` exists.
* [ ] `/flows-external-app-submit` ran and printed PASS for every gate.
* [ ] Screen recording of the app's primary tasks has been placed in `dist/certification/`.
* [ ] All files in `dist/certification/` (`src-.zip`, deploy bundle, screen recording) are ready to attach.


  If every box is ticked, the submission is ready. Submit through the [Cognite Zendesk submission form](https://cognite.zendesk.com/hc/en-us/requests/new?ticket_form_id=360001234312\&tf_priority=normal\&tf_subject=App+Review+Request%3A+%5BApp+name%5D\&tf_360015295097=cognite_flows\&tf_description=Dear+Cognite+Platform+Team%2C%3Cbr%3E%3Cbr%3EI+would+like+to+submit+my+Flows+app+for+review+and+certification.%3Cbr%3E%3Cbr%3EApp+name%3A+%5BApp+name%5D%3Cbr%3EApp+external+ID%3A+%5BexternalId%5D%3Cbr%3EVersion%3A+%5BversionTag%5D%3Cbr%3E%3Cbr%3E%60npx+%40cognite%2Fcli+apps+submit%60+verified+App-Brief.md%2C%3Cbr%3Ecode-review-report.md%2C+and+design-review-report.md+are+committed%3Cbr%3Eand+present+in+the+source+archive.%3Cbr%3E%3Cbr%3EAttached%3A%3Cbr%3E%5B+%5D+Source+archive+%28.zip%29+generated+by+%60npx+%40cognite%2Fcli+apps+submit%60%3Cbr%3E%5B+%5D+Screen+recording+of+the+application+%28required+for+design+review%29%3Cbr%3E%3Cbr%3EBest+regards%2C%3Cbr%3E%5BYour+name%5D).


## Troubleshooting common issues


  
    Open the latest `reviews/code-review/feedback-round-N/code-review-report.md` and work the `Must Fix` section top to bottom. Re-run `/flows-code-review` after each batch of fixes; it creates a new feedback round so reviewers can see your progression. Submission stays blocked until the most recent round reports `Must Fix open: 0`.
  

  
    The skill proposes scores from repo probes and your walkthrough notes; you can override any score it gets wrong. Re-run `/flows-design-review` in a new feedback round, override the scores you disagree with, and add an `Improvement note` explaining the reasoning so reviewers can follow your thinking.
  

  
    Any CDF project that does **not** have [Dev status](/cdf/flows/guides/dev-status) and is used for production decisions, dashboards, or workflows. Typically the project with `production` (or similar) in the name. If you're unsure, ask the project's CDF administrator. When in doubt, certify, or [request Dev status](/cdf/flows/guides/dev-status) for non-production projects.
  

  
    No. The design review needs to see the app in motion across your primary user tasks. A short walkthrough (2–5 minutes) is enough; narration is optional but helpful.
  

  
    Yes. Application certification is **per-version** and applies to every code change (new feature, bug fix, refactor, or dependency bump). Re-run the four skills against the new version and submit a fresh zip referencing the new commit hash before you republish to production.
  

  
    Yes. Certification is per-commit, not per-change-size. The re-run is fast when nothing meaningful has changed (the code-review and design-review skills produce reports quickly against a known-good codebase), so the friction is small. The guarantee that production only ever runs certified code is what matters.
  

  
    Make the fixes, re-run `/flows-code-review` and `/flows-design-review` (each in a new feedback round), then re-run `/flows-external-app-submit` to produce a fresh zip. Open a new Zendesk ticket and note in the description that this is a re-certification, referencing the original ticket number.
  


## Further reading

* [Builder certification](/cdf/flows/guides/builder-certification) — Certify yourself before you certify an app.
* [Dev status](/cdf/flows/guides/dev-status) — Skip application certification on non-production projects.
* [Quality guidelines](/cdf/flows/guides/quality-guidelines) — The 10 design quality questions the design review skill scores against.
* [Skills](/cdf/flows/concepts/skills) — How skills are delivered and refreshed in your app.
* [Get started with Flows](/cdf/flows/guides/getting-started) — Scaffold a new app.


# Becoming a certified Flows custom apps builder
Source: https://docs.cognite.com/cdf/flows/guides/builder-certification

Learn how to complete the builder certification to develop and deploy Flows custom apps.

**Builder certification** qualifies a developer (internal, partner, or customer) to build production-ready Flows custom apps in customer **Cognite Data Fusion (CDF)** projects, including non-production projects. It confirms you've met security, data, and UX standards before working on customer projects.


  Builder certification authorizes you as a builder. Each app you publish to a production CDF project still needs [application certification](/cdf/flows/guides/application-certification).


## Certification scope and validity

* **Who it covers**: Individual builders (internal, partner, or customer) who complete the Flows custom apps training path.
* **What it covers**: Authorization to build Flows custom apps in customer CDF projects.
* **Validity**: Six months from the date you claim the certificate.

## Prerequisites

**Flows custom apps** is a pro-code product: you write and maintain the application code. Before you start, confirm that you have:

* Proficiency with an agentic coding tool. [Cursor](https://cursor.com/) or [Claude Code](https://www.anthropic.com/claude-code) is strongly preferred.
* Access to a CDF project where you can build. A development or test project is fine.
* Working familiarity with CDF, the Cognite JavaScript Software Development Kit (SDK), and CDF data modeling concepts.

See [Getting started with Flows custom apps](/cdf/flows/guides/getting-started) for project setup.

## Completing the certification path

Internal, partner, and customer builders follow the same path:

1. Complete [Cognite Flows Foundation](https://hub.cognite.com/p/cognite-flows).
2. Attend a one-day hands-on workshop.
3. Claim the Cognite Flows builder certificate.
4. Generate and register a signing key.


  
    Before the enablement session, finish:

    * The [Cognite Flows Foundation](https://hub.cognite.com/p/cognite-flows) course.
    * The persona-matched upskilling material your Cognite representative sends you (depending on whether you're a solution architect, app developer, dashboard creator, platform owner, or operational subject matter expert (SME)).
  

  
    Join the on-site Flows enablement session. The session facilitator reviews the theory at the start. Then you build against live CDF data on real use cases, using the certification skills (`/flows-app-brief`, `/flows-code-review`, `/flows-design-review`) end to end.

    
      Start with `/flows-app-brief` after you create the app with `npx @cognite/cli@latest apps create`. It produces `App-Brief.md`, which [application certification](/cdf/flows/guides/application-certification) requires later.
    
  

  
    Once you've completed the hands-on workshop, claim your certificate and digital badge.

    
      After you claim the certificate, you're a certified Flows custom apps builder for six months.
    
  

  
    After you claim the certificate, generate a signing key and register the public key with Cognite. You need this key to publish apps. The private key never leaves your machine.

    Follow [Generate and register a signing key](/cdf/flows/guides/code-signing#generate-and-register-a-signing-key). Cognite support checks your **Cognite Flows Foundation** completion and the hands-on workshop before adding your public key. When the key is in the registry, use [Upload, sign, and publish the app](/cdf/flows/guides/code-signing#upload-sign-and-publish-the-app) to publish each version.
  


## Recertification

To maintain active status, recertify before your six-month certification expires. Recertification is self-serve: retake the latest Academy course and refresh your hands-on work against the current Flows custom apps template and skills.

## Troubleshooting common issues


  
    No, attendance alone isn't enough. Finish the Academy pre-work and the hands-on building, then claim your certificate. You're a certified builder when you claim the certificate.
  

  
    For initial certification, no. Internal, partner, and customer builders go through the Flows enablement session as the single supported path. **Recertification** is self-serve once your initial certification is in place.
  

  
    No. The app you build during the enablement session must operate against live CDF data so the certification skills produce meaningful reports and the session facilitator can assess your work properly.
  

  
    No. Builder certification authorizes you to build Flows custom apps in production environments. Each app you publish to a **production** project still needs [application certification](/cdf/flows/guides/application-certification) so Cognite can issue the app certification signature (`.cert.sig`). Projects with [Dev status](/cdf/flows/guides/dev-status) skip this signature, but you must still add a developer signature before you publish. See [Signatures required to publish](/cdf/flows/guides/code-signing#signatures-required-to-publish).
  

  
    Recertify by retaking the latest Academy course and refreshing your hands-on work. Contact your Cognite representative if you've been out of practice for an extended period and want a refresher session.
  


## Further reading

* [Application certification](/cdf/flows/guides/application-certification) — Required for every Flows custom app published to a production project.
* [Dev status](/cdf/flows/guides/dev-status) — Request Dev status to publish builder-signed apps on a non-production project without application certification.
* [Code signing](/cdf/flows/guides/code-signing) — Sign bundles with a developer signature.
* [Flows custom apps quality guidelines](/cdf/flows/guides/quality-guidelines) — The 10 design quality questions the design review skill scores against.
* [Builder skills](/cdf/flows/concepts/skills) — How the certification skills are delivered and refreshed.
* [Getting started with Flows custom apps](/cdf/flows/guides/getting-started) — Scaffold a new app and set up your project.
* [Building Flows custom applications](/cdf/flows) — Template capabilities and tooling overview.


# Signing Flows custom apps from the CLI
Source: https://docs.cognite.com/cdf/flows/guides/code-signing

Step-by-step guide to generate signing keys, sign Flows custom app bundles, and publish signed deployments with the Cognite CLI.

Signing a Flows custom app proves who built the bundle and binds the signature to the exact bytes deployed. The platform rejects the version if anything in the bundle changes after signing, or if the signing key isn't registered.

This guide has two parts. First, generate and register a signing key. Then upload, sign, and publish each version of the app.

Use this guide if you're a certified Flows builder and you publish custom apps with the Cognite CLI.

## Signatures required to publish

Every publish needs a **developer signature**. Projects with [**Dev status**](/cdf/flows/guides/dev-status) need only that signature. Production **Cognite Data Fusion (CDF)** projects without Dev status need **both** that signature and Cognite's **app certification signature** (`.cert.sig`) from [Application certification](/cdf/flows/guides/application-certification). Each signature is tied to the exact bundle bytes. This guide covers the developer signature only.

| Signature | What it proves |
| - | - |
| Developer signature | A certified developer built this bundle for this CDF project. |
| App certification signature | Cognite has reviewed and approved this production bundle. |

[Request Dev status](/cdf/flows/guides/dev-status) before you publish to a non-production project.

## Prerequisites

* The latest Cognite CLI (`npx @cognite/cli@latest`).
* A Flows custom app with `app.json` (with `infra` set to `appsApi`).
* Access to the CDF project you'll deploy to.
* [Builder certification](/cdf/flows/guides/builder-certification), or signing instructions from the team reviewing your app.
* [Application certification](/cdf/flows/guides/application-certification) if you're publishing to a production project and need Cognite's `.cert.sig`.


  A developer signature is not the same as [application certification](/cdf/flows/guides/application-certification). Production apps still need Cognite's application certification signature before they can be published to production projects.


## Generate and register a signing key

Do this after you claim the [builder certificate](/cdf/flows/guides/builder-certification). Every publish needs a developer signature from a key that Cognite has registered. Generate a signing key and submit the Zendesk URL that the CLI prints. You need one registered key to publish apps to any CDF project.


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

    When prompted for a key ID (`kid`), give the key a short name for this machine, such as `juno-laptop`. The key expires in **12 months**. On macOS, the private key goes in **Keychain** (a password prompt is expected). On Windows, it goes in **Credential Manager**. Don't email the `.pub.pem` file. The Zendesk URL already includes the public key.

    These flags change how the CLI collects the name and how you get the Zendesk URL.

    | Flag | What it does |
    | - | - |
    | `--interactive` | Prompts you to **Open in browser** or **Copy link**. Opens a pre-filled Zendesk form. Does not submit the form. |
    | `--copy-link` | Copies the Zendesk URL with no prompt. |
    | `--kid` | Sets the key ID. Use a short name for this machine. |
    | `--email` | Sets the email address on the Zendesk form. |

    If you pass `--kid` and `--email` together, the CLI skips prompts and prints the URL plus a YAML block. Use the URL. Don't paste YAML into a blank ticket.

    
      The private key stays on your machine. Don't share it, commit it, export it from Keychain, or send it to Cognite.
    
  

  
    Submit the Zendesk form from the URL that `keys generate` printed. Don't paste YAML into a blank ticket.

    Support checks that you completed **Cognite Flows Foundation** and the **hands-on workshop**, then replies when they add the key. New keys become available on weekdays during business hours in Central European Time (CET). Until then, `apps status` can show `KEY_NOT_IN_REGISTRY`. If **publish** fails with a 403 that mentions CDF capabilities, that message is generic. It is not an access problem. See [403: signing key is not in the public key registry](#403-signing-key-is-not-in-the-public-key-registry).
  



  When support has added the key and it is available, you can publish apps with a developer signature.


## Upload, sign, and publish the app

After your public key is registered, use these steps to upload, sign, and publish each version of the app.


  
    From your app folder:

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

    `apps deploy` packages `dist/`, uploads it as a DRAFT, and keeps a copy of the exact bytes at `.cognite-bundles/-.zip` so signing operates on what the platform actually received. The app scaffold gitignores `.cognite-bundles/`. Don't commit bundle files from that folder.
  

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

    With no arguments, `apps sign` uses `externalId` and `versionTag` from `app.json`. It finds the matching `.cognite-bundles/-.zip`, writes `.dev.sig` next to it, and submits the signature to the platform. Override with `--signing-identity `, `--scope /`, or an explicit bundle path.

    Run `apps status` to verify the signature was accepted before you publish.

    
      Commit before signing so the source-to-signature link stays auditable. Tag the commit with the app version:

      ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
      git tag "v$(jq -r .versionTag app.json)" -m "Signed deployment"
      git push origin --tags
      ```
    
  

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

    `apps publish` transitions the version from DRAFT to PUBLISHED. Signatures were already submitted by `apps sign`; publish re-submits any local `.dev.sig` (and `.cert.sig` if present) as a safety net, then flips the lifecycle state.
  

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

    The command shows the lifecycle state and every signature the platform has on record for the current version. Each entry includes the signing identity (`kid`), the role (`developer` or `certifier`), the time the signature was issued, and the platform's verdict.

    You'll see one of three shapes depending on where you are in the flow:

    Before `apps deploy`:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    Status:  not deployed yet

    Run `npx @cognite/cli apps deploy` to upload this version.
    ```

    After `apps deploy`, before `apps sign` + `apps publish`:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    Status:  DRAFT

    Signatures: none stored

    Run `npx @cognite/cli apps publish .` to publish this version.
    ```

    After a clean publish:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    App:     Sign Test App (sign-test-app)
    Version: 0.0.3  (local)
    Status:  PUBLISHED

    Signatures:
      acme-dev-001    (developer, signed 2026-05-27T13:22:37.000Z) — VALID
      cognite-cert-1  (certifier, signed 2026-05-27T13:25:10.000Z) — VALID
    ```

    A verdict other than `VALID` means the platform won't accept that signature for serve-time verification. The verdict table explains each result and what to do.

    | Verdict | What it means | What to do |
    | - | - | - |
    | `VALID` | Signature verifies and the key is in the registry and in date. | Nothing — this is the expected state. |
    | `REVOKED` | The signing key has been revoked since the signature was submitted. | Re-sign with a current key, then publish a new version. |
    | `EXPIRED` | The signing key was in date when signed, but has since expired. | Rotate the key (see [Rotate or replace a key](#rotate-or-replace-a-key)) and re-sign. |
    | `SIGNED_BEFORE_KEY_ISSUED` | The signature's `iat` timestamp predates the key's registration. Clock skew, or a stale key. | Re-sign with the current system clock. If the clock is correct, contact Cognite. |
    | `IAT_IN_FUTURE` | The signature's `iat` timestamp is in the future. Usually clock skew on the signing machine. | Fix the signing machine's clock, then re-sign and re-publish. |
    | `BUNDLE_TOO_OLD` | The bundle's signature is older than the platform's minimum-age policy. | Re-sign the current bundle and re-publish. |
    | `KEY_NOT_IN_REGISTRY` | The `kid` isn't in the public key registry, or isn't available yet. | Confirm the `kid` with `keys list`. Wait until the key is available on a weekday during business hours, Central European Time. See [403: signing key is not in the public key registry](#403-signing-key-is-not-in-the-public-key-registry). |

    
      Verify the version is **PUBLISHED** and your developer signature appears as `VALID` for the expected `kid`. Anything else needs action before the version will serve.
    
  


## Production certification (Cognite signature)

Production CDF projects without [Dev status](/cdf/flows/guides/dev-status) need both a developer signature and an app certification signature. The two signatures are independent. Cognite signs the same bundle bytes with their own key and returns the signature to you. Complete the [Upload, sign, and publish the app](#upload-sign-and-publish-the-app) steps through **Sign the bundle**, then add these steps before you publish the application:


  
    From your app folder, on a clean commit:

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

    `apps submit` packages a source archive (`src-.zip`), copies the deploy bundle into `dist/submit/`, and opens a pre-filled Zendesk request with the app metadata. Attach everything in `dist/submit/` plus a screen recording of the app, then submit.

    
      The command will fail if your working tree has uncommitted changes — the source archive has to match the committed code exactly. Commit first, then re-run.
    
  

  
    After Cognite reviews and approves the bundle, your Zendesk contact replies with a `.cert.sig` file. Save it to your app's `.cognite-bundles/` folder next to the deploy bundle, named `-.cert.sig`.

    For example, for app `sign-test-app` version `0.0.3`:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    .cognite-bundles/
      sign-test-app-0.0.3.zip          ← created by apps deploy
      sign-test-app-0.0.3.zip.dev.sig  ← created by apps sign
      sign-test-app-0.0.3.zip.cert.sig ← from Cognite, save here
    ```

    To open `.cognite-bundles/` in your file manager from the app folder:

    
      
        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        open .cognite-bundles
        ```
      

      
        ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        explorer .cognite-bundles
        ```
      

      
        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        xdg-open .cognite-bundles
        ```
      
    

    Don't commit `.cert.sig` to git. The scaffold gitignores `.cognite-bundles/` for this reason.
  

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

    `apps publish` picks up both `.dev.sig` and `.cert.sig`, submits the certifier signature, and transitions the version to PUBLISHED.

    Run `apps status .` to confirm both signatures show as `VALID`.
  


## Sign again when the bundle changes

The signature is bound to the exact bytes of the bundle. Anything that changes the bundle invalidates the signature:

* Re-running `npm run build`
* Editing files in `dist/` or `manifest.json`
* Bumping the app version

Re-run `apps deploy`, `apps sign`, and `apps publish` in order. `deploy` overwrites the bundle file at the same path, so the next `sign` picks up the new bytes automatically.

## Rotate or replace a key

Generate a new key when the old one expires, you move to a new machine, or you suspect the private key is compromised:

1. `npx @cognite/cli@latest keys generate --interactive`.
2. Register the new public key.
3. Sign new bundles with the new key.
4. Ask your Cognite contact to revoke the old key if needed.

Previously published apps stay published. Rotating your local key doesn't invalidate signatures already accepted by the platform.

## Troubleshooting


  
    Run `npx @cognite/cli@latest keys generate --interactive`, then retry the signing command.
  

  
    The bytes you signed don't match what the platform received. Run these commands in order:

    1. `npx @cognite/cli@latest apps deploy` — refreshes `.cognite-bundles/-.zip` with the bytes the platform has.
    2. `npx @cognite/cli@latest apps sign` — signs the refreshed bundle.
    3. `npx @cognite/cli@latest apps publish .` — submits the new signature.

    Don't manually repackage the bundle.
  

  
    `apps sign` stores the signature even if the key isn't in the registry yet. Wait until the key is available on a weekday during business hours, Central European Time. Don't sign or publish again while you wait. `apps status` flips to `VALID` on its own. If **publish** returned 403, see [403: signing key is not in the public key registry](#403-signing-key-is-not-in-the-public-key-registry) and run `apps publish` again after the key is available.
  

  
    If **publish** fails with:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    signature (role=developer, kid=jsmith-dev-001): signing key used to create the signature is not in the public key registry. | code: 403 | X-Request-ID: ...
      You don't have the required CDF capabilities. Please contact your CDF admin.
    ```

    The first line is the cause: that `kid` isn't in the public key registry. The second sentence is a generic message the CLI shows for any 403. It is not an access problem. Don't contact your CDF administrator for this error.

    Either you signed with a **different local key** than the one you registered, or the registered key **is not available yet**. Run `npx @cognite/cli@latest keys list`. If you signed with the wrong key, sign again with `--signing-identity ` and publish again. If you used the registered key, wait until the key is available on a weekday during business hours, Central European Time (CET), then run `apps publish` again. You don't need to sign again.

    If the error continues during business hours, Central European Time, contact Cognite support.
  

  
    The signature timestamp doesn't line up with the key's registration window. Almost always clock skew on the signing machine. Make sure your system clock is correct, then re-run `apps sign` and `apps publish`.
  

  
    You're targeting a production project that requires both a developer and an app certification signature. Follow [Production certification](#production-certification-cognite-signature) to submit for review and add the `.cert.sig` Cognite returns.
  

  
    Run `npx @cognite/cli@latest keys list`, find the correct `kid`, and pass it with `--signing-identity `.
  

  
    Generate a new key on the replacement machine and register the public key. Ask your Cognite contact to revoke the old key if it may be compromised.
  


## Related topics

* [Becoming a certified Flows custom apps builder](/cdf/flows/guides/builder-certification)
* [Certifying a Flows custom app for production](/cdf/flows/guides/application-certification)
* [Deploying Flows custom apps](/cdf/flows/guides/deploying)
* [Dev status](/cdf/flows/guides/dev-status)
* [Flows custom apps quality guidelines](/cdf/flows/guides/quality-guidelines)


# Deploying Flows custom apps
Source: https://docs.cognite.com/cdf/flows/guides/deploying

Deploy your Flows custom app to Cognite Data Fusion (CDF) with interactive or automated deployment and App Hosting lifecycle commands.

You can deploy your Flows custom app to CDF **interactively** from your machine (browser sign-in, no OAuth secrets in the terminal) or **automate** deployment in CI/CD with client credentials.

## Interactive deployment

The simplest path uses your browser for sign-in—no OAuth configuration in the terminal:

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

This will:

1. Build your app.
2. Open a browser window for you to sign in to CDF.
3. Prompt you to select a deployment target from `app.json`.
4. Package and deploy to your configured project.
5. Show a link to your deployed app.

### Options

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
# Use the first deployment target (skip selection prompt)
npx @cognite/cli@latest apps deploy --interactive -d 0

# Use a specific project by name
npx @cognite/cli@latest apps deploy --interactive -d your-project-name

# Skip the build step (if already built)
npx @cognite/cli@latest apps deploy --interactive --skip-build
```

### Draft and published versions

`apps deploy` uploads your app as a `DRAFT` version. To publish and activate it, see [How a version reaches Custom apps](/cdf/flows/concepts/app-lifecycle#how-a-version-reaches-custom-apps).


  `--published` flag is used for legacy apps:

  | Scenario | Behavior |
  | - | - |
  | Legacy app, `--published` flag | Honored — deploys as `PUBLISHED` |
  | App Hosting app, `--published` flag | Warning printed, flag ignored — always deploys as `DRAFT`. Use `apps publish .` / `apps activate .` instead |

  For App Hosting apps, use `npx @cognite/cli@latest apps publish .` and `npx @cognite/cli@latest apps activate .` to control visibility.


## App Hosting lifecycle commands

For apps using App Hosting infrastructure (`"infra": "appsApi"` in `app.json`), use the following commands to manage the version lifecycle after deployment. Each version progresses through the states: `DRAFT` → `PUBLISHED` → `ACTIVE`.

### Check status

Print the current deployment status of your app version:

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

### Publish a version

Transition the current version from `DRAFT` to `PUBLISHED` (visible but not yet the `ACTIVE` version):

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

This command is idempotent — re-running on an already `PUBLISHED` or `ACTIVE` version is a no-op.


  Publishing **requires a developer signature**, including on projects with [Dev status](/cdf/flows/guides/dev-status). Production projects without Dev status need **both** that signature and Cognite's app certification signature (`.cert.sig`) from [application certification](/cdf/flows/guides/application-certification). See [Code signing](/cdf/flows/guides/code-signing).


### Activate a version

Set the current version as `ACTIVE` (the version users see). Publish the version if it's still `DRAFT`:

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

If a previous version was `ACTIVE`, the output reports which version it replaced.


  Use `--interactive` to authenticate via browser sign-in when running these commands from your machine:

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


## Automated deployment (CI/CD)

For CI/CD pipelines, configure client credentials.

### Prerequisites

1. **OAuth client** — A client ID registered in your CDF project.
2. **Client secret** — The secret for that client.
3. **Capabilities** — The `apphosting:read` and `apphosting:write` capabilities granted to the client via a group. These capabilities can be scoped to the app's `externalId` from `app.json`. Add `apphosting:run` if the same client also needs to run the app. See [Assign capabilities](/cdf/access/guides/capabilities#flows-custom-apps).

Ask your Cognite administrator to register an OAuth client with the required permissions.

### Step 1: Configure app.json

Add `deployClientId` and `deploySecretName` to your deployment configuration:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "name": "My App",
  "description": "My awesome Flows app",
  "externalId": "my-app",
  "versionTag": "1.0.0",
  "deployments": [
    {
      "org": "my-org",
      "project": "my-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "your-client-id",
      "deploySecretName": "MY_APP_SECRET"
    }
  ]
}
```

| Field | Description |
| - | - |
| `name` | Display name in CDF |
| `externalId` | Unique identifier (kebab-case) |
| `versionTag` | Semantic version |
| `deployClientId` | OAuth client ID |
| `deploySecretName` | Environment variable name for the secret |
| `idpType` | Identity provider (`cdf` or `entra_id`). Defaults to `cdf` |
| `tenantId` | Microsoft Entra tenant ID (required when `idpType` is `entra_id`) |
| `published` | Legacy field: whether the app is visible to end users. Prefer `apps publish` / `apps activate` for App Hosting apps. |

#### Microsoft Entra ID deployment

Set `idpType` to `entra_id` and provide `tenantId`:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "deployments": [
    {
      "org": "my-org",
      "project": "my-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "your-entra-client-id",
      "deploySecretName": "MY_APP_SECRET",
      "idpType": "entra_id",
      "tenantId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
```

When `idpType` is `entra_id`, Flows requests a token from Microsoft Entra ID and derives the CDF scope from `baseUrl` (for example, `https://greenfield.cognitedata.com/.default`).

### Step 2: Set the secret

Export the client secret:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
export MY_APP_SECRET="your-client-secret"
```


  In CI/CD, store secrets in your platform’s secret manager (for example, GitHub Actions repository secrets, Azure DevOps variable groups, or GitLab CI variables).


### Step 3: Deploy

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

This will:

1. Build your app (`tsc && vite build`).
2. Package `dist/` into a zip.
3. Authenticate with client credentials.
4. Upload through the CDF Files API.
5. Make the app available in CDF.

### Preview deployments

For pull request previews:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
npm run deploy-preview
```

### Multiple environments

Add multiple entries to `deployments`:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "deployments": [
    {
      "org": "your-org",
      "project": "dev-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "dev-client-id",
      "deploySecretName": "DEV_SECRET"
    },
    {
      "org": "your-org",
      "project": "prod-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "prod-client-id",
      "deploySecretName": "PROD_SECRET"
    }
  ]
}
```

## Versioning

Update `versionTag` in `app.json` for each release:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "versionTag": "1.2.0"
}
```

### Roll back to a published version

Each version is stored in CDF. To point **Custom apps** at an earlier published, Cognite-certified version, set `versionTag` in `app.json` to that version, then run:

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


  Do not run `apps deploy` against that `versionTag`. Published versions cannot be overwritten.


See [New versions and rollback](/cdf/flows/concepts/app-lifecycle#new-versions-and-rollback) for when to roll back versus recertify.

## Troubleshooting

### What permissions do I need to deploy?

Your OAuth client (for CI/CD) or user account (for interactive deployment) needs `apphosting:read` and `apphosting:write`. You can scope these capabilities to the app's `externalId` from `app.json`. Add `apphosting:run` if the same principal also needs to run the app. See [Assign capabilities](/cdf/access/guides/capabilities#flows-custom-apps).

### "Deployment secret not found"

Ensure the environment variable name matches `deploySecretName`:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
export MY_APP_SECRET="your-secret"
```

### "Failed to authenticate"

Check that:

* The client ID is correct.
* The client secret is valid and not expired.
* The client has the required CDF permissions (including Files API write access).

### Build fails

Run the build locally:

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

### Interactive sign-in issues

1. Confirm you have access to the CDF project.
2. Ensure pop-ups are not blocked.
3. Try `npx @cognite/cli@latest apps deploy --interactive --org your-org` as a hint.

## Further reading

* [Get started with Flows](/cdf/flows/guides/getting-started) — Create an app and first deploy.
* [Run your app locally](/cdf/flows/guides/running-locally) — Dev server, HTTPS, and troubleshooting.
* [App lifecycle](/cdf/flows/concepts/app-lifecycle) — Draft, published, and active versions.
* [Code signing](/cdf/flows/guides/code-signing) — Sign bundles with a developer signature.
* [Dev status](/cdf/flows/guides/dev-status) — Skip application certification on non-production projects.
* [Auth API](/cdf/flows/reference/api/auth) — Tokens and SDK usage related to deployment identities.


# Requesting Dev status for a CDF project
Source: https://docs.cognite.com/cdf/flows/guides/dev-status

Learn how to request Dev status for a non-production Cognite Data Fusion (CDF) project so you can publish builder-signed custom apps without application certification.

Use this procedure to share a prototype application on a **test, dev, or staging** Cognite Data Fusion (CDF) project without [application certification](/cdf/flows/guides/application-certification). Dev status moves app security responsibility to the certified builder and the CDF project owner.


  Dev status transfers risk ownership for app security to the **certified builder** and the **CDF project owner**. Cognite does not run application certification on those applications. The builder and project owner own the checks Cognite normally performs, including the `/flows-code-review` skill, dependency / CVE follow-up (`review-packages.md` / `npm audit`), and not shipping known-bad or malicious code. Do not request Dev status for a production project.


## Prerequisites

* Only a **CDF project owner** can submit this request. If you are not the owner, ask them to submit it.
* The target project is **test, dev, or staging**. Cognite does not grant Dev status for production projects.
* [Builder certification](/cdf/flows/guides/builder-certification) and a developer signature are required to publish after Cognite grants Dev status. See [Code signing](/cdf/flows/guides/code-signing).

On a project with Dev status:

* You still add a **developer signature** with `apps sign`. See [Code signing](/cdf/flows/guides/code-signing).
* You can publish a builder-signed app. Cognite's **app certification signature** (`.cert.sig`) is not required, and CDF does not show the 14-day production warning.
* Only the version owner can open an unsigned version. A builder-signed draft is shareable. See [App lifecycle](/cdf/flows/concepts/app-lifecycle).

## Request Dev status

[Zendesk](https://cognite.zendesk.com) is Cognite's support-request site. Select the **Request Dev status for a CDF project** card to open a pre-filled form. Edit the form if needed, and then select **Submit**. If you can't sign in, ask your Cognite representative for a Zendesk login.


  Opens a pre-filled Zendesk request.


## After Cognite grants Dev status


  
    Follow [Code signing](/cdf/flows/guides/code-signing) for the developer signature.
  

  
    Follow [Deploying Flows custom apps](/cdf/flows/guides/deploying) and [App lifecycle](/cdf/flows/concepts/app-lifecycle). **Publish** locks the version. **Activate** makes the app show up on **Custom apps**, or replaces the previously active version.
  


## Further reading

* [Application certification](/cdf/flows/guides/application-certification) — The default path you are opting out of.
* [Builder certification](/cdf/flows/guides/builder-certification) — Qualify to build Flows custom apps in customer environments.
* [Code signing](/cdf/flows/guides/code-signing) — Sign bundles with a developer signature.
* [Deploying Flows custom apps](/cdf/flows/guides/deploying) — Interactive and CI/CD deployment, lifecycle commands, and rollback.


# Getting started with Flows custom apps
Source: https://docs.cognite.com/cdf/flows/guides/getting-started

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:

* **Latest supported Node.js and npm versions.** The npm version that is installed with Node.js is sufficient.
* **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.


  **Certification for customer environments**: To publish to a **production** project, you need both a developer signature and Cognite's app certification signature. On a **non-production** project, a [certified builder](/cdf/flows/guides/builder-certification) can publish with a developer signature alone if the project has Dev status. Cognite does not grant Dev status for production projects. [Request Dev status](/cdf/flows/guides/dev-status) before you publish to a non-production project. See [Code signing](/cdf/flows/guides/code-signing).


## Set up your environment

### Install Node.js

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


  ```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 a currently supported Node.js release:
  nvm install --lts
  ```

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

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


#### Verify installation

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
node --version
npm --version
```

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


  
    Use nvm or Homebrew.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    nvm install --lts
    nvm use --lts
    # OR if using Homebrew:
    brew upgrade node
    ```
  

  
    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@latest
    ```
  


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


  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](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


  
    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 .
    ```

    
      This command is the same on Linux, macOS, and Windows. If `npx` prompts you to install the package or doesn't run, use `npm exec --yes -- @cognite/cli@latest apps create`. After a global install (`npm install -g @cognite/cli@latest`), you can also run `cognite apps create`.
    
  

  
    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`. |

    
      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.
    
  

  
    If you plan to publish this app to a **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.

    
      Skip this step for projects with [Dev status](/cdf/flows/guides/dev-status). Cognite's app certification signature isn't required on those projects, but you still need a developer signature before you publish. See [Code signing](/cdf/flows/guides/code-signing).
    
  

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

    
      
        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        cursor my-analytics-app
        ```
      

      
        ```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.
      

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

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

    Check `engines` in the generated `package.json` for the versions the current template requires.

    
      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.
    

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

  
    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.
  

  
    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.
    * [Installing Aura](/cdf/aura/guides/installation) — UI framework that ships with the template.
    * [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.

    
      When you start building:

      * **[Aura](/cdf/aura/guides/installation)** — Ensure **[`@cognite/aura`](/cdf/aura/guides/installation)** 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.
    
  

  
    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.
  


## Generated structure

Here is the generated structure of your app:


  
    
      
    

    
      
    

    
      

      

      
        
      

      

      
    

    

    

    

    

    

    

    

    

    

    

    
  


## 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.
* **Aura UI** — The template includes [`@cognite/aura`](/cdf/aura/guides/installation). See the [Aura design system](/cdf/aura) for foundations, primitives, and patterns.
* **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.
* [Aura design system](/cdf/aura) — Foundations, primitives, and patterns for Flows custom app UI.
* [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.
* [Dev status](/cdf/flows/guides/dev-status) — Skip application certification on non-production projects.
* [Auth API](/cdf/flows/reference/api/auth) — `connectToHostApp` and authenticated CDF access.
* [Host App API](/cdf/flows/reference/api/host-app-api) — Navigation, state, sidebar visibility, fullscreen, and agent integration.
* [Content Security Policy](/cdf/flows/reference/api/csp) — Production CSP baseline and how to extend it via `manifest.json`.


# Developing and shipping Flows custom apps
Source: https://docs.cognite.com/cdf/flows/guides/index

Follow Flows custom app guides from first project creation through local development with Vite to deploying React apps inside Cognite Data Fusion (CDF).

Walk through creating a **Flows custom app**, running it locally, and publishing it to CDF in a single guided path. Before you build for customers, review the [quality guidelines](/cdf/flows/guides/quality-guidelines) — they define the standards your app must meet for certification.


  
    Create an app, install dependencies, and run it in CDF.
  

  
    Run specify, clarify, and plan on a real example and end with a reviewable implementation plan.
  

  
    Persist and share app state through URLs with `syncInternalState`.
  

  
    Dev server, HTTPS, CDF iframe, and local configuration.
  

  
    One-time `mkcert` setup, plus a no-admin fallback.
  

  
    Use the App Hosting OAuth relay for an additional Microsoft Entra ID sign-in from within a Flows custom app.
  

  
    Interactive deploy and CI/CD.
  

  
    Engineering and design standards every Flows app must meet.
  

  
    Generate signing keys and sign app bundles from the CLI.
  



# Trusting the local HTTPS certificate for Flows custom apps
Source: https://docs.cognite.com/cdf/flows/guides/local-https

Step-by-step guide to installing a trusted local certificate so your Flows custom app loads without warnings in Cognite Data Fusion (CDF).

This guide is for developers building Flows custom apps. Before you begin, make sure you have a Flows custom app created and dependencies installed. See [Getting started with Flows custom apps](/cdf/flows/guides/getting-started).

`npm run dev` serves your app over HTTPS so CDF can embed it in an iframe. Without a trusted certificate, the browser blocks the embed and shows **Not Secure** or **"the webpage at `https://localhost:3001/` might be having issues"**. You need to establish trust between your browser and the local dev server before CDF can load your app.

You can establish trust in two ways:

* **[Install `mkcert`](#installing-mkcert-recommended)**: One-time setup that works everywhere. Requires admin access.
* **[Accept the certificate in the browser](#accepting-the-certificate-manually-no-admin-required)**: No installation needed, but you must repeat this on every dev server restart.

## Installing mkcert (recommended)


  
    
      
        Run the following command in your terminal:

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

      
        1. Open the **Start** menu, type **Windows PowerShell**.
        2. Right-click **Windows PowerShell** and select **Run as administrator**.
        3. Accept the UAC prompt.
        4. Run the following command:

        ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        choco install mkcert
        ```
      

      
        Run the following command in your terminal:

        ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        scoop bucket add extras
        scoop install mkcert
        ```
      
    

    If you don't have a package manager, download the binary directly from the [mkcert installation guide](https://github.com/FiloSottile/mkcert#installation).
  

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

    This command adds the `mkcert` **Certificate Authority (CA)** to your system trust store and issues a certificate for `localhost`, `local.cognite.ai`, and `*.local.cognite.ai`.
    You must accept the sudo or UAC prompt when it appears.
  

  
    Stop `npm run dev`, restart it, then fully quit and reopen your browser so it re-reads the trust store. The address bar should show the lock icon.
  


## Accepting the certificate manually (no admin required)

If you don't have admin access, manually trust the dev server's self-signed certificate in your browser:


  
    Run the following command in your terminal:

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

    The URL is displayed in the terminal (for example, `https://localhost:3001`).
  

  
    Open a new tab in your browser and paste the URL. The browser shows a privacy warning:

    
      
        Select **Advanced** → **Proceed to localhost (unsafe)**.
      

      
        Select **Advanced…** → **Accept the Risk and Continue**.
      

      
        Select **Show Details** → **visit this website** → **Visit Website**.
      
    

    The new tab will appear blank or show a "The webpage at `https://localhost:3001` might be having issues" message as the app only renders within the CDF iframe, not in a standalone window. You can close this tab.
  

  
    Return to the **CDF** tab and reload. If the iframe doesn't load immediately, reload again and wait a few seconds for the now-trusted session to register.
  



  Install `mkcert` to avoid repeating this step.Without `mkcert`, the dev server generates a new certificate on every start, so the browser warning returns on every restart, port change (for example, `3002` instead of `3001`), or browser switch.


## Troubleshooting


  
    **Symptom**:

    * Running `npx @cognite/cli@latest apps setup-https` fails with `mkcert is not installed`.

    **Cause**:

    * The CLI cannot find `mkcert` on your `PATH`.

    **Resolution**:

    * Install `mkcert` (see [Installing mkcert (recommended)](#installing-mkcert-recommended)), then run the command again.
    * On Windows, run `choco install mkcert` from an elevated PowerShell.
  

  
    **Symptom**:

    * The browser shows **Not Secure** even after `apps setup-https` completed successfully.

    **Cause**:

    * The browser cached the old trust store state and hasn't re-read it yet.

    **Resolution**:

    * Fully quit and reopen the browser.
    * On Windows, close Edge from the system tray, not just the window.
  

  
    **Symptom**:

    * The CLI reports that the `apps setup-https` command doesn't exist.

    **Cause**:

    * Your local version of `@cognite/cli` is older than `1.4.0`, which is when the command was added.

    **Resolution**:

    * Run the command with `@latest` to bypass any pinned version:

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

    * If `@latest` still resolves to a version older than `1.4.0`, delete any `.npmrc` in the current directory that pins a registry or version.
  

  
    **Symptom**:

    * Each `npm run dev` start uses a higher port number.

    **Cause**:

    * An orphaned `node` process from a previous session is still holding the port.

    **Resolution**:

    * Find and stop the process. You can only stop processes you own.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    # macOS / Linux
    lsof -i :3001 # Checks what's running on port 3001
    kill -9  # Stops the process
    ```

    ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    # Windows
    Get-Process -Id (Get-NetTCPConnection -LocalPort 3001).OwningProcess
    Stop-Process -Id  -Force
    ```
  


## Further reading

* [Running Flows custom apps locally](/cdf/flows/guides/running-locally)
* [Sign Flows custom apps from the CLI](/cdf/flows/guides/code-signing)


# Signing in with an additional Microsoft Entra ID account
Source: https://docs.cognite.com/cdf/flows/guides/oauth-relay

Step-by-step guide to using the App Hosting OAuth relay for an additional Microsoft Entra ID sign-in from within a Flows custom app.

Use the App Hosting OAuth relay when your Flows custom app needs an additional sign-in from within the app. For example, pull data from a source authenticated by a different Microsoft Entra ID tenant than Cognite Data Fusion (CDF). [`connectToHostApp`](/cdf/flows/reference/api/auth) returns CDF credentials only, so the user must sign in with a different Microsoft Entra ID account, typically in that other tenant. You can run the flow more than once for multiple additional accounts.

You implement the popup in your app code and decide when it runs. App Hosting serves the relay as a static, unauthenticated page at `/apphosting/oauth-relay` on the app's origin; the path stays the same across versions. The authorization code stays in the browser: it isn't sent to CDF or App Hosting, isn't persisted beyond the browser cache, and may be accessible across sessions.

## Prerequisites

* A [Flows custom app](/cdf/flows/guides/getting-started) that runs inside CDF.
* A Microsoft Entra ID app registration for the other tenant or service, with the [single-page application](#register-the-redirect-uri) platform.
* CDF credentials from [`connectToHostApp`](/cdf/flows/reference/api/auth). Use the relay only for the additional Microsoft Entra ID sign-in, not for CDF.

## How the relay works

1. Your app opens a popup at the Microsoft Entra ID authorize URL with `response_mode=fragment`, so Microsoft Entra ID returns the authorization code in the URL fragment (`#code=...`).

2. Include `prompt=select_account` on that authorization request so Microsoft Entra ID shows the account picker. Without it, Microsoft Entra ID may reuse the CDF account, and the app won't get a token for the other tenant.

3. After sign-in, Microsoft Entra ID redirects the popup to `{app-origin}/apphosting/oauth-relay#code=...&state=...`.

4. The relay posts the fragment to `window.opener` and does not store it:

   ```js theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
   { type: "APPHOSTING_OAUTH_RESPONSE", fragment: window.location.hash }
   ```

   The relay uses `postMessage` to send the fragment to the window that opened the popup (`window.opener`). The `postMessage` target origin is the relay's own origin. If there is no opener, the page does nothing.

5. Your app checks `event.origin`, reads `code` from the fragment, and exchanges it for tokens with PKCE (Proof Key for Code Exchange). You store those tokens and attach them to calls to the other service. See [Store the token and call the other service](#store-the-token-and-call-the-other-service).


  The relay reads `window.location.hash`. If you omit `response_mode=fragment`, the code lands in the query string and the app receives an empty fragment.


## Find the deployed app origin

You need the app origin to register the redirect URI in Microsoft Entra ID. The origin stays the same for every version of the app in a project. For example, the origin is `https://9f446ebf4f46.apps.api.cogniteappsdata.com`. You can copy it from the browser or compute it from the app's `externalId` and `project`.


  
    Open the deployed app in CDF and copy the origin from the address bar. Keep `https://` and the host, and drop everything after the first `/` that follows the host.
  

  
    Assemble `https://.apps..cogniteappsdata.com` from `app.json`. `{cluster}` is the `baseUrl` subdomain (`api` for `https://api.cognitedata.com`). The command prints `{app-hash}`: the first 12 characters of the SHA-256 hash of `externalId`, a null byte, and `project`. Replace `my-app` and `my-project` with your `externalId` and `project`.

    
      
        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        printf 'my-app\0my-project' | shasum -a 256 | cut -c1-12
        ```
      

      
        ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        $sha = [System.Security.Cryptography.SHA256]::Create()
        $bytes = [System.Text.Encoding]::UTF8.GetBytes("my-app" + [char]0 + "my-project")
        (-join ($sha.ComputeHash($bytes) | ForEach-Object { $_.ToString("x2") })).Substring(0, 12)
        ```
      
    
  


Use that origin when registering the redirect URI. The redirect URI is the origin plus `/apphosting/oauth-relay`.

## Register the redirect URI

In the Azure portal, add the redirect URIs to the **Single-page application** platform. Don't use the **Web** platform because it doesn't return the CORS headers required to exchange the code from the iframe.


  
    Go to **Microsoft Entra ID** → **App registrations** → your registration → **Authentication**.
  

  
    Under the **Redirect URI configuration** tab, select **+ Add a platform** or **+ Add Redirect URI**. In the right side panel, select **Single-page application**.
  

  
    Add the redirect URI for local and one for the deployed app. The path is always `/apphosting/oauth-relay`.

    | Environment | Redirect URI |
    | - | - |
    | Local | `https://localhost:3001/apphosting/oauth-relay` |
    | Deployed | `https://.apps..cogniteappsdata.com/apphosting/oauth-relay` |

    Don't register an app asset such as `callback.html` on the deployed origin. App assets require the CDF session cookie, so the popup receives a 401 response and the opener can't read it.
  

  
    After you add the URI, select **Confirm** to update authentication and save the changes.
  


## Serve the relay locally

App Hosting serves `/apphosting/oauth-relay` in production. For local development, serve the same path from the Vite dev server:

```ts wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import type { PluginOption } from "vite";

function oauthRelayDevPlugin(): PluginOption {
  const relayHtml = `

  OAuth relay
  
    Completing sign-in…
    
  
`;
  return {
    name: "oauth-relay-dev",
    configureServer(server) {
      server.middlewares.use("/apphosting/oauth-relay", (_req, res) => {
        res.setHeader("Content-Type", "text/html");
        res.end(relayHtml);
      });
    },
  };
}
```

Add `oauthRelayDevPlugin()` to the `plugins` array in `vite.config.ts`.

## Handle the relay response

The relay posts the fragment to your app with `postMessage`. Handle the `message` event and read the authorization `code` from the fragment. Then POST the code and the PKCE verifier to the Microsoft Entra ID token endpoint to get tokens.

```ts wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
window.addEventListener("message", (event) => {
  if (event.origin !== window.location.origin) return;
  if (event.data?.type !== "APPHOSTING_OAUTH_RESPONSE") return;

  const params = new URLSearchParams(
    String(event.data.fragment).replace(/^#/, "")
  );
  const code = params.get("code");
  // Next: POST code + PKCE verifier to the Microsoft Entra ID token endpoint.
});
```

Allow the identity provider in `manifest.json`. If you call Microsoft Graph (Microsoft's API for user and organization data, for example the `/me` endpoint), also allow `https://graph.microsoft.com`. See [Content Security Policy](/cdf/flows/reference/api/csp).

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": [
          "https://login.microsoftonline.com",
          "https://graph.microsoft.com"
        ],
        "directives": ["connect-src"]
      }
    ]
  }
}
```

## Store the token and call the other service

The relay doesn't store the authorization code or the tokens. After you exchange the code, keep the access token (and refresh token, if returned) in your app, for example, in memory or in `localStorage`. Attach the access token to the requests you send to the other service.

## Refresh the access token

If the token response includes a `refresh_token`, redeem it before the access token expires. Microsoft Entra ID single-page application (SPA) registrations rotate refresh tokens, so replace the stored refresh token after each successful response.

## Further reading

* [Flows Auth API](/cdf/flows/reference/api/auth): Get a CDF token with `connectToHostApp`.
* [Content Security Policy](/cdf/flows/reference/api/csp): Allow `login.microsoftonline.com` in `manifest.json`.
* [Run your app locally](/cdf/flows/guides/running-locally): Use the development server and CDF iframe.


# Flows custom apps quality guidelines
Source: https://docs.cognite.com/cdf/flows/guides/quality-guidelines

Comprehensive quality assessment criteria for Flows custom apps, including design evaluation rubric and engineering standards.

These guidelines define the quality standards that Flows custom apps must meet for certification. They're the rubric the design review step of the [Application certification](/cdf/flows/guides/application-certification) flow scores against.


  If you ran `/flows-design-review`, the skill already proposed scores against this rubric and wrote them to `reviews/design-review/feedback-round-N/design-review-report.md`. Use this page as the authoritative reference when overriding any of the proposed scores or interpreting reviewer feedback.


## Design quality assessment

The design quality assessment evaluates user experience, interface design, and usability through 10 key questions based on established UX principles. **Target score: 3.8 or higher average** across all questions.

## Self-assessment process

### Step 1: Confirm the user and tasks

**Before opening the app**:

1. **Define the primary user**: Identify the specific role and context (e.g., "Maintenance engineers on offshore platforms")
2. **List key tasks**: Document 2-3 critical workflows this user needs to complete (e.g., "Check pump vibration alerts", "Schedule maintenance work")
3. **Gather context**: Note the user's experience level, time constraints, and success criteria


  This step is crucial. The assessment is only as useful as the clarity of the user and tasks. If they aren't well-defined, stop here and define them first.


### Step 2: Walk through each task end-to-end

**Task-based evaluation**:

1. **Open the app as that user**: Use a clean browser session with representative test data
2. **Complete each task from beginning to end**: Click through every step without shortcuts
3. **Focus on task completion**: Don't evaluate screens in isolation - only findings that affect task completion matter
4. **Document pain points**: Note where users get stuck, confused, or make errors

### Step 3: Score the 10 questions

**Assessment process**:

1. **Apply the scoring criteria**: Use what you observed during task completion to score each question 1-5
2. **Focus on critical areas**: Questions 2 (navigation) and 6 (error prevention) require walking the tasks and can't be assessed from code alone
3. **Calculate your average**: Sum all scores ÷ 10
4. **Identify improvement areas**: List any questions scoring under 3 for immediate attention

## The 10 design quality questions


  
    **Question**: Are you using [Aura](/cdf/aura) tokens, layouts, components and patterns correctly?

    See the [Aura design system](/cdf/aura) for foundations, primitives, and patterns.

    **5 - Excellent**: All Aura tokens are applied correctly, no hard coded values are used. The app uses proper responsive sizing and page layouts. Aura components are used without style overrides. Component best practices followed. Exceptions allowed for component needs not found in the system. Patterns align with design system guidelines.

    **4 - Good**: Mostly using Aura tokens and components with 1-2 minor exceptions. Layout spacing mostly consistent. Minimal style overrides that don't break patterns.

    **3 - Average**: Mix of Aura and custom elements. Some proper spacing, some random values. Using Aura components but overriding styles in multiple places. Some best practices ignored.

    **2 - Below average**: Frequently using custom colors, typography, or spacing instead of Aura tokens. Heavy component customization that breaks design system patterns.

    **1 - Poor**: Not using Aura design system. Custom colors, fonts, spacing throughout. Building custom components instead of using Aura. No adherence to design system guidelines.
  

  
    **Question**: Can users tell where they are and navigate easily? Are elements organized with clear visual hierarchy?

    **5 - Excellent**: User's current location always clear. Easy navigation forward/back. Menu structure consistent. Related items clearly grouped. Strong visual hierarchy guides attention. Content flows logically (F/Z pattern).

    **4 - Good**: Usually clear where you are. Navigation mostly consistent. Good grouping and hierarchy with minor exceptions.

    **3 - Average**: Sometimes unclear what page you're on. Navigation works but isn't always intuitive. Some grouping makes sense, hierarchy exists but not always clear.

    **2 - Below average**: Often lost or confused. Navigation changes between pages. Poor grouping and weak visual hierarchy - everything looks equally important.

    **1 - Poor**: No indication of current location. No clear way to navigate. Inconsistent structure. No logical grouping or visual hierarchy.
  

  
    **Question**: Are buttons, inputs, and actions labeled clearly? Can users understand what everything does?

    **5 - Excellent**: Every element has a clear, specific label. Language is plain and action-oriented ("Save changes", "Delete item").

    **4 - Good**: Most labels are clear with only minor ambiguity. Language is mostly plain with minimal jargon.

    **3 - Average**: Labels are present but sometimes vague ("Submit", "OK"). Some unnecessary jargon used.

    **2 - Below average**: Many labels are unclear or generic. Heavy use of technical terms without explanation.

    **1 - Poor**: Labels are missing, confusing, or use jargon that users won't understand.
  

  
    **Question**: Do users know what's happening? Are forms easy to use with helpful validation and error messages?

    **5 - Excellent**: Immediate feedback for actions. Clear loading states. Helpful success/error messages that explain what happened and what to do next. All form fields are clearly labeled. Required fields marked. Real-time validation with specific, actionable messages. Easy to correct mistakes.

    **4 - Good**: Most actions provide feedback. Loading states present. Form fields well-labeled. Validation is mostly helpful with minor timing or clarity issues. Error messages are generally clear.

    **3 - Average**: Some feedback provided but not consistent. Loading states sometimes missing. Fields labeled but some unclear. Basic validation present. Error messages are generic and could be more helpful.

    **2 - Below average**: Minimal feedback. Users often don't know if actions worked. Unclear what fields need. Validation only happens on submit. Unhelpful error messages.

    **1 - Poor**: No feedback. Silent failures. Technical error codes without explanation. No labels or requirements shown. No validation or only shows errors after multiple attempts.
  

  
    **Question**: Is it obvious what's clickable? Do interactive elements respond appropriately?

    **5 - Excellent**: All clickable items look clickable (buttons look like buttons). Hover effects on interactive elements. Cursor changes appropriately.

    **4 - Good**: Most interactive elements are obvious. Hover effects mostly present. Minor inconsistencies.

    **3 - Average**: Some clickable items look clickable. Inconsistent hover states. Occasionally unclear what's interactive.

    **2 - Below average**: Many interactive elements don't look clickable. Few or no hover effects. Confusing interactions.

    **1 - Poor**: Can't tell what's clickable. No visual feedback on interaction. Elements that look clickable aren't.
  

  
    **Question**: Can users undo or cancel destructive actions? Are there warnings before important actions?

    **5 - Excellent**: Confirmation dialogs before destructive actions. Auto-save prevents data loss. Clear undo options or cancel buttons.

    **4 - Good**: Most destructive actions have warnings. Some auto-save or undo capabilities.

    **3 - Average**: Some warnings present for major actions. Limited undo/cancel options. Some risk of data loss.

    **2 - Below average**: Few warnings. No undo options. Easy to accidentally lose work.

    **1 - Poor**: No warnings. No way to undo or cancel. Frequent accidental data loss.
  

  
    **Question**: Does your app work well on different screen sizes? Is it usable on desktop, tablet, and mobile?

    **5 - Excellent**: Seamless experience across desktop, tablet, and mobile. Layouts adapt appropriately. Touch targets are 40px+ on mobile. Text readable on all screen sizes. Navigation optimized for each device. No horizontal scrolling. If app is not used on mobile/hand-held device, it should be hidden, or functionality should be limited to prevent a poor user experience. Are hover states accounted for in mobile/touch devices so users can still access the same content without the ability to hover. Smooth behavior allows for relevant content to remain visible on mobile devices when native elements, such as keyboards, are present.

    **4 - Good**: Works well on most devices. Layouts adapt with minor issues. Most touch targets are appropriate. Generally readable and usable across screen sizes.

    **3 - Average**: Functional on multiple devices but not optimized. Some layout issues on smaller screens. Some touch targets too small on mobile. Horizontal scrolling sometimes required.

    **2 - Below average**: Poor mobile/tablet experience. Layouts break on smaller screens. Many touch targets too small. Text hard to read on mobile. Significant usability issues on non-desktop devices.

    **1 - Poor**: Only works on desktop. Completely broken on mobile/tablet. Unusable on smaller screens.
  

  
    **Question**: When there's no data, is it clear what to do next? Do empty pages guide users? Can users easily request access or share data (invite) with other users?

    **5 - Excellent**: All empty states show helpful messages and clear next steps. Simple graphics guide users. First-time users know exactly what to do.

    **4 - Good**: Most empty states are helpful. Generally clear what to do first. Minor gaps in guidance.

    **3 - Average**: Some empty states explained. First-time users can figure it out with effort.

    **2 - Below average**: Many blank pages with no guidance. Unclear how to get started.

    **1 - Poor**: Blank pages everywhere. No indication of what to do or why nothing is showing.
  

  
    **Question**: Does the app load quickly? Can users complete tasks efficiently? Are there shortcuts for common actions?

    **5 - Excellent**: Fast loading with progressive content display. Bulk actions available. Keyboard shortcuts work. Common tasks take minimal clicks.

    **4 - Good**: Reasonable loading times. Most tasks are streamlined. Some efficiency features present.

    **3 - Average**: Acceptable performance but could be faster. Tasks require moderate effort. Few shortcuts.

    **2 - Below average**: Slow loading. Tasks require many steps or clicks. No shortcuts or bulk actions.

    **1 - Poor**: Very slow or unresponsive. Tasks are tedious and require excessive clicks. No efficiency features.
  

  
    **Question**: Can people use your app with technology assisted devices, such as screen readers and keyboard inputs? Are there focus states and do they navigate across the page correctly? Does it meet WCAG AA 2.1 standards?

    **5 - Excellent**: All interactions work via keyboard (Tab, Enter, Escape). Text contrast meets WCAG AA (4.5:1 for normal text, 3:1 for large text). Clear focus indicators on all interactive elements. Proper ARIA labels for screen readers. Images have alt text. Clickable areas are 40px+ for touch, 20px+ for mouse. Form errors announced to screen readers.

    **4 - Good**: Most accessibility requirements met. Keyboard navigation works for nearly all features. Contrast meets standards with 1-2 minor exceptions. Focus indicators mostly visible. Most ARIA labels present.

    **3 - Average**: Basic keyboard support but missing for some features. Contrast mostly acceptable but some failures. Focus indicators are present but not always clear. Some ARIA labels missing. Clickable areas sometimes too small.

    **2 - Below average**: Limited keyboard support. Multiple contrast failures. Weak or missing focus indicators. Few ARIA labels. Many clickable areas are too small. Screen reader experience is poor.

    **1 - Poor**: No keyboard navigation. Poor contrast throughout. No focus indicators. No ARIA labels. Not usable with assistive technologies.
  


## Quality scoring

Each question is scored on a scale of 1-5, then calculate your average score by dividing the total by 10.

| Average score | Quality level | Recommendation |
| - | - | - |
| **4.5 - 5.0** | **Excellent — ready to launch** | Your app meets high quality standards. Minor improvements can be made over time. |
| **3.8 - 4.4** | **Good — launch with minor fixes** | Your app is functional and usable. Address the lower-scoring areas before or shortly after launch. |
| **3.0 - 3.7** | **Average — needs improvement** | Your app works but has significant usability issues. Fix major problems before launching. |
| **Below 3.0** | **Needs significant work** | Your app requires substantial improvements before launch. Focus on the lowest-scoring areas first. |

## Further reading

* [Application certification](/cdf/flows/guides/application-certification) — Where this rubric is applied during per-app certification.
* [Builder certification](/cdf/flows/guides/builder-certification) — Individual developer certification process.
* [Skills](/cdf/flows/concepts/skills) — How the certification skills (including the design review skill) are delivered.
* [Get started with Flows](/cdf/flows/guides/getting-started) — Initial setup and development guide.


# Running Flows custom apps locally
Source: https://docs.cognite.com/cdf/flows/guides/running-locally

Run your Flows custom app in development mode with npm, the Vite dev server, HTTPS, and Cognite Data Fusion (CDF).

Local development uses **Vite** (hot module replacement, HTTPS on localhost) and **npm**. The [Vite plugin API](/cdf/flows/reference/api/vite) documents `fusionOpenPlugin` and the CDF development URL pattern.

## Start the dev server

After you create your Flows custom app and install dependencies, start the dev server to run the app locally:

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

This will:

1. Generate HTTPS certificates (first run only).
2. Start the Vite dev server on `https://localhost:3001` (or the next available port if 3001 is already in use).
3. Open your app in CDF (when configured).

You access your app through the CDF URL shown in [Development URL](#development-url) below, not directly at `localhost:3001`. The browser needs to reach the local dev server, but authentication requires the CDF parent window.


  The dev server generates a self-signed HTTPS certificate to embed in CDF. The browser does not trust this certificate by default, so you'll see a warning, and CDF will show **Failed to connect to Fusion host** until you trust it. See [Trust the local HTTPS certificate](/cdf/flows/guides/local-https) for the one-time setup.


## How it works

Users sign in through CDF. Your app runs in an iframe inside CDF, and `connectToHostApp()` from `@cognite/app-sdk` handles authentication by communicating with the host window. Use the returned `HostAppAPI` to get an access token and construct an authenticated Cognite SDK.

**TanStack Query (React Query)** is included for data fetching. Combine it with `connectToHostApp()` to call the SDK (for example, assets or time series) with loading and error handling in React. See the [Auth API](/cdf/flows/reference/api/auth) for connection and credential usage.

```mermaid theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
%%{init: {
  "theme": "base",
  "themeVariables": {
    "lineColor": "#b8bec6",
    "primaryColor": "#ffffff",
    "tertiaryColor": "#f6f8fa",
    "fontFamily": "Inter, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, Helvetica Neue, Arial, sans-serif",
    "fontSize": "14px"
  }
}}%%
flowchart TB

%% ===== Node styles (same palette as Records / streams diagrams) =====
classDef Site   fill:#2f6cf6,stroke:#24292f,stroke-width:2px,color:#fff
classDef Area   fill:#8e43e7,stroke:#24292f,stroke-width:2px,color:#fff
classDef Line   fill:#0fa678,stroke:#24292f,stroke-width:2px,color:#fff
classDef Record fill:#566370,stroke:#24292f,stroke-width:2px,color:#fff

linkStyle default stroke:#b8bec6,stroke-width:3px;

subgraph fusion["Cognite Data Fusion"]
  subgraph app["Your Flows app"]
    direction TB
    dev["Vite dev server on localhost:3001"]:::Line
    creds["Receives auth credentials from CDF"]:::Record
    dev --> creds
  end
end

class fusion Site;
class app Area;
```

## Development URL

The dev server can open your app at:

```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
https://{org}.fusion.cognite.com/{project}/flows-apps/development/{appExternalId}/3001
```

Where `{org}` and `{project}` come from your `app.json` configuration.

## Hot module replacement

Changes to your code appear quickly without losing state:

```tsx theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
function App() {
  return Hello Flows!;
}
```

## Configuration

### Change the port

Edit `vite.config.ts`:

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
export default defineConfig({
  server: {
    port: 3002, // Change from default 3001
  },
});
```

### Disable auto-open

Remove `fusionOpenPlugin` from `vite.config.ts` if you do not want the browser to open automatically:

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
export default defineConfig({
  plugins: [
    react(),
    mkcert(),
    // fusionOpenPlugin(), // Comment out
  ],
});
```

## Troubleshooting

### App will not start

**Check your Node.js version**

Keep Node.js up to date. The generated `package.json` lists the versions the current template requires under `engines`.

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
node --version
npm --version
```

If Node.js is outdated, update it using nvm (recommended):

```bash wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
. "$HOME/.nvm/nvm.sh"
nvm install --lts
nvm use --lts
```

See [Install Node.js](/cdf/flows/guides/getting-started#install-nodejs) in Get started for more detail.

**`ERR_REQUIRE_ESM` error**

If you see an error about `require()` of an ES module, your Node.js version is too old. Update Node.js and compare it with `engines` in `package.json`.

**Dependencies not installed**

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

### Certificate errors

If `npm run dev` starts but the browser shows **Not Secure** or the app fails to load inside CDF, the dev server's HTTPS certificate isn't trusted by your browser. See [Trust the local HTTPS certificate](/cdf/flows/guides/local-https) for the one-time `mkcert` setup that fixes this on macOS, Linux, and Windows.

### Port already in use

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
lsof -i :3001
kill -9 
```

Or change the port in your Vite configuration.

## Further reading

* [Get started with Flows](/cdf/flows/guides/getting-started) — Create an app and prerequisites.
* [Deploy your Flows app](/cdf/flows/guides/deploying) — Interactive deploy and CI/CD.
* [Auth API](/cdf/flows/reference/api/auth) — `connectToHostApp` and authenticated CDF access.
* [Host App API](/cdf/flows/reference/api/host-app-api) — Navigation, state, sidebar visibility, fullscreen, and agent integration.
* [Vite plugin API](/cdf/flows/reference/api/vite) — `fusionOpenPlugin` and development URLs.


# Persisting app state in URLs
Source: https://docs.cognite.com/cdf/flows/guides/shareable-app-state-with-urls

Use syncInternalState to store your Flows custom app's view state in the URL, so users can share links that open the app exactly where they left off. This guide is for developers building Flows custom apps who want shareable deep links.

Flows custom apps run inside an iframe and can't manage the browser URL directly. Call `syncInternalState` to store your app's view state in the `customAppInternalState` URL search param. This makes the URL shareable. Anyone who opens it sees the same view. Cognite Data Fusion (CDF) passes the stored value back as `initialState` the next time the app mounts.

## Prerequisites

Before you start, ensure you have:

* A **Flows** custom app created and running locally. See [Getting started with Flows custom apps](/cdf/flows/guides/getting-started).
* **`@cognite/app-sdk`** installed.

## How it works

When your app calls `syncInternalState`, CDF serializes your state object into the `customAppInternalState` URL search param. The state can capture anything that defines where the user was. That includes not just which page is open, but also component-level detail: which panels are collapsed, what values are prefilled in a form, which rows are expanded in a table, what filters are active. For example:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "activeTab": "trends",
  "selectedAssetId": "7518432",
  "sidebarCollapsed": true,
  "filters": { "status": "active", "minValue": 42 },
  "prefilledForm": { "tag": "21PT1234", "unit": "bar" }
}
```

CDF URL-encodes that and appends it to the browser URL:

```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
https://your-cluster.fusion.cognite.com/my-project/flows/apps/my-app
  ?customAppInternalState=%7B%22activeTab%22%3A%22trends%22%2C%22selectedAssetId%22%3A...%7D
```

The user can copy that URL and share it. When someone else (or the same user after navigating away) opens the link, CDF decodes the param and passes it back to your app as `initialState`. The app opens with the same tab, filters, and form values already in place.

## Implement state syncing


  
    Destructure `initialState` from `connectToHostApp`. If it exists, parse it and restore your app's state before the first render.

    ```tsx wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    import { useEffect, useState } from "react";
    import { connectToHostApp, type HostAppAPI } from "@cognite/app-sdk";

    function App() {
      const [api, setApi] = useState(null);
      const [activeTab, setActiveTab] = useState("overview");

      useEffect(() => {
        connectToHostApp()
          .then(({ api, initialState }) => {
            setApi(api);
            if (initialState) {
              try {
                setActiveTab(JSON.parse(initialState).activeTab);
              } catch {
                // ignore malformed state
              }
            }
          })
          .catch(() => {
            // Not running inside CDF — continue with defaults
          });
      }, []);

      // ...
    }
    ```

    Always wrap `JSON.parse` in a `try`/`catch`. Saved state may be malformed if the schema changed between deploys.

    
      Open your app with a `customAppInternalState` value in the URL (or reload after syncing state in step 2). The restored tab, filters, and other fields match the saved state instead of your defaults.
    
  

  
    Call `syncInternalState` after any user action that changes meaningful state. Pass a JSON-serialized string.

    ```tsx wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    function handleTabChange(tab: string) {
      setActiveTab(tab);
      void api?.syncInternalState(JSON.stringify({ activeTab: tab }));
    }
    ```

    Pass the complete state object on every call. `syncInternalState` replaces the stored value; it does not merge.

    
      Change a persisted value (for example, switch tabs). The browser URL updates with a new `customAppInternalState` search param that reflects your change.
    
  


## Complete example

Because `syncInternalState` **replaces** the stored value on every call, the safest approach is to keep all persisted fields in a single state object and update them together. That way there is one place to serialize from and one place to restore to. No field silently overwrites another.

```tsx wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { useEffect, useRef, useState } from "react";
import { connectToHostApp, type HostAppAPI } from "@cognite/app-sdk";

interface PersistedState {
  activeTab: string;
  sidebarCollapsed: boolean;
  filters: { status: string };
}

const DEFAULT_STATE: PersistedState = {
  activeTab: "overview",
  sidebarCollapsed: false,
  filters: { status: "all" },
};

export function App() {
  const [api, setApi] = useState(null);
  const [state, setState] = useState(DEFAULT_STATE);
  const apiRef = useRef(null);

  useEffect(() => {
    connectToHostApp()
      .then(({ api, initialState }) => {
        apiRef.current = api;
        setApi(api);
        if (initialState) {
          try {
            setState({ ...DEFAULT_STATE, ...JSON.parse(initialState) });
          } catch {
            // malformed — keep defaults
          }
        }
      })
      .catch(() => {
        // standalone dev — continue without host
      });
  }, []);

  function updateState(patch: Partial) {
    setState((prev) => {
      const next = { ...prev, ...patch };
      void apiRef.current?.syncInternalState(JSON.stringify(next));
      return next;
    });
  }

  return (
    <>
       updateState({ sidebarCollapsed: collapsed })}
      />
       updateState({ activeTab: tab })}
      />
       updateState({ filters })}
      />
    
  );
}
```

`updateState` merges the patch into the current state and immediately syncs the full object. No field is ever lost.

## What to include in persisted state

Include state that defines the user's current view and that they would want to return to:

| Include | Exclude |
| - | - |
| Active tab or page | Loading flags (`isLoading`, `isFetching`) |
| Selected item IDs | Server-fetched data (re-fetch on mount) |
| Applied filters and sort order | Truly ephemeral UI state (open dropdown, tooltip) |
| Search queries | Error messages |
| Collapsed / expanded panel state | Sensitive values (tokens, passwords) |
| Prefilled form values | Large blobs or binary data |
| Zoom level or scroll position | N/A |

Keep persisted state small. Store IDs and view parameters, not full data objects. Fetch data from the API on mount using the restored IDs.


  Browsers impose a maximum URL length (typically around 2,000 characters, though it varies by browser and server). Because the state is URL-encoded, large state objects can exceed this limit and cause the URL to be truncated or rejected. Avoid storing large state objects. If your serialized state grows beyond a few hundred characters, store only the minimal keys needed to reconstruct the view.


## Further reading

* [Auth API](/cdf/flows/reference/api/auth) — `connectToHostApp` and authenticated CDF access.
* [Host App API](/cdf/flows/reference/api/host-app-api) — `syncInternalState` and other interaction methods.
* [Integrating AI agents with Flows](/cdf/flows/guides/ai_agent_integration) — Share app state with the built-in agent.
* [Run your app locally](/cdf/flows/guides/running-locally) — Dev server, HTTPS, and CDF iframe.


# Plan a dashboard app with spec-kit
Source: https://docs.cognite.com/cdf/flows/guides/spec-kit-walkthrough

Learn to use spec-kit by running specify, clarify, and plan on a real Production Accounting dashboard — from a short description to a reviewable implementation plan.

You'll run the first three spec-kit commands — `/speckit.specify`, `/speckit.clarify`, and `/speckit.plan` — to plan a realistic Production Accounting dashboard. You will end with a `spec.md` that captures your intent, a Clarifications section that resolves every ambiguity, and a `plan.md` your agent can act on.

The last two commands, `/speckit.tasks` and `/speckit.implement`, are not covered. See [Spec-driven development](/cdf/flows/concepts/spec-driven-development) for the full flow.

The spec you write in this walkthrough drives toward a finished app like the one below — a KPI bar and a Balance Reconciliation Tree with quality badges, running as a Flows app in development mode:


  


## Prerequisites

You need a **Flows** custom app with spec-kit enabled. If you don't have one yet:

1. Follow [Getting started with Flows custom apps](/cdf/flows/guides/getting-started) to create your app.
2. When prompted **Enable spec-driven development**, choose **Yes**, then choose **Yes** again when prompted to enable spec-kit.

Once your app is open in Cursor or Claude Code, the spec-kit slash commands are available in `.cursor/commands/` and `.claude/commands/`.

## Step 1: Specify your feature

Start with a short description of the app, then let spec-kit expand it into a structured spec.


  
    Give spec-kit a short description of what you want to build. You don't need to fill in every detail — the template will prompt you for the rest:

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    /speckit.specify Build an Oil Balance Detail dashboard called 'Production Accounting'. Landing page shows a KPI bar (Gross Production, Net Export, Imbalance, Closure %) and a Balance Reconciliation Tree — hierarchical table of flow components with values, source tags, and quality badges (Verified/Estimated/Manual). Read flow components and KPI inputs from CDF data models. React + Tailwind.
    ```

    The command creates `specs/001-production-accounting/spec.md` pre-populated with the spec-kit template.

    
      Keep the one-liner focused on the surface and the key behavior. You will fill in edge cases and constraints during `/speckit.clarify`.
    
  

  
    Open `specs/001-production-accounting/spec.md`. The template has generated User Stories, acceptance scenarios, and placeholder Functional Requirements from your description. An example of the populated output (trimmed):

    ```markdown wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    # Feature Specification: Production Accounting Dashboard

    **Feature Branch**: `001-production-accounting`
    **Created**: 2026-06-08
    **Status**: Draft
    **Input**: User description: "Build an Oil Balance Detail dashboard
    called 'Production Accounting'..."

    ## User Scenarios & Testing

    ### User Story 1 — View at-a-glance production KPIs (Priority: P1)

    A production accountant opens the dashboard to get an immediate
    snapshot of overall oil balance health. The KPI bar surfaces four
    headline metrics — Gross Production, Net Export, Imbalance, and
    Closure % — so the accountant can immediately identify if the period
    is closing within acceptable tolerance.

    **Acceptance Scenarios**:

    1. **Given** the dashboard loads, **When** the landing page is
       displayed, **Then** four KPI cards appear in a horizontal bar:
       Gross Production (Mbbl), Net Export (Mbbl), Imbalance (Mbbl),
       and Closure (%).
    2. **Given** Imbalance is outside the acceptable threshold, **Then**
       the Imbalance card renders in a warning or danger tone.

    ### User Story 2 — Explore the Balance Reconciliation Tree (Priority: P2)

    The accountant needs to trace where production volumes come from and
    where they go. The Balance Reconciliation Tree is a hierarchical table
    listing all flow components (Wellhead Production → Field Gross →
    Terminal Receipts → Pipeline Export → Losses). Each row shows the
    component name, a numeric value with unit, a source tag, and a quality
    badge (Verified / Estimated / Manual).

    ## Requirements

    ### Functional Requirements

    - **FR-001**: The dashboard MUST display a KPI bar with four metrics:
      Gross Production (Mbbl), Net Export (Mbbl), Imbalance (Mbbl), and
      Closure (%). Closure % MUST equal Net Export / Gross Production × 100.
    - **FR-004**: The Balance Reconciliation Tree MUST render as a
      hierarchical table with collapsible parent rows.
    - **FR-006**: Quality badges MUST support exactly three states:
      Verified (success tone), Estimated (warning tone), Manual (neutral tone).
    - **FR-009**: The dashboard MUST load flow components and balance
      periods from the `production_accounting` data model and read the
      values behind each source tag from `cdf_cdm.CogniteTimeSeries:v1`.
    ```

    Fill in any sections the template left as placeholders, especially **Data Models & CDF Integration** and **Success Criteria**.

    
      Complete these sections before running `/speckit.plan`. The plan command depends on them to generate an accurate implementation plan.
    
  


## Step 2: Clarify ambiguities

Resolve the open questions in the spec before you plan, so the implementation rests on explicit decisions.


  
    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    /speckit.clarify
    ```

    The command reads your spec and runs an internal coverage scan across categories: functional scope, data model, integration, and edge cases. It then surfaces up to five questions that would block planning if left unanswered.
  

  
    For each question, your agent presents a recommendation and an options table. The following example is from the Production Accounting spec:

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    **Question 3 of up to 5**

    The spec doesn't define how Imbalance is derived. In oil balance
    accounting this matters because the value could be computed from the
    tree (Gross Production minus Net Export minus Losses) or it could be a
    standalone value independent of the tree rows.

    **Recommended:** Option B — derived from tree totals. This ensures the
    KPI bar and the reconciliation tree are mathematically consistent
    (Imbalance = Gross Production − Net Export − Losses), which is the
    standard industry definition and keeps the dashboard internally
    coherent.

    | Option | Description |
    |--------|-------------|
    | A | Independent value — KPI bar values are all standalone, no formula |
    | B | Derived: Imbalance = Gross Production − Net Export − sum of Losses nodes |
    | C | Derived from tree totals but formula is an implementation detail |

    Reply with the option letter, "yes" to accept the recommendation,
    or a short answer (≤5 words).
    ```

    Reply with the option letter or accept the recommendation. Your agent writes the answer directly back into the `spec.md` **Clarifications** section:

    ```markdown theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    ## Clarifications

    ### Session 2026-06-08

    - Q: What is the initial expand state of the Balance Reconciliation Tree
      on load? → A: Top-level rows expanded, all children collapsed
      (progressive disclosure).
    - Q: Is the Imbalance warning threshold user-configurable or hardcoded?
      → A: Hardcoded constant (±5 Mbbl), not user-adjustable in v1.
    - Q: Is the Imbalance KPI value derived from tree totals or independent
      of the tree? → A: Derived — Imbalance = Gross Production − Net Export −
      sum of Losses nodes; KPI bar and tree MUST be consistent.
    - Q: Is the dashboard a standalone page or embedded in a Cognite Data Fusion
      iframe? → A: Embedded in CDF iframe — use `@cognite/app-sdk`
      (`connectToHostApp`) for host integration and layout.
    - Q: Which UI state should be persisted in the CDF URL? → A: None —
      dashboard always opens in its default state on reload.
    ```
  

  
    When all questions are resolved, your agent outputs a summary:

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    ## Clarification complete

    5 of 5 questions asked and answered.

    Spec: specs/001-production-accounting/spec.md

    Sections touched: Functional Requirements (FR-001, FR-002, FR-007,
    FR-011, FR-012), Key Entities (Imbalance derivation), Assumptions,
    Clarifications.

    All categories resolved. Suggested next command: /speckit.plan
    ```

    At this point, `spec.md` is complete and ready for planning. Commit it before moving on so the decisions are in git history.
  


## Step 3: Generate the implementation plan

Turn the clarified spec into a concrete, reviewable plan your agent can act on.


  
    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    /speckit.plan
    ```

    The command reads the clarified spec and generates `specs/001-production-accounting/plan.md`. For the Production Accounting dashboard, the output included the following sections (trimmed):

    ```markdown wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    # Implementation Plan: Production Accounting Dashboard

    **Branch**: `001-production-accounting` | **Date**: 2026-06-08

    ## Summary

    Replace the current boilerplate App.tsx with a Production Accounting
    dashboard embedded in the Cognite Data Fusion iframe. The dashboard renders
    a KPI bar computed from the oil balance dataset, and a hierarchical
    Balance Reconciliation Tree with expand/collapse rows, quality badges,
    and a quality filter. Data is read from CDF data models through
    `connectToHostApp`.

    ## Technical Context

    Language/Version: TypeScript 5.x + React 18.3
    Primary Dependencies: @cognite/aura/components, @cognite/app-sdk,
      @cognite/sdk, Tailwind CSS 4, Vitest 4
    Storage: CDF data models — production_accounting (FlowComponent,
      BalancePeriod) and cdf_cdm (CogniteTimeSeries)
    Testing: Vitest + @testing-library/react
    Target Platform: Cognite Data Fusion iframe (desktop, 1280px+ viewport)

    ## Project Structure

    src/
    ├── __mocks__/
    │   └── balanceData.ts
    ├── types/
    │   └── balance.ts
    ├── services/
    │   ├── BalanceDataService.ts
    │   └── CdfBalanceDataService.ts
    ├── state/
    │   └── DashboardStateProvider.tsx
    ├── hooks/
    │   ├── useDashboardStorage.ts
    │   └── useProductionAccountingViewModel.ts
    ├── components/
    │   ├── KpiBar/
    │   │   ├── KpiBar.tsx
    │   │   ├── KpiCard.tsx
    │   │   └── KpiBar.test.tsx
    │   ├── ReconciliationTree/
    │   │   ├── ReconciliationTree.tsx
    │   │   ├── TreeRow.tsx
    │   │   ├── QualityBadge.tsx
    │   │   ├── QualityFilter.tsx
    │   │   └── ReconciliationTree.test.tsx
    │   └── ProductionAccountingPage.tsx
    ├── App.tsx
    └── App.test.tsx
    ```

    The plan also includes a **Constitution Check** — a table verifying that the proposed implementation satisfies each rule in `AGENTS.md`, such as using `@cognite/aura/components` before raw HTML, following the ViewModel pattern, and writing tests for every hook and component that contains logic.
  

  
    Review `plan.md` with your team before starting implementation. If anything looks off, update `spec.md` and re-run `/speckit.plan`. Commit both files together.

    
      You don't have to use `/speckit.plan` to generate this file. You can write `plan.md` yourself or produce it through your agent's in-session plan mode — as long as the steps are numbered and ordered clearly enough for `/speckit.tasks` to split into a task list.
    
  


## Troubleshooting


  
    The slash commands ship only when you enable spec-kit during `apps create`. Confirm that `.cursor/commands/` and `.claude/commands/` contain `speckit.*` files. If they're missing, you created the app without spec-kit — there is no retrofit command, so re-scaffold the app and choose **Yes** at the spec-kit prompt, or manually copy the spec-kit files into your app. See [Spec-driven development](/cdf/flows/concepts/spec-driven-development#spec-kit).
  

  
    The command asks only about ambiguities it finds, up to five. If your `spec.md` is already specific, it may ask fewer questions or none. Review the coverage report it prints. If a category you care about is marked resolved but you disagree, add detail to `spec.md` and run `/speckit.clarify` again.
  

  
    The plan is only as good as the clarified spec. Update `spec.md` — especially the Functional Requirements and the Data Models & CDF Integration section — then re-run `/speckit.plan`. Running the command again regenerates the plan from the current spec.
  


## What's next

You've run specify, clarify, and plan on a real feature and committed a `spec.md` and `plan.md` to your repository. Your agent now has the context it needs to implement the Production Accounting dashboard.

The next two spec-kit commands decompose the plan into executable tasks and run them in order:

* `/speckit.tasks` — writes an ordered `tasks.md` where each task maps back to a functional requirement.
* `/speckit.implement` — runs the tasks in sequence, stopping at each one to confirm before continuing.

See [Spec-driven development](/cdf/flows/concepts/spec-driven-development) for how these commands work and how they fit into the full flow.


# Building Flows custom applications
Source: https://docs.cognite.com/cdf/flows/index

Build production-ready web applications for industrial applications with AI-native development tools and modern web technologies.

**Cognite Flows** enables you to build production-grade web applications that integrate seamlessly with CDF. **Flows** provides an accessible development platform with built-in templates, authentication, and AI-enhanced capabilities for creating scalable industrial applications.

## Key capabilities

* **Modern web platform**: Easy-to-use templates with full customization options.
* **Built-in CDF integration**: Authentication, data access, and SDK utilities.
* **AI-native development**: Pre-built skills and agent patterns for AI coding agents — including Claude Code, Cursor, GitHub Copilot, and more.
* **Developer-friendly tools**: Hot reload, automated testing, and simple deployment.
* **Enterprise ready**: Version control and access control with scalable architecture and CI/CD support.


  
    Create an app, install dependencies, and run it in CDF.
  

  
    Become a certified Flows custom apps builder for customer environments.
  

  
    Run the four skill-driven steps to certify an app for production deployment.
  

  
    Request Dev status to publish builder-signed apps on a non-production project.
  

  
    Scaffolding, auth, Vite, tests, deploy, and data fetching at a glance.
  

  
    UI framework for CDF and Flows custom app UI.
  

  
    Patterns and pitfalls for keeping Flows apps well-structured as they grow.
  

  
    Plan features in checked-in specs your team and agent both work from.
  

  
    Agent-agnostic AI skills that ship with every Flows custom app.
  

  
    Dev server, HTTPS, CDF iframe, and local configuration.
  

  
    Use the App Hosting OAuth relay for an additional Microsoft Entra ID sign-in from within a Flows custom app.
  

  
    Interactive deploy and CI/CD.
  



# Flows Auth API
Source: https://docs.cognite.com/cdf/flows/reference/api/auth

Complete reference for connectToHostApp and authenticated Cognite Data Fusion (CDF) access in Flows custom apps.

Connect your Flows custom app to the Cognite Data Fusion (CDF) host window and get credentials for authenticated SDK access.

Call `connectToHostApp` once at app startup. It returns a `HostAppAPI` instance with methods to get the current project, base URL, and access token. Use those credentials to construct a `CogniteClient`.

For navigation, state, sidebar visibility, fullscreen, and agent integration, see [Host App API](/cdf/flows/reference/api/host-app-api).

## Prerequisites

* A Flows custom app created with [`npx @cognite/cli@latest apps create`](/cdf/flows/guides/getting-started)
* Basic understanding of React hooks and `useEffect`

## connectToHostApp

Connects your app to the CDF host window and returns a `HostAppAPI` instance.

```tsx theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { connectToHostApp } from "@cognite/app-sdk";

const { api } = await connectToHostApp();
```

### Return value

| Property | Type | Description |
| - | - | - |
| `api` | `HostAppAPI` | API for communicating with the CDF host |
| `initialState` | `string \| undefined` | Restored state from a previous session (if `syncInternalState` was used) |

### Example: connect and get project

```tsx theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { useEffect, useState } from "react";
import { connectToHostApp } from "@cognite/app-sdk";

function App() {
  const [project, setProject] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState();

  useEffect(() => {
    let cancelled = false;
    connectToHostApp()
      .then(async ({ api }) => {
        if (cancelled) return;
        const proj = await api.getProject();
        if (!cancelled) setProject(proj);
      })
      .catch((err: unknown) => {
        if (cancelled) return;
        setError(err instanceof Error ? err.message : String(err));
      })
      .finally(() => {
        if (!cancelled) setIsLoading(false);
      });
    return () => {
      cancelled = true;
    };
  }, []);

  if (isLoading) return Loading...;
  if (error) return Error: {error};
  return Project: {project};
}
```

## HostAppAPI credential methods

The `HostAppAPI` instance returned by `connectToHostApp` includes methods for the current project, base URL, and access token. For navigation, state, sidebar visibility, fullscreen, and agent integration, see [Host App API](/cdf/flows/reference/api/host-app-api).

### getProject

Returns the current CDF project name.

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
const project = await api.getProject();
```

### getBaseUrl

Returns the base URL of the CDF cluster (for example, `https://greenfield.cognitedata.com`).

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
const baseUrl = await api.getBaseUrl();
```

### getAccessToken

Returns the current access token for authenticating CDF API calls.

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
const token = await api.getAccessToken();
```

### Example: construct a CogniteClient

Use `getProject`, `getBaseUrl`, and `getAccessToken` together to build an authenticated `CogniteClient` from `@cognite/sdk`:

```tsx theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { useEffect, useState } from "react";
import { connectToHostApp } from "@cognite/app-sdk";
import { CogniteClient } from "@cognite/sdk";

function App() {
  const [sdk, setSdk] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState();

  useEffect(() => {
    let cancelled = false;
    connectToHostApp()
      .then(async ({ api }) => {
        if (cancelled) return;
        const [project, baseUrl] = await Promise.all([
          api.getProject(),
          api.getBaseUrl(),
        ]);
        const client = new CogniteClient({
          project,
          baseUrl,
          getToken: () => api.getAccessToken(),
        });
        if (!cancelled) setSdk(client);
      })
      .catch((err: unknown) => {
        if (cancelled) return;
        setError(err instanceof Error ? err.message : String(err));
      })
      .finally(() => {
        if (!cancelled) setIsLoading(false);
      });
    return () => {
      cancelled = true;
    };
  }, []);

  if (isLoading) return Loading...;
  if (error) return Error: {error};
  // pass sdk down or use context
}
```

## Further reading

* [Getting started with Flows custom apps](/cdf/flows/guides/getting-started) — Create your first app
* [Run your app locally](/cdf/flows/guides/running-locally) — Development with authentication
* [Signing in with an additional Microsoft Entra ID account](/cdf/flows/guides/oauth-relay) — Additional Microsoft Entra ID sign-in via the App Hosting OAuth relay
* [Flows features](/cdf/flows/concepts/features) — TanStack Query integration with `connectToHostApp`


# Content Security Policy for Flows custom apps
Source: https://docs.cognite.com/cdf/flows/reference/api/csp

Understand the Content Security Policy (CSP) for Flows custom apps and how to allow trusted network sources in manifest.json.

When you deploy a Flows custom app, the platform applies a strict [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) — a browser security feature that controls which external resources the app is allowed to load. CSP limits where scripts, styles, images, fonts, frames, workers, media, and network requests can come from.

Most apps only need to change CSP when they call an external API, load map tiles, embed a frame, use a CDN, or add a dependency that creates workers or evaluates code at runtime. Add trusted sources in `permissions.network` in `manifest.json`.


  Run the app locally first. The [Flows Vite plugin](/cdf/flows/reference/api/vite) applies CSP during development and logs a manifest snippet when the browser blocks a request.


## How it works

Use `manifest.json` to add trusted sources to supported fetch directives:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://tiles.example.test"],
        "directives": ["img-src", "connect-src"]
      },
      {
        "sources": ["https://api.partner.test"]
      }
    ]
  }
}
```

If `directives` is omitted, the source is added to `connect-src`.

Apps can't remove baseline restrictions, such as `object-src 'none'`, or widen document-level directives, such as `default-src` and `frame-ancestors`. Every Flows app starts with the production baseline.

## Debug CSP violations

Run the app locally:

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

When the browser blocks a request, the Vite plugin logs a `manifest.json` snippet to the browser console (DevTools → Console tab):

```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
Flows Apps [linked-app-sdk v2] blocked connect-src -> https://tiles.example.test
Update your manifest.json with the snippet below:
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://tiles.example.test"],
        "directives": ["connect-src"]
      }
    ]
  }
}
```

Paste the rule into `manifest.json`. The dev server picks up the change without a restart.

## Production baseline

Hosted production apps use this CSP baseline:

```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
frame-ancestors https://*.fusion.cognite.com https://*.fusion.cogniteapp.com
base-uri 'self'
connect-src 'self' https://*.cognitedata.com wss://*.cognitedata.com
default-src 'self'
font-src 'self' data: https://fonts.gstatic.com
form-action 'self'
frame-src 'self'
img-src 'self' data: blob:
media-src 'self'
object-src 'none'
script-src 'self'
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com
worker-src 'self' blob:
```

Important details:

* CDF API and WebSocket endpoints are already allowed in `connect-src`.
* Production `script-src` allows `'unsafe-inline'` to be added via `manifest.json`, but this is strongly discouraged. Use [hash sources](#inline-scripts-in-script-src) instead.
* `eval` and `new Function(...)` are always blocked in production, regardless of `manifest.json`.
* `style-src` includes `'unsafe-inline'` because many UI libraries inject style tags.
* Aura font sources are already allowed.
* `frame-ancestors` is controlled by App Hosting and can't be changed from `manifest.json`.

## Development differences

Development uses the same baseline with a few additions for Vite and local framing:

* `script-src` also includes `'unsafe-inline'` and `'unsafe-eval'` for Vite HMR and React Refresh.
* `http://localhost`, `http://127.0.0.1`, `ws://localhost`, and `ws://127.0.0.1` sources are accepted during development.
* Local and preview CDF origins can frame the app.

These additions are removed in production. Dependencies that rely on development-only script relaxations will fail after deployment.

## Choose the right directive

Use the browser CSP error to identify the blocked directive, then add the narrowest source that covers it.

| Requirement | Directive |
| - | - |
| External HTTPS API | `connect-src` |
| WebSocket | `connect-src` with a `wss://` source |
| Map tiles, images, SVGs, or canvas textures | `img-src` |
| Web fonts | `font-src` |
| CDN stylesheet | `style-src` |
| Embedded iframe | `frame-src` |
| Audio or video | `media-src` |
| Worker script from another origin | `worker-src` |
| JavaScript file from another origin | `script-src` |


  Use `script-src` only for trusted script files. It can't approve `eval`, `new Function(...)`, or inline script tags in production.


## Manifest reference

Each `permissions.network` entry has this shape:

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
type NetworkRule = {
  sources: string[];
  directives?: CspFetchDirective[];
};
```

If `directives` is omitted, the source is added to `connect-src`. The valid values for `CspFetchDirective` are the eight directives in [Extensible directives](#extensible-directives).

### Extensible directives

Only these fetch directives can be extended:

```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
connect-src, font-src, frame-src, img-src, media-src, script-src, style-src, worker-src
```

Rules that only target unsupported directives are dropped. Unsupported examples include `default-src`, `frame-ancestors`, `object-src`, `base-uri`, and `form-action`.

### Source formats

Production accepts:

* HTTPS sources, for example `https://api.example.test` or `https://api.example.test:8443/v1`
* Secure WebSocket sources, for example `wss://stream.example.test`
* Host wildcards, for example `https://*.example.test`

Development also accepts local HTTP and WebSocket sources:

* `http://localhost:3000`
* `http://127.0.0.1:3000`
* `ws://localhost:5173`
* `ws://127.0.0.1:5173`

For `script-src`, production also accepts:

* `'wasm-unsafe-eval'`
* `'strict-dynamic'`
* Hash sources such as `'sha256-...'`, `'sha384-...'`, and `'sha512-...'`

The policy rejects sources with whitespace, control characters, semicolons, stray quotes, `javascript:` URLs, `data:` URLs, and broad wildcards, such as `https://*`.

Nonces are not supported — the Flows custom apps service does not generate per-request nonces.


  `manifest.json` can't add `'unsafe-eval'` to production `script-src`. Adding `'unsafe-inline'` is technically allowed but strongly discouraged — use a hash source to allowlist only the specific script you need, or move the code to an external file bundled by Vite. See [inline scripts](#inline-scripts-in-script-src).


## Examples

### External API

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://api.partner.test"]
      }
    ]
  }
}
```

Because `directives` is omitted, the source is added to `connect-src`.

### Map tiles

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://tiles.example.test"],
        "directives": ["img-src", "connect-src"]
      }
    ]
  }
}
```

Some map libraries fetch tile metadata with `fetch()` and load tile images through `` or canvas, so they need both directives.

### CDN stylesheet

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://cdn.example.test"],
        "directives": ["style-src"]
      }
    ]
  }
}
```

### WebAssembly

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["'wasm-unsafe-eval'"],
        "directives": ["script-src"]
      }
    ]
  }
}
```

Add this only when a library needs WebAssembly compilation at runtime.

## Common library issues

Some libraries use runtime patterns that production CSP blocks.

### Libraries that use `eval` or `new Function`

Templating, expression, charting, and schema libraries sometimes compile strings into functions at runtime. That requires `'unsafe-eval'` in `script-src`, which production apps don't allow.

Use a build-time compiler, a precompiled distribution, or a different dependency.

### `react-pdf` and `pdfjs-dist`

Configure the PDF worker as a same-origin asset bundled by Vite:

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { pdfjs } from "react-pdf";

pdfjs.GlobalWorkerOptions.workerSrc = new URL(
  "pdfjs-dist/build/pdf.worker.min.mjs",
  import.meta.url
).toString();
```

The URL resolves to the app's own origin, which is covered by `'self'` in `worker-src`.

### `troika-three-text` and `reagraph`

`troika-three-text`, used by `reagraph`, probes worker support with a blob worker and can call `importScripts()` with generated URLs. If that path is blocked, force troika onto the main thread before any `Text` instances or reagraph renders are created:

```ts theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
import { configureTextBuilder } from 'troika-three-text';

configureTextBuilder({ useWorker: false });
```

### Inline scripts in `script-src`

Adding `'unsafe-inline'` to `script-src` allows any inline `