build - Hello wasm-pack! (original) (raw)

  1. 1. Introduction
  2. 2. Quickstart
  3. 3. Prerequisites
    1. 3.1. npm (optional)
    2. 3.2. considerations
    3. 3.3. Non-rustup setups
  5. 4. Commands
    1. 4.1. new
    2. 4.2. build
    3. 4.3. test
    4. 4.4. pack and publish
    5. 4.5. init (DEPRECATED)
  7. 5. Tutorials
    1. 5.1. Hybrid applications with Webpack
      1. 5.1.1. Getting started
        1. 5.1.2. Using your library
    3. 5.2. npm browser packages
      1. 5.2.1. Getting started
          1. 5.2.1.1. Manual Setup
        2. 5.2.2. Template deep dive
          1. 5.2.2.1. Cargo.toml
            1. 5.2.2.2. src/lib.rs
            2. 5.2.2.3. src/utils.rs
            3. 5.2.2.4. wee_alloc
            4. 5.2.2.5. tests/web.rs
        4. 5.2.3. Building your project
        5. 5.2.4. Testing your project
        6. 5.2.5. Packaging and publishing
        7. 5.2.6. Using your library
  9. 6. Cargo.toml Configuration
  10. 7. Contributing

Hello wasm-pack!

wasm-pack build

The wasm-pack build command creates the files necessary for JavaScript interoperability and for publishing a package to npm. This involves compiling your code to wasm and generating a pkg folder. This pkg folder will contain the wasm binary, a JS wrapper file, your README, and a package.json file.

The pkg directory is automatically .gitignored by default, since it contains build artifacts which are not intended to be checked into version control.0

Path

The wasm-pack build command can be given an optional path argument, e.g.:

wasm-pack build examples/js-hello-world

This path should point to a directory that contains a Cargo.toml file. If no path is given, the build command will run in the current directory.

Output Directory

By default, wasm-pack will generate a directory for its build output called pkg. If you'd like to customize this you can use the --out-dir flag.

wasm-pack build --out-dir out

The above command will put your build artifacts in a directory called out, instead of the default pkg.

Generated file names

Flag --out-name sets the prefix for output file names. If not provided, package name is used instead.

Usage examples, assuming our crate is named dom:

wasm-pack build
# will produce files
# dom.d.ts  dom.js  dom_bg.d.ts  dom_bg.wasm  package.json  README.md

wasm-pack build --out-name index
# will produce files
# index.d.ts  index.js  index_bg.d.ts  index_bg.wasm  package.json  README.md

Profile

The build command accepts an optional profile argument: one of --dev,--profiling, or --release. If none is supplied, then --release is used.

This controls whether debug assertions are enabled, debug info is generated, and which (if any) optimizations are enabled.

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 --dev profile will build the output package using cargo's default non-release profile. Building this way is faster but applies few optimizations to the output, and enables debug assertions and other runtime correctness checks. The --profiling and --release profiles use cargo's release profile, but the former enables debug info as well, which helps when investigating performance issues in a profiler.

The exact meaning of the profile flags may evolve as the platform matures.

Target

The build command accepts a --target argument. This will customize the JS that is emitted and how the WebAssembly files are instantiated and loaded. For more documentation on the various strategies here, see the documentation on using the compiled output.

wasm-pack build --target nodejs
Option Usage Description
not specified or bundler Bundler Outputs JS that is suitable for interoperation with a Bundler like Webpack. You'll import the JS and the module key is specified in package.json. sideEffects: false is by default.
nodejs Node.js Outputs JS that uses CommonJS modules, for use with a require statement. main key in package.json.
web Native in browser Outputs JS that can be natively imported as an ES module in a browser, but the WebAssembly must be manually instantiated and loaded.
no-modules Native in browser Same as web, except the JS is included on a page and modifies global state, and doesn't support as many wasm-bindgen features as web
deno Deno Outputs JS that can be natively imported as an ES module in deno.

Scope

The build command also accepts an optional --scope argument. This will scope your package name, which is useful if your package name might conflict with something in the public registry. For example:

wasm-pack build examples/js-hello-world --scope test

This command would create a package.json file for a package called@test/js-hello-world. For more information about scoping, you can refer to the npm documentation here.

Mode

The build command accepts an optional --mode argument.

wasm-pack build examples/js-hello-world --mode no-install
Option Description
no-install wasm-pack build implicitly and create wasm binding without installing wasm-bindgen.
normal do all the stuffs of no-install with installed wasm-bindgen.

Extra options

The build command can pass extra options straight to cargo build even if they are not supported in wasm-pack. To use them simply add the extra arguments at the very end of your command, just as you would for cargo build. For example, to build the previous example using cargo's offline feature:

wasm-pack build examples/js-hello-world --mode no-install -- --offline

0 If you need to include additional assets in the pkg directory and your NPM package, we intend to have a solution for your use case soon. ↩