Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cognite.com/llms.txt

Use this file to discover all available pages before exploring further.

Local development uses Vite (hot module replacement, HTTPS on localhost) and npm. The Vite plugin API 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: 
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 below, not directly at localhost:3001. The browser needs to reach the local dev server, but authentication requires the CDF parent window.
On the first run, you may be prompted for your sudo password (your computer login password) to install a locally trusted certificate in your system keychain.Your app runs inside CDF over HTTPS, so the browser needs a valid certificate. The certificate is generated once and reused for later sessions.

​
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 for usage and examples.

​
Development URL

The dev server can open your app at: 
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: 
function App() {
  return <h1>Hello Flows!</h1>;
}

​
Configuration

​
Change the port

Edit vite.config.ts: 
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: 
export default defineConfig({
  plugins: [
    react(),
    mkcert(),
    // fusionOpenPlugin(), // Comment out
  ],
});

​
Troubleshooting

​
App will not start

Check your Node.js version Flows requires Node.js 20.19 or higher: 
node --version
If the version is below v20.19.0, update Node.js using nvm (recommended): 
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
. "$HOME/.nvm/nvm.sh"
nvm install 20.19.5
nvm use 20.19.5
See Install Node.js 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 to Node.js 20.19 or later. Dependencies not installed 
npm install

​
Certificate errors

App does not load in CDF If you run npm start but the app fails to load in CDF:
  1. Open the localhost URL in your browser (for example, https://localhost:3001).
  2. Select Advanced, then Proceed to accept the certificate.
  3. Return to CDF and refresh the page.
Certificate warnings Trust the certificate in your browser, or delete the .vite-plugin-mkcert folder and restart the dev server.

​
Port already in use

lsof -i :3001
kill -9 <PID>
Or change the port in your Vite configuration.

​
Further reading

Last modified on May 12, 2026