Overview

Experimental

See

https://js.icp.build/core/latest/canister-environment

Interfaces

CanisterEnv

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

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/core/src/agent/canister-env/index.ts:66

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.

---

GetCanisterEnvOptions

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

Experimental

Options for the getCanisterEnv function

Properties

cookieName?

optional cookieName?: string

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

Experimental

The name of the cookie to get the environment variables from.

Default

'ic_env'

Functions

getCanisterEnv()

getCanisterEnv<T>(options?): CanisterEnv & T

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

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

---

safeGetCanisterEnv()

safeGetCanisterEnv<T>(options?): CanisterEnv & T | undefined

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

Experimental

Safe version of getCanisterEnv that returns undefined instead of throwing errors.

Type Parameters

T

T = Record<string, never>

Parameters

options?

GetCanisterEnvOptions = {}

The options for loading the asset canister environment variables

Returns

CanisterEnv & T | undefined

The environment variables for the asset canister, or undefined if any error occurs

See

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

Example

// in a browser environment with valid cookie
const env = safeGetCanisterEnv();
console.log(env); // { IC_ROOT_KEY: Uint8Array, ... }

// in a Node.js environment
const env = safeGetCanisterEnv();
console.log(env); // undefined

// in a browser without the environment cookie
const env = safeGetCanisterEnv();
console.log(env); // undefined