From a467b0191bc8b61086d6e66a7eb3fa8e005e91ca Mon Sep 17 00:00:00 2001 From: Thierry Berger Date: Thu, 5 Jun 2025 16:53:23 +0200 Subject: [PATCH 1/3] chapter on javascript size guidelines (unlinked yet) --- docs/user_guides/templates/wasm_size_js.mdx | 85 +++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/user_guides/templates/wasm_size_js.mdx diff --git a/docs/user_guides/templates/wasm_size_js.mdx b/docs/user_guides/templates/wasm_size_js.mdx new file mode 100644 index 0000000..602beeb --- /dev/null +++ b/docs/user_guides/templates/wasm_size_js.mdx @@ -0,0 +1,85 @@ +--- +id: wasm_size +title: Wasm size +sidebar_label: Wasm size +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Reducing WebAssembly Size + +One of the main challenges when using WebAssembly (Wasm) in the browser is managing the size of the `.wasm` binary. +Larger Wasm files lead to longer download times, increased memory usage, and delayed startup, +especially on mobile networks and lower-end devices. +For game engines, physics libraries, or interactive web tools using `rapier.js`, +minimizing Wasm size is essential for a responsive user experience. + +This chapter will guide you through creating a customized `rapier.js` build including only what you need. + +## Customizing Your Build + +Rust-to-Wasm projects often include a lot of functionality—even things you may not use at runtime. +Every public function, every exported symbol, and every dependency can increase the final `.wasm` file size. +Although tools like `wasm-opt` and Rust's dead-code elimination (via `--release`) help, +some runtime features (like serialization, or debugging) can still bloat your binary. + +### Example + +#### Quick minimal + +Rapier's javascript package is already built using different settings, +so you can leverage its configuration to make your own one: + +Take a look at the `builds/prepare_builds/` folder: +it contains automation to create rust projects with different settings, +using [Tera](https://docs.rs/crate/tera) and custom scripts under the hood. + +To customize a build, you can edit a configuration json file from `assets/`: +a `example_dim2_minimal.json` is provided: +you can see that its `feature_set` is empty, and its `conditions_to_remove` has a list of items. + +Let's build it! + +0. Clone the repository + +```bash +git clone https://github.com/dimforge/rapier.js +cd rapier.js +``` + +1. Generate the rust wasm + +That's the purpose of `builds/prepare_builds/` folder, +run `cargo run -- -c assets/example_dim2_minimal.json` in it to generate a `builds/rapier2d-minimal` Rust project. + +Feel free to look at its content: the most impactful operation is to NOT enable some features. +For convenience, features typically share names with Rapier's packages and are forwarded accordingly. + +Navigate into the created folder, and run `npm run build` to create a wasm package. + +If you want more options, you can: +- create a new feature in the `Cargo.toml.tera`, which you can use in rust code +- or modify the generated `Cargo.toml`, and rebuild the package. + +2. Rapier-compat + +To build [rapier-compat](./getting_started_js#using-rapier-without-a-bundler), +go into `rapier-compat` and run `./build_conf.sh example_dim2_minimal`. +This copies the Wasm package and its javascript glue code, +applies transformations, and removes the `conditions_to_remove` entries from the included files. + +3. End result + +Now you have a customized wasm build, ready to use. + +With this example, here is the size impact you can expect on `rapier_wasm2d_bg.wasm`: + +- published rapier2d package: + - Bundle Size: 1.27 MB + - brotli Size: 353.56 KB +- Custom build (no debug render, no serialization): + - Bundle Size: 1.05 MB + - brotli Size: 300.06 KB + +That's a solid improvement! you may go further by passing `-Oz` to wasm-opt, or customizing your build even further. \ No newline at end of file From 564f2541d7b7e9483053486ae22e21e61dd5b93d Mon Sep 17 00:00:00 2001 From: Thierry Berger Date: Fri, 6 Jun 2025 09:10:53 +0200 Subject: [PATCH 2/3] integrate the docs to the sidebar conf --- docs/user_guides/templates/wasm_size_js.mdx | 4 ++-- sidebar_docs.js | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/user_guides/templates/wasm_size_js.mdx b/docs/user_guides/templates/wasm_size_js.mdx index 602beeb..b56dc0e 100644 --- a/docs/user_guides/templates/wasm_size_js.mdx +++ b/docs/user_guides/templates/wasm_size_js.mdx @@ -1,5 +1,5 @@ --- -id: wasm_size +id: wasm_size_js title: Wasm size sidebar_label: Wasm size --- @@ -19,7 +19,7 @@ This chapter will guide you through creating a customized `rapier.js` build incl ## Customizing Your Build -Rust-to-Wasm projects often include a lot of functionality—even things you may not use at runtime. +Rust-to-Wasm projects often include a lot of functionality, even things you may not use at runtime. Every public function, every exported symbol, and every dependency can increase the final `.wasm` file size. Although tools like `wasm-opt` and Rust's dead-code elimination (via `--release`) help, some runtime features (like serialization, or debugging) can still bloat your binary. diff --git a/sidebar_docs.js b/sidebar_docs.js index 03d2f2c..3b062c7 100644 --- a/sidebar_docs.js +++ b/sidebar_docs.js @@ -17,6 +17,7 @@ let template = { // 'user_guides/templates_injected/integration_parameters', 'user_guides/templates_injected/serialization', 'user_guides/templates_injected/determinism', + 'user_guides/templates_injected/wasm_size_js', 'user_guides/templates_injected/common_mistakes', // 'user_guides/templates_injected/the_rapier_testbed', // 'user_guides/templates_injected/common_recipes', @@ -65,6 +66,7 @@ let specialized_guides = { 'user_guides/javascript/advanced_collision_detection_js', 'user_guides/javascript/serialization', 'user_guides/javascript/determinism', + 'user_guides/javascript/wasm_size_js', 'user_guides/javascript/common_mistakes', ], }; From e8f0a6747fe917a73618fa2c0b9dad33219b2977 Mon Sep 17 00:00:00 2001 From: Thierry Berger Date: Tue, 10 Jun 2025 10:07:59 +0200 Subject: [PATCH 3/3] update json fields naming --- docs/user_guides/templates/wasm_size_js.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_guides/templates/wasm_size_js.mdx b/docs/user_guides/templates/wasm_size_js.mdx index b56dc0e..5a35714 100644 --- a/docs/user_guides/templates/wasm_size_js.mdx +++ b/docs/user_guides/templates/wasm_size_js.mdx @@ -37,7 +37,7 @@ using [Tera](https://docs.rs/crate/tera) and custom scripts under the hood. To customize a build, you can edit a configuration json file from `assets/`: a `example_dim2_minimal.json` is provided: -you can see that its `feature_set` is empty, and its `conditions_to_remove` has a list of items. +you can see that its `additional_features` is empty, and its `conditional_compilation_to_remove` has a list of items. Let's build it! @@ -67,7 +67,7 @@ If you want more options, you can: To build [rapier-compat](./getting_started_js#using-rapier-without-a-bundler), go into `rapier-compat` and run `./build_conf.sh example_dim2_minimal`. This copies the Wasm package and its javascript glue code, -applies transformations, and removes the `conditions_to_remove` entries from the included files. +applies transformations, and removes the `conditional_compilation_to_remove` entries from the included files. 3. End result