build: Add `js` Cargo feature flag for WASM builds by lpahlavi · Pull Request #118 · anza-xyz/solana-sdk

lpahlavi · 2025-04-02T10:56:07Z

Previously, the wasm32 target implicitly assumed a browser environment, which caused issues when building for non-browser WASM environments due to the unconditional inclusion of wasm-bindgen.

This commit introduces an explicit js feature flag, making wasm-bindgen and js-sys conditional dependencies. This allows greater flexibility for different WASM execution environments.

Related to #117

Previously, the wasm32 target implicitly assumed a browser environment, which caused issues when building for non-browser WASM environments due to the unconditional inclusion of `wasm-bindgen`. This commit introduces an explicit 'js' feature flag, making `wasm-bindgen` and `js-sys` conditional dependencies. This allows greater flexibility for different WASM execution environments. Related to anza-xyz#117

apfitzge · 2025-04-02T14:46:15Z

@joncinque requesting your review on this since you just did the feature powerset change. I don't have a strong opinion, if you're okay w/ it I will sign-off on it for the tx-metadata team.

joncinque

Thanks for your contribution! I'm in agreement for this change, makes total sense to me.

The main issue: I believe this is a breaking change for people currently using the packages in wasm builds, since they're expecting all of the JS stuff to come with it. That's unfortunately going to complicate / slow down the release process a bit.

Also, in all the Cargo.tomls, we should keep gating the js-sys and wasm-bindgen crates on:

[target.'cfg(target_family = "wasm")'.dependencies]

As another note, I looked around at different feature names used for enabling JS for wasm builds, and here are some popular crates:

getrandom uses wasm_js
time uses wasm-bindgen as the feature name
chrono uses wasmbind
uuid and jiff use js

So your choice of js is good, but I could also be convinced to do something like wasm-js if you liked that more.

joncinque · 2025-04-02T21:28:42Z

+wasm-bindgen = { workspace = true, optional = true }

 [dev-dependencies]
 solana-hash = { path = ".", features = ["dev-context-only-utils"] }


I can't comment lower down, but can you remove js-sys and wasm-bindgen from the wasm32 dependencies on lines 38-40?

As per your suggestion, I've moved all the dependencies for the new js feature back to a section gated by the target_arch = "wasm32".

joncinque · 2025-04-02T21:42:19Z

@@ -19,7 +19,7 @@ use {
    },


I can't comment further up on line 6, but does a non-JS wasm build always need std? We might be able to change the std usage to:

#[cfg(feature = "std")]

Maybe more specifically -- does a wasm build like yours need std by default? And if we simplify that feature, then we shoudl also remove the target_arch bit on line 12.

Good question! In our particular case, we actually do always use std for non-JS builds, but I think what makes most sense here is probably to change most usages of target_arch = "wasm32" to feature = "js". I tried to have a look in each affected file where the std dependencies where needed and I tried to make it so that when the std imports were only needed in code gated by the js feature, I changed target_arch = "wasm32" to feature = "js", and otherwise I removed the gate on the target architecture. WDYT?

joncinque · 2025-04-02T22:41:14Z

@@ -31,7 +31,7 @@ use {
    num_traits::{FromPrimitive, ToPrimitive},


Same bit at the top, lines 7 and 15, changing to

#[cfg(feature = "std")]

joncinque · 2025-04-02T22:43:20Z

+#[cfg_attr(feature = "js", wasm_bindgen)]
 #[repr(transparent)]
 #[cfg_attr(feature = "frozen-abi", derive(solana_frozen_abi_macro::AbiExample))]
 #[cfg_attr(


I can't comment there, but there's a TryFrom<Vec<u8>> for Pubkey impl around line 429 and some gating around new_unique() (lines 483), and we should change the gating to just:

#[cfg(feature = "std")]

Good catch! Done.

joncinque · 2025-04-02T22:45:22Z

    std::string::ToString::to_string(&display).into()
 }

