Vite Environment Variables

This example showcases how IC Reactor integrates with Vite’s environment variable system and the local icp-cli environment to automatically manage canister IDs and network configurations.

Features Demonstrated

• Automatic Injection: Canister IDs are automatically detected from the local environment and injected into the frontend.
• Fixed Overrides: Use canisterId in the Vite plugin config when you want a specific canister ID to override the auto-detected development value.
• Seamless Local Dev: Run icp deploy and your frontend immediately knows where to find the canisters.
• Client Configuration: ClientManager reads the plugin’s ic_env cookie automatically here — canister IDs and root key alike need no option to switch on, because the dev server is a local host and that is where the cookie is trusted. On a custom domain or mainnet it is not read at all.

Links

Open in StackBlitzEdit and run in your browser

View on GitHubBrowse the source code

Live Preview

Implementation

The ClientManager needs no extra configuration — in the browser it reads the ic_env cookie for canister IDs on every construction, and adopts the root key it carries, because the dev server is served from a local host. On any other host the cookie is ignored entirely — root key and canister IDs alike — unless you pass allowEnvConfig: true, and a reactor with no configured canisterId throws there rather than trusting it:

frontend/src/lib/clients.ts

import { ClientManager } from "@ic-reactor/react"
import { QueryClient } from "@tanstack/react-query"

export const queryClient = new QueryClient()

/**
 * IC Reactor Client Manager
 *
 * Auto-generated by @ic-reactor/codegen
 */
export const clientManager = new ClientManager({
  queryClient,
})

The Vite plugin then ensures these variables are available during development by setting an ic_env cookie:

frontend/vite.config.ts

import { defineConfig } from "vite"
import { icReactor } from "@ic-reactor/vite-plugin"

export default defineConfig({
  plugins: [
    icReactor({
      // Generate where the app imports from. The defaults are
      // outDir "src/declarations" + clientManagerPath "../../clients", which
      // line up only when the ClientManager sits at `src/clients`.
      outDir: "./src/lib/canisters",
      canisters: [
        {
          name: "backend",
          didFile: "./declarations/backend.did",
          clientManagerPath: "../../clients",
        },
      ],
      // Enabled by default
      injectEnvironment: true,
    }),
  ],
})

Pinning a canister ID

A per-canister canisterId overrides whatever the local icp deploy discovered, and is baked into the generated reactor. That is what you want for a mainnet canister the app should always talk to — and what you do not want in a local-development config, where it silently points the app at someone else’s canister instead of the one you just deployed. The example above deliberately omits it, matching the checked-in examples/vite-environment-variables/frontend/vite.config.ts.

Keep outDir and clientManagerPath in step

clientManagerPath is resolved from the generated file, so moving outDir without moving it too produces bindings that import a module that does not exist. If the app then keeps importing an older hand-copied set from the old location, everything still runs — against bindings no regeneration touches.