{"id":13493880,"url":"https://github.com/dflemstr/rust-native-wasm-loader","last_synced_at":"2025-03-15T14:30:41.347Z","repository":{"id":66855335,"uuid":"114038399","full_name":"dflemstr/rust-native-wasm-loader","owner":"dflemstr","description":null,"archived":false,"fork":false,"pushed_at":"2018-10-07T19:21:11.000Z","size":433,"stargazers_count":163,"open_issues_count":6,"forks_count":12,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-02-27T03:05:53.983Z","etag":null,"topics":["loader","rust","webpack-loader"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dflemstr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-12T20:57:23.000Z","updated_at":"2023-06-07T01:59:15.000Z","dependencies_parsed_at":"2023-03-20T11:55:14.981Z","dependency_job_id":null,"html_url":"https://github.com/dflemstr/rust-native-wasm-loader","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Frust-native-wasm-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Frust-native-wasm-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Frust-native-wasm-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Frust-native-wasm-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dflemstr","download_url":"https://codeload.github.com/dflemstr/rust-native-wasm-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243742597,"owners_count":20340669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["loader","rust","webpack-loader"],"created_at":"2024-07-31T19:01:19.651Z","updated_at":"2025-03-15T14:30:40.662Z","avatar_url":"https://github.com/dflemstr.png","language":"JavaScript","readme":"# `rust-native-wasm-loader`\n\n[![Build Status](https://travis-ci.org/dflemstr/rust-native-wasm-loader.svg?branch=master)](https://travis-ci.org/dflemstr/rust-native-wasm-loader) [![rust-native-wasm-loader](https://img.shields.io/npm/dt/rust-native-wasm-loader.svg)](https://www.npmjs.com/package/rust-native-wasm-loader) [![npm](https://img.shields.io/npm/v/rust-native-wasm-loader.svg)](https://www.npmjs.com/package/rust-native-wasm-loader)\n\nThis is a webpack loader that loads Rust code as a WebAssembly module.  It uses the native Rust\nsupport for compiling to `wasm32` and does not require Emscripten.\n\n   * [rust-native-wasm-loader](#rust-native-wasm-loader)\n   * [Usage](#usage)\n      * [Short version](#short-version)\n      * [Available loader options](#available-loader-options)\n      * [Long version](#long-version)\n   * [wasm-bindgen experimental support](#wasm-bindgen-experimental-support)\n   * [cargo-web experimental support](#cargo-web-experimental-support)\n\n# Usage\n\nIf you already know how to use Rust and Webpack, read the \"Short version\" of this section.  If you\nwant a full example, read the \"Long version.\"\n\n## Short version\n\nAdd both this loader and `wasm-loader` to your Webpack loaders in `webpack.config.js`:\n\n```js\nmodule.exports = {\n  // ...\n  module: {\n    rules: [\n      {\n        test: /\\.rs$/,\n        use: [{\n          loader: 'wasm-loader'\n        }, {\n          loader: 'rust-native-wasm-loader',\n          options: {\n            release: true\n          }\n        }]\n      }\n    ]\n  }\n}\n```\n\nThen, specify that your Rust library should be a `cdylib` in `Cargo.toml`:\n\n```toml\n[lib]\ncrate-type = [\"cdylib\"]\n```\n\nNow you can import any functions marked with `#[no_mangle]` as WebAssembly functions:\n\n```js\nimport loadWasm from './path/to/rustlib/src/lib.rs'\n\nloadWasm().then(result =\u003e {\n  const add = result.instance.exports['add'];\n  console.log('return value was', add(2, 3));\n});\n```\n\n## Available loader options\n\n  - `release`: `boolean`; whether to compile the WebAssembly module in debug or release mode;\n    defaults to `false`.\n  - `gc`: `boolean`; whether to run `wasm-gc` on the WebAssembly output.  Reduces binary size but\n    requires installing [wasm-gc][].  Defaults to `false` and is a no-op in `wasmBindgen` or\n    `cargoWeb` mode.\n  - `target`: `string`; the Rust target to use; this defaults to `wasm32-unknown-unknown`\n  - `wasmBindgen`: `boolean` or `object`; use `wasm-bindgen` to post-process the wasm file.  This\n    probably means that you need to chain this loader with `babel-loader` as well since\n    `wasm-bindgen` outputs ES6 (or typescript).\n      - `wasmBindgen.debug`: `boolean`; run `wasm-bindgen` in debug mode.\n      - `wasmBindgen.wasm2es6js`: `boolean`; use `wasm2es6js` to inline the wasm file into generated\n        Javascript.  Useful if webpack is not configured to load wasm files via some other loader.\n      - `wasmBindgen.typescript`: `boolean`; emit a typescript declaration file as part of the\n        build.  This file will automatically be referenced, and in a way that `ts-loader` will pick\n        it up but it's still possible to treat the output from this loader like a normal Javascript\n        module compatible with `babel-loader`.\n  - `cargoWeb`: `boolean` or `object`; use `cargo-web` to compile the project instead of only\n    building a `wasm` module.  Defaults to `false`.\n      - `cargoWeb.name`: `string`; the file name to use for emitting the wasm file for `cargo-web`,\n        e.g. `'static/wasm/[name].[hash:8].wasm'`.\n      - `cargoWeb.regExp`: `string`; a regexp to extract additional variables for use in `name`.\n\n## Long version\n\nFirst, you need Rust installed.  The easiest way is to follow the instructions at [rustup.rs][].\n\nThen, you need to add support for WebAssembly cross-compilation.  At the time of writing, this\nrequires using the `nightly` compiler:\n\n```text\nrustup toolchain install nightly\nrustup target add wasm32-unknown-unknown --toolchain nightly\n```\n\nThe next step is to integrate a cargo/node project.  Let's assume we don't already have one, so we\ncreate one:\n\n```text\ncargo init add\ncd add\n```\n\nIf nightly is not your system default toolchain, create a file named `rust-toolchain` containing\nthe toolchain name you want to associate with the project:\n\n```\necho nightly \u003e rust-toolchain\n```\n\nWe can add the Rust code that should be available in the WebAssembly module to `src/lib.rs`.  All\nfunctions that should be reachable from WebAssembly should be marked with `#[no_mangle]`:\n\n```rust\n#[no_mangle]\npub fn add(a: i32, b: i32) -\u003e i32 {\n    eprintln!(\"add({:?}, {:?}) was called\", a, b);\n    a + b\n}\n```\n\nThen, specify that your Rust library should be a `cdylib` in `Cargo.toml`:\n\n```toml\n[lib]\ncrate-type = [\"cdylib\"]\n```\n\nNow you can actually start to use this loader.  This loader itself does not create Javascript code\nfor loading a WebAssembly module, so you need to compose it with another loader, like `wasm-loader`:\n\n```text\nyarn init\nyarn add --dev webpack\nyarn add --dev rust-native-wasm-loader wasm-loader\n```\n\nThe loaders can be registered the usual way by adding them to your `webpack.config.js`:\n\n```js\nconst path = require('path');\n\nmodule.exports = {\n  entry: './src/index.js',\n  output: {\n    filename: 'index.js',\n    path: path.resolve(__dirname, 'dist')\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.rs$/,\n        use: [{\n          loader: 'wasm-loader'\n        }, {\n          loader: 'rust-native-wasm-loader',\n          options: {\n            release: true\n          }\n        }]\n      }\n    ]\n  }\n};\n```\n\nYou can now import the WebAssembly module by using the main `.rs` file from your Cargo project\n(`lib.rs` or `main.rs`); e.g. from your `index.js`:\n\n```js\nimport loadAdd from './lib.rs'\n\nloadAdd().then(result =\u003e {\n  const add = result.instance.exports['add'];\n  console.log('return value was', add(2, 3));\n});\n```\n\nYou can now run webpack and the resulting code from node.js or a browser:\n\n```text\n$ yarn run webpack\n$ node dist/index.js\nreturn value was 5\n```\n\n# `wasm-bindgen` experimental support\n\nYou can use experimental `wasm-bindgen` support with the following options:\n\n```js\n{\n  test: /\\.rs$/,\n  use: [\n    {\n      loader: 'babel-loader',\n      options: {\n        compact: true,\n      }\n    },\n    {\n      loader: 'rust-native-wasm-loader',\n      options: {\n        release: true,\n        wasmBindgen: {\n          wasm2es6js: true,\n        },\n      }\n    }\n  ]\n}\n```\n\nand edit your `lib.rs`:\n\n```rust\nextern crate wasm_bindgen;\nuse wasm_bindgen::prelude::*;\n\n#[wasm_bindgen]\npub fn add(a: i32, b: i32) -\u003e i32 {\n    a + b\n}\n```\n\nThe loader now uses `wasm-bindgen` to build the project.  If you are using webpack 4, it has experimental native support for importing WASM files, so you probably\ndon't need the `wasm2es6js` flag. If you are using webpack 3 (or bundling for Chrome and it's 4K limit on main thread WASM), it is needed in order to inline\nthe loading of the wasm file correctly.  By using `wasm2es6js`, the loader returns a normal Javascript module that can\nbe loaded like so:\n\n```js\nimport { add, wasmBooted } from './path/to/rustlib/src/lib.rs'\n\nwasmBooted.then(() =\u003e {\n  console.log('return value was', add(2, 3));\n});\n```\n\n# `cargo-web` experimental support\n\nYou can use experimental `cargo-web` support with the following options:\n\n```js\n{\n  loader: 'rust-native-wasm-loader',\n  options: {\n    cargoWeb: true,\n    name: 'static/wasm/[name].[hash:8].wasm'\n  }\n}\n```\n\nThe loader now uses `cargo-web` to build the project, and as a result needs to emit the wasm file\nseparately.  The loader now returns a normal Javascript module that can be loaded like so:\n\n```js\nimport loadWasm from './path/to/rustlib/src/lib.rs'\n\nloadWasm.then(module =\u003e {\n  console.log('return value was', module.add(2, 3));\n});\n```\n\n[rustup.rs]: https://rustup.rs/\n[wasm-gc]: https://github.com/alexcrichton/wasm-gc\n","funding_links":[],"categories":["JavaScript","Development Tools"],"sub_categories":["JavaScript Toolchains and Bundler Plugins"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdflemstr%2Frust-native-wasm-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdflemstr%2Frust-native-wasm-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdflemstr%2Frust-native-wasm-loader/lists"}