-#[allow(non_snake_case)]


We'll still need the allow(non_snake_case) directive

Ah I mistakenly seem to have deleted #[allow(non_snake_case)] instead of #[cfg(target_arch = "wasm32")]. Thanks for noticing this! It is now fixed.

joncinque · 2025-04-02T22:47:39Z


-#[allow(non_snake_case)]
+#[cfg(feature = "js")]
 #[cfg(target_arch = "wasm32")]


We can probably remove this since the js feature gates it

Absolutely! Done.

joncinque · 2025-04-02T23:09:29Z

    solana_sanitize::Sanitize,
 };
-#[cfg(target_arch = "wasm32")]
+#[cfg(feature = "js")]


Assuming that we gate std just on the std feature, let's gate this properly with:

#[cfg(all(feature = "std", feature = "js"))]

For reference, I'm looking at how uuid declares something similar here: https://github.com/uuid-rs/uuid/blob/cb19a46cf17cd9840205e0d67a32ea8a18e58374/src/timestamp.rs#L308

I don't think we need the full target_arch part too, but the std + js feature gate seems to make sense

joncinque · 2025-04-02T23:10:44Z

 impl_borsh_serialize!(borsh0_10);

-#[cfg(all(target_arch = "wasm32", feature = "curve25519"))]
+#[cfg(all(feature = "js", feature = "curve25519"))]


This one will also need the std feature

Good catch! Done.

joncinque · 2025-04-02T23:11:34Z

 }

-#[allow(non_snake_case)]
+#[cfg(feature = "js")]


This will also need the std feature

Good catch! Done.

joncinque · 2025-04-02T23:11:45Z

 }

-#[cfg(target_arch = "wasm32")]
+#[cfg(feature = "js")]


This will also need the std feature

Good catch! Done.

lpahlavi

@joncinque Thank you so much for reviewing this PR so quickly!

I am aware that this will unfortunately be breaking... I believe due to Cargo's limitation to opt-in only features, there's not much we can do to mitigate this. I thought about adding the feature to default since the dependencies are anyways gated by the wasm32 target architecture, but this seems a little bit awkward. WDYT?

I am also wondering if it would be theoretically best to add target_arch = "wasm32" to all the places where we have feature = "js" or if we are OK with the code simply not compiling when having the js feature enabled for another target architecture than wasm32. Do you have an opinion on this?

One final question: do you have any idea how long it might take before this is released given that it involves a breaking change?

Thanks again and let me know if you have any further feedback!

lpahlavi · 2025-04-04T09:43:26Z

    std::string::ToString::to_string(&display).into()
 }

-#[allow(non_snake_case)]


Ah I mistakenly seem to have deleted #[allow(non_snake_case)] instead of #[cfg(target_arch = "wasm32")]. Thanks for noticing this! It is now fixed.

lpahlavi · 2025-04-04T09:43:45Z


-#[allow(non_snake_case)]
+#[cfg(feature = "js")]
 #[cfg(target_arch = "wasm32")]


Absolutely! Done.

lpahlavi · 2025-04-04T13:11:14Z

+wasm-bindgen = { workspace = true, optional = true }

 [dev-dependencies]
 solana-hash = { path = ".", features = ["dev-context-only-utils"] }


As per your suggestion, I've moved all the dependencies for the new js feature back to a section gated by the target_arch = "wasm32".

lpahlavi · 2025-04-04T13:13:25Z

@@ -19,7 +19,7 @@ use {
    },


Good question! In our particular case, we actually do always use std for non-JS builds, but I think what makes most sense here is probably to change most usages of target_arch = "wasm32" to feature = "js". I tried to have a look in each affected file where the std dependencies where needed and I tried to make it so that when the std imports were only needed in code gated by the js feature, I changed target_arch = "wasm32" to feature = "js", and otherwise I removed the gate on the target architecture. WDYT?

