Add three build profiles and infrastructure for their toml config - [fitzgen], [issue/153] [issue/160] [pull/440]
When originally conceived,
wasm-pack was exclusively a packaging and publishing tool, which naively assumed that the crate author would simply run
wasm-pack when they were ready to publish a wasm package. As a result,
wasm-pack always ran
cargo build in
--release mode. Since then,
wasm-pack has grown into an integrated build tool used at all stages of development, from idea conception to publishing, and as such has developed new needs.
In previous releases, we've supported a flag called
--debug which will run
cargo build in
dev mode, which trades faster compilation speed for a lack of optimizations. We've renamed this flag to
--dev to match
cargo and added an additional flag, representing a third, intermediary, build profile, called
--profiling which is useful for investigating performance issues. You can see all three flags and their uses in the table below:
| Profile | Debug Assertions | Debug Info | Optimizations | Notes |
--dev | Yes | Yes | No | Useful for development and debugging. |
--profiling | No | Yes | Yes | Useful when profiling and investigating performance issues. |
--release | No | No | Yes | Useful for shipping to production. |
The meaning of these flags will evolve as the platform grows, and always be tied to the behavior of these flags in
cargo. You can learn more about these in the [
cargo profile documentation].
This PR also introduces a way to configure
wasm-pack in your
Cargo.toml file that we intend to use much more in the future. As a largely convention-based tool,
wasm-pack will never require that you configure it manually, however, as our community and their projects mature alongside the tool, it became clear that allowing folks the ability to drop down and configure things was something we needed to do to meet their needs.
Currently, you can only configure things related to the above-mentioned build profiles. To learn more, check out the documentation. It leverages the
package.metadata.wasm-pack key in your
Cagol.toml, and looks like this:
# Should we enable wasm-bindgen's debug assertions in its generated JS glue?
debug-js-glue = true
# Should wasm-bindgen demangle the symbols in the "name" custom section?
demangle-name-section = true
# Should we emit the DWARF debug info custom sections?
dwarf-debug-info = false
As always- there are defaults for you to use, but if you love to configure (or have a project that requires it), get excited, as your options have grown now and will continue to!
cargo profile documentation]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-profile-sections
--dev to match
cargo - [fitzgen], pull/439
See the discussion of the build profiles feature above. This is a strict renaming of the previous
--debug flag, which will now warn as deprecated.
Add an option to pass an arbitrary set of arguments to
cargo build - [torkve], [issue/455] [pull/461]
As an integrated build tool,
wasm-pack orchestrates many secondary command line tools to build your package in a single command. Notably, one of these tools is
cargo has a wide array of features and flags, and we couldn't reasonably expect to implement them all as first class features of
wasm-pack. As a result, we've created the option to allow users to pass an arbitrary number of additional flags to
wasm-pack by appending them to the
wasm-pack build command, after passing
--. For example:
wasm-pack build examples/js-hello-world --mode no-install -- -Z offline
In the above example, the flag
-Z offline will be passed to
cargo build. This feature is documented here.
Pre-build before wasm-pack publish - [csmoe], issue/438 [pull/444]
Previously, if you ran
wasm-pack publish before you had successfully run
you'd receive an error that a package could not be found- because there would be no
out-directory containing a
In this situation, you would hope that
wasm-pack would build your package for you when you
wasm-pack publish. This is slightly complicated by the fact that not everyone wants to
build their package to the default target or to a directory named
To solve this, running
wasm-pack publish before a successful build will give you an interactive
prompt to build your package- allowing you to specify your out directory as well as the target you'd
like to build to. Check it out in the gif below:
Generate self-.gitignore as part of pkg folder - RReverser, [pull/453]
wasm-pack was first published, the
pkg directory was intended to be treated as a build artifact, and as such should never be published to version control. This was never enforced by any assets generated by
Now, when building your package,
wasm-pack will also generate a
.gitignore file so that the
pkg, or out-directory, will be ignored.
If you use another version control tool, you'll need to still create or edit your own ignore file- pull requests to support other version control tools are welcome!
If you require editing of the generated
package.json or add additonal assets to your package before publishing, you'll want to remove the
.gitignore file and commit to version control. We intend to have a solution that makes this workflow significantly easier in upcoming releases!
Support cargo workspaces - [fitzgen], issue/252 [issue/305] [pull/430]
Workspaces are a well-liked and used feature of cargo that allow you to build multiple crates in a single cargo project. Because of how
wasm-pack handled paths for
target and out-directories, we did not support cargo workspaces out of the box. Now they should work well and the feature is well guarded by tests!
Use a global cache for all downloaded binaries - [alexcrichton], [pull/426]
wasm-pack is an integrated build tool that orchestrates several other command line tools to build your wasm project for you. How
wasm-pack does this has evolved significantly since it's early versions. In the last version, a
bin directory was created to house the tool binaries that
wasm-pack needed to build our project, but this had several limitations. Firstly, it created a
bin directory in your project's root, which could be confusing. Secondly, it meant that sharing these tools across multiple projects was not possible. We did this because it gaves us the fine-grained control over the version of these tools that you used.
wasm-pack will not generate a
bin directory, but rather will use a global cache. We retain the fine-grained control over the versions of these tools that are used, but allow multiple projects that use the same tools at the same versions to share the already installed asset. Your global cache will generally be in your user's home directory- we use the
dirs crate to determine where to place this global cache. This is not currently customizable but is something we intend to look into doing!
This feature ensures that
wasm-pack users are downloading a minimal number of binaries from the network, which, for
wasm-pack users with multiple projects, should speed up build times.