ic0

ic0  

An easy-to-use JavaScript API for the Internet Computer.

---

The ic0 npm package makes it easier to interact with Internet Computer (IC) canisters from development and testing environments.

Installation

npm i --save ic0

Quick Start

Add the following code to your webapp (works out of the box when hosted on the IC):

import ic from 'ic0';

const ledger = ic('ryjl3-tyaaa-aaaaa-aaaba-cai'); // Access the IC ledger canister

console.log(await ledger.call('name')) // Call (or query) the `name` method

Replica Canisters

A replica canister represents a live canister running on the IC (or local replica), identified by a unique Principal.

Basic usage:

import { replicaCanister } from 'ic0';

const principal = 'ryjl3-tyaaa-aaaaa-aaaba-cai'; // Canister ID (Principal)
const ledger = replicaCanister(principal);

console.log(await ledger.call('name')) // => { name: 'Internet Computer' }

Advanced usage:

Replica canisters use agent-js behind the scenes.

import { replicaCanister } from 'ic0';
import { HttpAgent } from '@dfinity/agent';

const principal = 'ryjl3-tyaaa-aaaaa-aaaba-cai';
const agent = new HttpAgent({ host: ... }); // Use a custom agent from `agent-js`

const ledger = replicaCanister(principal, agent);

console.log(await ledger.call('name')); // => { name: 'Internet Computer' }

Dev Canisters

A dev canister makes it possible to interact with canisters provided by a live-reload development environment such as the Motoko Dev Server.

Basic usage:

import { devCanister } from 'ic0';

const backend = devCanister('backend'); // Canister alias specified in your `dfx.json` file

console.log(await backend.call('getValue')); // Call the `getValue()` method on your `backend` canister

Advanced usage:

This package makes it possible to seamlessly switch between devCanister and replicaCanister depending on the environment.

For example, you can use the import.meta.env property available in Vite:

import { devCanister, replicaCanister } from 'ic0';

const backend = import.meta.env.DEV
    ? devCanister('backend')
    : replicaCanister('rrkah-fqaaa-aaaaa-aaaaq-cai'); // Deployed canister Principal

console.log(await backend.call('getValue')); // Call the `getValue()` method on the deployed canister when in production

Mock Canisters

A mock canister makes it easy to mock the behavior of your canisters for unit tests.

Basic usage:

import { mockCanister } from 'ic0';

const mock = mockCanister({
    // Mock canister method named `echo()`
    async echo(x: number) {
        return x;
    }
});

console.log(await mock.call('echo', 123)); // => 123

Advanced usage:

Provide a fallback canister and/or compose several mocks by passing a second argument to the mockCanister() function:

import { mockCanister, replicaCanister } from 'ic0';

const ledger = replicaCanister(principal, agent);

const mockLedger = mockCanister({
    async echo(x: number) {
        return x;
    }
}, ledger); // Fall back to the deployed `ledger` canister

const mock = mockCanister({
    async runMock() {
        return this.call('echo', 456); // Call the mocked `echo()` function
    }
}, mockLedger); // Fall back to another mock canister

console.log(await mock.call('runMock')); // => 456