Local Development

Local Development

Recommended Flow: icp-cli + Vite Plugin

For Vite apps, the preferred local workflow is:

1. start the local network with icp-cli
2. deploy canisters with icp deploy
3. let @ic-reactor/vite-plugin inject the ic_env cookie
4. configure ClientManager with withCanisterEnv: true

Example:

export const clientManager = new ClientManager({
  queryClient,
  withCanisterEnv: true,
})

icp network start -d
icp deploy backend
pnpm dev

Manual dfx Flow

If your project still uses dfx, use withProcessEnv: true and point the app at declarations generated by that workflow.

export const clientManager = new ClientManager({
  queryClient,
  withProcessEnv: true,
})

Common environment value:

DFX_NETWORK=local

Root Key Reminder

For local replicas, make sure the client manager is initialized so the local root key is fetched:

await clientManager.initialize()

Troubleshooting

Certificate verification failures

Usually means the local root key was not fetched yet.

Wrong local port

• icp-cli: icp network status -e local --json
• dfx: dfx info webserver-port

Then set port explicitly if needed.

Local Internet Identity

If you use a manual dfx project, deploy a local Internet Identity canister and let useAuth() auto-detect the correct provider from the network settings.