Upgrading to @icp-sdk/core

The new @icp-sdk/core package is made up of multiple submodules, each of which contains the functionality of the respective old @dfinity/... package.

Automatic

We provide a CLI tool to automatically upgrade your code to use the new package.

Simply run the following command in the root of your project:

npx @icp-sdk/core-migrate@latest

For more migration options, run npx @icp-sdk/core-migrate@latest --help.

Manual

Everything previously exported from the individual @dfinity/* packages is now exported from a @icp-sdk/core/* submodule.

Remove the following packages, if present:
- @dfinity/agent
- @dfinity/candid
- @dfinity/identity
- @dfinity/identity-secp256k1
- @dfinity/principal
E.g.
Terminal window
```
npm remove @dfinity/{agent,candid,identity,identity-secp256k1,principal}
```
Install the new @icp-sdk/core package:
Terminal window
```
npm i @icp-sdk/core
```

Replace old imports with new imports, if present:

Old Import	New Import
`@dfinity/agent`	`@icp-sdk/core/agent`
`@dfinity/candid`	`@icp-sdk/core/candid`
`@dfinity/identity`	`@icp-sdk/core/identity`
`@dfinity/identity-secp256k1`	`@icp-sdk/core/identity/secp256k1`
`@dfinity/principal`	`@icp-sdk/core/principal`

E.g.

- import { HttpAgent } from '@dfinity/agent';
+ import { HttpAgent } from '@icp-sdk/core/agent';

Troubleshooting

TypeScript `moduleResolution`

If you’re using TypeScript, you need to set the moduleResolution to either node16, nodenext or bundler in your tsconfig.json file.

{
  "compilerOptions": {
    "moduleResolution": "node16"
  }
}

Using agent-js v2

If you’re using agent-js v2, you need to upgrade to v3 before upgrading to @icp-sdk/core. You can find the release notes here.

Workspaces

If you’re using a workspace, you must run the migration tool for each package in the workspace that has any @dfinity/* dependencies. You may need to first uninstall the @dfinity/* packages manually from all the packages in the workspace before running the migration tool, to avoid version conflicts.

A similar approach can be used for monorepos.

Tree-shaking

Tree-shaking is supported, so you can import only the submodules you need and your bundler will automatically remove the unused code.

Using `@dfinity/*` packages in other places than imports

The @icp-sdk/core-migrate CLI tool only replaces the @dfinity/* occurrences in imports. If you are using @dfinity/* packages somewhere else in your code, e.g. in tests mocks, you will need to find and replace the occurrences manually.

E.g.

 vi.mock('@dfinity/agent', () => ({
 vi.mock('@icp-sdk/core/agent', () => ({
  ...
}));

`@dfinity/assets` and `@dfinity/auth-client`

The @dfinity/assets and @dfinity/auth-client packages are not included in @icp-sdk/core. They will be included in other @icp-sdk/* packages in the near future. For now, you can still use them.

`@dfinity/use-auth-client`

The @dfinity/use-auth-client package is not included in @icp-sdk/core and has been deprecated. Please consider using other libraries instead. Recommended alternatives:

Installing with pnpm

If you’re using pnpm, you might need to install the peer dependencies of @icp-sdk/core manually:

pnpm install @dfinity/agent @dfinity/candid @dfinity/identity @dfinity/identity-secp256k1 @dfinity/principal

Building libraries with Rollup/Vite

If you’re building a library that depends on @icp-sdk/core, you need to specify each submodule you’re using in your Rollup configuration (this also applies to Vite, which uses Rollup under the hood):

rollupOptions: {
  external: [
    '@icp-sdk/core/agent',
    '@icp-sdk/core/candid',
    '@icp-sdk/core/identity',
    '@icp-sdk/core/identity/secp256k1',
    '@icp-sdk/core/principal',
  ],
  output: {
    globals: {
      '@icp-sdk/core/agent': 'icp-sdk-core-agent',
      '@icp-sdk/core/candid': 'icp-sdk-core-candid',
      '@icp-sdk/core/identity': 'icp-sdk-core-identity',
      '@icp-sdk/core/identity/secp256k1': 'icp-sdk-core-identity-secp256k1',
      '@icp-sdk/core/principal': 'icp-sdk-core-principal',
    },
  },
},