> ## 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.
# Running Flows custom apps 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 usage and examples.
```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**
Flows requires Node.js 20.19 or higher:
```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
node --version
```
If the version is below v20.19.0, update Node.js 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 20.19.5
nvm use 20.19.5
```
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 to Node.js 20.19 or later.
**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`, `HostAppAPI`, and helpers.
* [Vite plugin API](/cdf/flows/reference/api/vite) — `fusionOpenPlugin` and development URLs.