ICP JavaScript SDK Core v5.0.0 is released!

Developers JavaScript
1

We have released v5.0.0 of the ICP JavaScript SDK Core library. This major release focuses on consolidating the @icp-sdk/core package and improving it.

For detailed upgrading instructions and information about the new features, see our V5 Upgrading Guide.

What’s New

New API versions

Agent now uses the latest IC API endpoints: /api/v4 for calls and /api/v3 for queries/read_state.

Local replica upgrade required

Use dfx >=v0.30.1 or PocketIC >=v11.0.0 or pic-js >=v0.17.0.

Peer dependencies removed

The @dfinity/{agent,candid,identity,identity-secp256k1,principal} packages are no longer peer dependencies. Remove them before upgrading the core package.

Refer to the upgrading guide for more details.

The source code of the @dfinity/{agent,candid,identity,identity-secp256k1,principal} packages has also been removed from the dfinity/icp-js-core repo.

New Certificate Utility functions

We’ve added some functions to send read_state requests to subnets using the /api/v3/subnet/<effective_subnet_id>/read_state endpoint and extract data from the certificate returned by the endpoint.

Take a look at the New Features section of the upgrading guide for more details.

Minor security improvements

query and read_state response validation has been improved, strengthening certificate verification and query/read_state signature checks.

The Changelog contains a full list of all the fixes.

Packages Deprecation

This release allows us to deprecate the following packages.

@dfinity/auth-client

The @dfinity/auth-client package has been deprecated. Please migrate to @icp-sdk/auth, which version has also been upgraded to use @icp-sdk/core v5.

@dfinity/assets

The @dfinity/assets package has been deprecated. Its functionality is now part of @icp-sdk/canisters, which version has also been upgraded to use @icp-sdk/core v5.

Future Work

  • Continued improvements to the developer experience and the docs
  • Deprecation of the @dfinity/agent, @dfinity/candid, @dfinity/identity, @dfinity/identity-secp256k1 and @dfinity/principal packages
10 Likes
2

Hi DFINITY team,

I’m trying to upgrade my project & templates to use the new @icp-sdk/core v5 (as recommended in the upgrade guide) along with @ic-reactor/react v3 beta, but I’ve run into a compatibility issue with dfx-generated declarations.

The Issue

DFX version: 0.30.1
@icp-sdk/core version: 5.0.0
@icp-sdk/auth version: 5.0.0

When running dfx generate, the generated declaration files still use old @dfinity/* imports:

src/declarations/hello/index.js:

import { Actor, HttpAgent } from "@dfinity/agent";
// ...

src/declarations/hello/index.d.ts:

import type { ActorSubclass, HttpAgentOptions, ActorConfig, Agent } from "@dfinity/agent";
import type { Principal } from "@dfinity/principal";
import type { IDL } from "@dfinity/candid";

// ...

This causes build failures when the project uses @icp-sdk/core instead of @dfinity/* packages:

Error: Turbopack build failed with 1 errors:
Module not found: Can't resolve '@dfinity/agent'
> 1 | import { Actor, HttpAgent } from "@dfinity/agent";

What I’ve Tried

  1. Using npx @icp-sdk/core-migrate@latest - this only migrates imports in my own code, not the dfx-generated declarations
  2. Manually editing the declarations - but they get overwritten on every dfx generate

Questions

  1. Are there plans to update dfx to generate declarations compatible with @icp-sdk/core? Will a future version of dfx have an option to use @icp-sdk/core/* imports instead of @dfinity/*?
  2. What is the recommended workaround for now? Should we:
  • Keep @dfinity/* packages installed alongside @icp-sdk/core? (The upgrade guide mentions this for pnpm users installing peer dependencies)
  • Use bundler aliases to redirect @dfinity/* to @icp-sdk/core/*?
  • Create a post-generate script to modify the declarations?
  • Not use the dfx-generated declarations and create our own?
  1. What is the long-term vision for the relationship between dfx and @icp-sdk? As the ecosystem transitions from @dfinity/* to @icp-sdk/*, how will dfx tooling evolve to support this?

Current Workaround

For now, I’m planning to either:

  • Install @dfinity/agent, @dfinity/principal, and @dfinity/candid as peer dependencies (as mentioned in the pnpm troubleshooting section)
  • Or use bundler path aliases in next.config.js to map @dfinity/* → @icp-sdk/core/*

But I’d like to know the officially recommended approach.

Reproduction Repository

Here’s a minimal reproduction: ic-rust-nextjs template

package.json dependencies:

{
  "dependencies": {
    "@ic-reactor/react": "^3.0.0-beta.6",
    "@icp-sdk/auth": "^5.0.0",
    "@icp-sdk/core": "^5.0.0",
    "next": "^16.1.1"
  }
}

Thanks for any clarification on this matter!

2 Likes
3

Not an answer but, just wanted to let know I spotted your question and shared it with the team.

2 Likes
4

Yes, I’m working on it right now. Not sure yet how we’ll do it, but maybe we simply always generate the @icp-sdk/core imports and if you don’t want to update then you keep using old dfx versions

If you look at package.jsonin your frontend folder you can most likely see "prebuild”: “dfx generate”. I would suggest playing around with that so that you have a workflow that suits you.

Personally, I think I would change the prebuild step to something like dfx generate && find src/declarations -type f -exec sed -i '' 's|@dfinity/|@icp-sdk/core/|g' {} + (:warning: not actually tested, and sed behaves differently between macOS and Linux) until dfx generates the right bindings

1 Like
5

On the one hand this is great news, and good functionality but this will break a lot of apps, and the tooling for it seems not ready yet as @Vivienne commented at the bottom of this thread.

Is it possible to upgrade DFX to a target release BEFORE this breaking change, or the only way not to break our code is not to upgrade at all to avoid this significant upgrade effort?

If indeed we can upgrade DFX to a version before this breaking change, how can we do it, and what would be the ideal DFX target?

We have a DAPP we are working on, and we usually just upgrade DFX but for sure we will not do this now… until we fully understand how to upgrade the code, and until the utilities for this SDK are fully working.

6

So, after discussing with the team we concluded that we would simply change the imports in one of the coming releases and mark it as a breaking change, even though it will cause some upgrade work for some people.

Every patch version that we put out is guaranteed (assuming no bugs that we failed to notice…) to not break any existing workflows. So if you do not upgrade to the next minor version you are safe. Any breaking changes are labelled in the changelog, so it shouldn’t be too hard to figure out if upgrading is safe.

I plan on also suggesting the workaround I mentioned above in the changelog as a way to shim in backwards compatibility with the old packages.

It currently looks like the breaking change will happen with dfx 0.31.X, so upgrading to the currently-in-beta 0.30.2 will still be safe.

1 Like
7

What about @dfinity/utils ?

8

I’m not aware of plans to do anything with @dfinity/utils, at least for now

1 Like
9

If you are asking why it is still a standalone library, it felt like it should not be part of @icp-sdk/core nor @icp-sdk/canisters, but rather something like @icp-sdk/something (replace “something” with “tools”, “utils”, or a better naming idea). So we left it on the side for now.

We won’t forget it though, we (myself included) use it everywhere in our apps.

When it comes to the dependency on core/AgentJS, it was already upgraded to support @icp-sdk/core v3, then v4 and then latest v5.

4 Likes
10

Thanks Vivienne, this helps plan our upgrade efforts, and upgrade carefully forward.

For anyone interested in this topic the DFX release notes are here:

Upgrade carefully… for now it seems the breaking change is not here yet.

1 Like