lpahlavi · 2025-04-04T13:41:16Z

@@ -31,7 +31,7 @@ use {
    num_traits::{FromPrimitive, ToPrimitive},


lpahlavi · 2025-04-04T13:42:27Z

+#[cfg_attr(feature = "js", wasm_bindgen)]
 #[repr(transparent)]
 #[cfg_attr(feature = "frozen-abi", derive(solana_frozen_abi_macro::AbiExample))]
 #[cfg_attr(


Good catch! Done.

lpahlavi · 2025-04-04T13:43:18Z

 impl_borsh_serialize!(borsh0_10);

-#[cfg(all(target_arch = "wasm32", feature = "curve25519"))]
+#[cfg(all(feature = "js", feature = "curve25519"))]


Good catch! Done.

lpahlavi · 2025-04-04T13:45:50Z

 }

-#[allow(non_snake_case)]
+#[cfg(feature = "js")]


Good catch! Done.

lpahlavi · 2025-04-04T13:46:00Z

 }

-#[cfg(target_arch = "wasm32")]
+#[cfg(feature = "js")]


Good catch! Done.

joncinque · 2025-04-07T23:28:11Z

I am aware that this will unfortunately be breaking... I believe due to Cargo's limitation to opt-in only features, there's not much we can do to mitigate this. I thought about adding the feature to default since the dependencies are anyways gated by the wasm32 target architecture, but this seems a little bit awkward. WDYT?

That would still be breaking for users of default-features = false, but since that likely narrows the scope of users down a lot, maybe we can do it just this once. We'd be breaking wasm users with default-features = false, which should be a tiny fraction.

The other option, which is unfortunately a lot of work, is to use the semver trick for all these crates: https://github.com/dtolnay/semver-trick. We can have the v2 crates depend on the v3 crates with the correct feature, and then re-export everything, but to be totally honest, I'm not too keen on doing all of that.

I am also wondering if it would be theoretically best to add target_arch = "wasm32" to all the places where we have feature = "js" or if we are OK with the code simply not compiling when having the js feature enabled for another target architecture than wasm32. Do you have an opinion on this?

Yes, after thinking about it a bit more, let's do what you suggested and also gate all js usage on the wasm32 check.

One final question: do you have any idea how long it might take before this is released given that it involves a breaking change?

I'm still figuring out the exact release process, and I need to coordinate with some of our downstream users, so it might take a month before the crates are released.

lpahlavi · 2025-04-08T13:27:02Z

@joncinque Thanks a lot for your feedback!

Given your feedback, I've now:

added the js feature to the default features for all affected crates
made sure that dependencies are included with the js feature only if the js feature is enabled
gated all wasm_bingen related functionality by both the js feature and the wasm32 target architecture

