getCanisterEnv

getCanisterEnv<T>(options): CanisterEnv & T

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

Experimental

Get the environment variables served by the asset canister via the cookie.

The returned object always includes IC_ROOT_KEY property. You can extend the global CanisterEnv interface to add your own environment variables and have strong typing for them.

In Node.js environment (or any other environment where globalThis.document is not available), this function will throw an error. Use safeGetCanisterEnv if you need a function that returns undefined instead of throwing errors.

Type Parameters

T

T = Record<string, never>

Parameters

options

GetCanisterEnvOptions = {}

The options for loading the canister environment variables

Returns

CanisterEnv & T

The environment variables for the asset canister, always including IC_ROOT_KEY

Throws

When globalThis.document is not available

Throws

When the cookie is not found

Throws

When the IC_ROOT_KEY is missing or has an invalid length

See

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

Example

type MyCanisterEnv = {
  readonly ['PUBLIC_CANISTER_ID:backend']: string;
};

const env = getCanisterEnv<MyCanisterEnv>();

console.log(env.IC_ROOT_KEY); // always available (Uint8Array)
console.log(env['PUBLIC_CANISTER_ID:backend']); // ✅ from generic parameter, TS passes
console.log(env['PUBLIC_CANISTER_ID:frontend']); // ❌ TS will show an error

Have a look at CanisterEnv for more details on how to extend the interface