Migrating

This guide explains how to migrate your bindings generation from the previous tools like dfx or didc to @icp-sdk/bindgen.

From dfx (Rust canister)

Before

If you were using dfx to generate bindings, your configuration was likely to be like this:

dfx.json

{
  "canisters": {
    "hello-world-backend": {
      "candid": "src/hello-world-backend/hello-world-backend.did",
      "package": "hello-world-backend",
      "type": "rust"
    },
    ...
  }
}

And you were generating bindings with the following command:

dfx generate

This was typically writing the bindings’ files in the src/declarations/hello-world-backend directory, unless you configured the canisters.hello-world-backend.declarations field.

After

Now, you can migrate to @icp-sdk/bindgen in CLI mode by running the following command (typically in a script in the package.json file of the frontend):

icp-bindgen --did-file ./src/hello-world-backend/hello-world-backend.did --out-dir ./src/hello-world-frontend/backend

In case you configured the canisters.hello-world-backend.declarations field, you can pass the canisters.hello-world-backend.declarations.output value to the --out-dir flag. Note that in @icp-sdk/bindgen, there’s no way to avoid generating the TypeScript declarations.

This will generate the bindings in the src/hello-world-frontend/backend directory. See the Bindings Structure page for more information on the generated files.

The same can be applied for a canister configured as type: custom in the dfx.json file.

From dfx (Motoko canister)

Before

If you were using dfx to generate bindings, your configuration was likely to be like this:

dfx.json

{
  "canisters": {
    "hello-world-backend": {
      "main": "src/hello-world-backend/main.mo",
      "type": "motoko"
    },
    ...
  }
}

And you were generating bindings with the following command:

dfx generate

This was typically writing the bindings’ files in the src/declarations/hello-world-backend directory, unless you configured the canisters.hello-world-backend.declarations field.

After

In Motoko, the Candid declaration file (.did) is generated by dfx at build time. It’s typically written in the .dfx/<network-name>/canisters/hello-world-backend/hello-world-backend.did file.

Now, you can migrate to @icp-sdk/bindgen in CLI mode by running the following commands (typically in a script in the package.json file of the frontend):

dfx build --check hello-world-backend # can be skipped if you already built the canister
icp-bindgen --did-file ./.dfx/<network-name>/canisters/hello-world-backend/hello-world-backend.did --out-dir ./src/hello-world-frontend/backend

During the build, dfx injects a $DFX_NETWORK environment variable that contains the network name, which you can use to construct the path to the .did file.

In case you configured the canisters.hello-world-backend.declarations field, you can pass the canisters.hello-world-backend.declarations.output value to the --out-dir flag. Note that in @icp-sdk/bindgen, there’s no way to avoid generating the TypeScript declarations.

This will generate the bindings in the src/hello-world-frontend/backend directory. See the Bindings Structure page for more information on the generated files.

---

For a more sophisticated approach, you can configure the canisters.hello-world-backend.declarations field to write the .did file to a directory of your choice and then use the --did-file flag to point to it. For example:

dfx.json

{
  "canisters": {
    "hello-world-backend": {
      "main": "src/hello-world-backend/main.mo",
      "type": "motoko",
      "declarations": {
        "bindings": ["did"],
        "output": "candid"
      }
    },
    ...
  }
}

And then you can run the following commands:

dfx generate --check hello-world-backend
icp-bindgen --did-file ./candid/hello-world-backend.did --out-dir ./src/hello-world-frontend/backend

From didc

Before

If you were using didc to generate bindings, you were likely running the following commands:

didc bind --target js ./service.did > ./service.did.js
didc bind --target ts ./service.did > ./service.did.d.ts

After

Now, you can migrate to @icp-sdk/bindgen in CLI mode by running the following command:

icp-bindgen --did-file ./service.did --out-dir ./service

This will generate the bindings in the service directory. See the Bindings Structure page for more information on the generated files.

Note: There’s no way to avoid generating the TypeScript declarations.