CanisterEnv

Defined in: packages/agent/src/canister-env/index.ts:60

Experimental

The environment variables served by the asset canister that hosts the frontend. You can extend the CanisterEnv interface to add your own environment variables and have strong typing for them.

See

The Canister Environment Guide for more details on how to use the canister environment in a frontend application

Examples

Extend the global CanisterEnv interface to add your own environment variables:

index.ts

// You can declare the interface to have strong typing
// for your own environment variables across your codebase
declare module '@icp-sdk/core/agent/canister-env' {
  interface CanisterEnv {
    readonly ['PUBLIC_CANISTER_ID:backend']: string;
    readonly PUBLIC_API_URL: string;
  }
}

const env = getCanisterEnv();

console.log(env.IC_ROOT_KEY); // by default served by the asset canister
console.log(env['PUBLIC_CANISTER_ID:backend']); // ✅ TS passes
console.log(env.PUBLIC_API_URL); // ✅ TS passes
console.log(env['PUBLIC_CANISTER_ID:another']); // ❌ TS will show an error

Alternatively, use the generic parameter to specify additional properties:

index.ts

const env = getCanisterEnv<{ readonly ['PUBLIC_CANISTER_ID:backend']: string }>();

console.log(env.IC_ROOT_KEY); // by default served by the asset canister
console.log(env['PUBLIC_CANISTER_ID:backend']); // ✅ from generic parameter, TS passes
console.log(env['PUBLIC_CANISTER_ID:frontend']); // ❌ TS will show an error

Properties

IC_ROOT_KEY

readonly IC_ROOT_KEY: Uint8Array

Defined in: packages/agent/src/canister-env/index.ts:65

Experimental

The root key of the IC network where the asset canister is deployed. Served by default by the asset canister that hosts the frontend.