I believe this way we should minimize the number of affected users (i.e. only the ones using wasm_bindgen with default-features = false) while still avoiding having to resort to the semver trick (I'm also not too keen on resorting to that...).

I'm still figuring out the exact release process, and I need to coordinate with some of our downstream users, so it might take a month before the crates are released.

Thank you for the info! That should be completely fine for us as we can rely on the forked repository in the meantime. Let me know if there's anything I can do to support on that side.

Let me know if you have any other feedback concerning the code!

lpahlavi · 2025-05-09T12:13:46Z

@joncinque May I ask if there is an updated timeline on when the breaking changes should be released? Thanks!

joncinque · 2025-05-09T12:55:24Z

We've been discussing this a bit offline and in Discord (https://discord.com/channels/428295358100013066/476811830145318912/1369891812797452288), and I'm starting to lean towards a slightly different solution, of just removing all of the wasm-bindgen code completely from the component crates, and instead factoring it all into a new crate, as in #138

We've been sidetracked by some other things, so at the latest, the breaking changes should be released by the end of the month.

lpahlavi · 2025-05-09T13:25:10Z

Thanks a lot for the quick reply!

We've been discussing this a bit offline and in Discord (https://discord.com/channels/428295358100013066/476811830145318912/1369891812797452288), and I'm starting to lean towards a slightly different solution, of just removing all of the wasm-bindgen code completely from the component crates, and instead factoring it all into a new crate, as in #138

I see, thanks for the link! Unfortunately it seems I don't have access to the #sdk channel so I can't check out the details, but in principle the idea sounds good as well to me and I don't have a particularly strong preference for one or the other option.

Would someone from Anza then take the lead in this case?

We've been sidetracked by some other things, so at the latest, the breaking changes should be released by the end of the month.

I see no problem, thank you for the update! Do you know if there is somewhere I can follow this more closely?

joncinque · 2025-05-09T13:37:37Z

I'll repost the most relevant comment:

I really don’t think there is a single person who throws wasm bindgen into an isomorphic library and thinks “you know what my binary needs? 50 random unused additional functions that only work in the runtime”
context: https://x.com/deanmlittle/status/1917987491614974329?s=46&t=Y1-eTu6GZzzEk5uEf3Rs1Q

And yes, we'll take the lead on this from here, most likely in #138 -- that'll be the PR to follow. It should end up being much simpler since we're just ~~removing~~ edit: moving everything. Otherwise, you can see updates on the breaking changes issue #84

lpahlavi · 2025-05-09T13:44:52Z

Fantastic, thanks a lot! Looking forward to the release!

Do you have any idea if the solana-program/system repo will head in the same direction (see this issue, essentially a clone of #117)? I ask because it seems that you are also a major contributor there and the problem is essentially the same as here.

joncinque · 2025-05-12T22:45:20Z

Do you have any idea if the solana-program/system repo will head in the same direction (see this solana-program/system#47, essentially a clone of #117)?

Yeah, we should probably do the same thing everywhere

lpahlavi · 2025-05-13T05:54:19Z

Great, thank you! I will update the issue there to reflect this.

lpahlavi · 2025-06-03T13:29:47Z

Hi @joncinque! Do you know if there are any updates on the progress for the next release including the breaking changes? Perhaps I could get an invite to the Discord channel to follow the news there? Thanks!

joncinque · 2025-06-05T23:55:03Z

Sorry for the late reply, we'll start landing some breaking changes first thing next week and probably releasing some 3.0.0-rc.1 crates for people to test with by the end of the week

lpahlavi · 2025-06-07T08:22:52Z

Thanks a lot for the heads up! I've been monitoring the repo a bit and see that the first breaking changes look to be soon merged. Looking forward to testing the first release candidates!

lpahlavi · 2025-06-16T06:00:15Z

@joncinque @LucasSte : I've noticed that the PR to add a WASM crate (here) doesn't quite allow removing all wasm-bindgen dependencies (yet). Is the idea to also merge this PR here adding a feature flag, or do you expect to create some new PRs to remove the other wasm-bindgen dependencies?

joncinque · 2025-06-20T16:34:31Z

That's correct, after that PR lands, the idea is to just move all of the wasm logic from the individual crates and into solana-sdk-wasm-js

lpahlavi · 2025-06-23T07:24:18Z

That's correct, after that PR lands, the idea is to just move all of the wasm logic from the individual crates and into solana-sdk-wasm-js

Great, thanks a lot for the confirmation @joncinque! Just to clarify the timeline though, is this planned to be all part of the upcoming release? Or is this a longer term plan?

#### Problem As outlined in anza-xyz#118, the sdk incorrectly assumes that all wasm builds are targeting a js environment, which breaks builds in non-js targets. #### Summary of changes The wasm-js code isn't strictly needed to make things work, so instead, move all of the code into different modules. This causes some copy-pasta, but keeps wasm builds lean. If people are using wasm-js, most likely they'll roll their own code anyway. As part of this, since solana-keypair now uses rand 0.8, we can upgrade the getrandom backend to 0.2.

joncinque · 2025-07-23T22:01:38Z

Sorry for the wait! #244 will finally take care of this

wasm-js: Move all implementations into sdk-wasm-js #### Problem As outlined in #118, the sdk incorrectly assumes that all wasm builds are targeting a js environment, which breaks builds in non-js targets. #### Summary of changes The wasm-js code isn't strictly needed to make things work, so instead, move all of the code into different modules. This causes some copy-pasta, but keeps wasm builds lean. If people are using wasm-js, most likely they'll roll their own code anyway. As part of this, since solana-keypair now uses rand 0.8, we can upgrade the getrandom backend to 0.2.

wasm-js: Move all implementations into sdk-wasm-js As outlined in anza-xyz#118, the sdk incorrectly assumes that all wasm builds are targeting a js environment, which breaks builds in non-js targets. The wasm-js code isn't strictly needed to make things work, so instead, move all of the code into different modules. This causes some copy-pasta, but keeps wasm builds lean. If people are using wasm-js, most likely they'll roll their own code anyway. As part of this, since solana-keypair now uses rand 0.8, we can upgrade the getrandom backend to 0.2.

gregorydemay mentioned this pull request Apr 2, 2025

Target architecture wasm32 should not assume a Javascript environment #117

Closed

lpahlavi mentioned this pull request Apr 2, 2025

build: migrate dependencies to solana-sdk repository dfinity/sol-rpc-canister#55

Merged

lpahlavi marked this pull request as ready for review April 2, 2025 14:05

lpahlavi requested a review from a team as a code owner April 2, 2025 14:05

apfitzge requested a review from joncinque April 2, 2025 14:45

joncinque reviewed Apr 2, 2025

View reviewed changes

lpahlavi added 4 commits April 4, 2025 11:47

Order features alphabetically

feb600d

Fix deleted #[allow(non_snake_case)]

fd92fd9

Gate js feature dependencies with wasm32 target_arch

db2b409

Simplify std gated imports

7eafb82

lpahlavi commented Apr 4, 2025

View reviewed changes

lpahlavi added 2 commits April 7, 2025 15:24

Remove unnecessary 'any'

b15c25c

Change 'all' to 'any'

c800e7c

lpahlavi mentioned this pull request Apr 7, 2025

build: Add js Cargo feature flag for WASM builds solana-program/system#48

Closed

lpahlavi added 2 commits April 8, 2025 15:01

Also gate javascript features with target_arch

4e12c10

Add 'js' to default features

616d0ef

joncinque added the breaking PR contains breaking changes label Apr 21, 2025

joncinque mentioned this pull request Apr 21, 2025

v3: Tracking issue for upcoming breaking changes #84

Closed

lpahlavi mentioned this pull request May 5, 2025

Target architecture wasm32 should not assume a Javascript environment solana-program/system#47

Closed

Cargo sort

58a34db

joncinque mentioned this pull request Jul 16, 2025

Remove some unused dependencies #228

Merged

joncinque mentioned this pull request Jul 23, 2025

wasm-js!: Move all implementations into sdk-wasm-js #244

Merged

joncinque closed this in #244 Jul 28, 2025

		@@ -31,7 +31,7 @@ use {
		num_traits::{FromPrimitive, ToPrimitive},

Conversation

lpahlavi commented Apr 2, 2025

Uh oh!

apfitzge commented Apr 2, 2025

Uh oh!

joncinque left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lpahlavi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joncinque commented Apr 7, 2025

Uh oh!

lpahlavi commented Apr 8, 2025

Uh oh!

lpahlavi commented May 9, 2025

Uh oh!

joncinque commented May 9, 2025

Uh oh!

lpahlavi commented May 9, 2025

Uh oh!

joncinque commented May 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joncinque commented May 9, 2025 •

edited

Loading

lpahlavi commented Jun 16, 2025 •

edited

Loading