Co-authored-by: Patrick McCarver <patrick@merklebros.com>master
parent
b2b7abf43e
commit
3e77644235
@ -0,0 +1,15 @@ |
||||
# Getting Started |
||||
|
||||
You can create a new Rust-WebAssembly webpack project by using the [rustwasm webpack-template]. |
||||
|
||||
Run: |
||||
|
||||
``` |
||||
npm init rust-webpack my-app |
||||
``` |
||||
|
||||
The last argument will be your project name. After you run the command, you will have a |
||||
directory with a new project, ready to go. We'll talk about what's been included in this |
||||
template further in this guide. |
||||
|
||||
[rustwasm webpack-template]: https://github.com/rustwasm/rust-webpack-template |
@ -0,0 +1,23 @@ |
||||
# Building your project |
||||
|
||||
We are writing a package that should be used in the browser, so we run this in our terminal: |
||||
|
||||
```bash |
||||
$ wasm-pack build |
||||
``` |
||||
|
||||
If you were writing a package that should be used in Node.js (with CommonJS modules, e.g. `require`), |
||||
you would run this in your terminal: |
||||
|
||||
```bash |
||||
$ wasm-pack build --target nodejs |
||||
``` |
||||
|
||||
This command does a few things when run: |
||||
|
||||
1. It'll compile your code to wasm if you haven't already |
||||
2. It'll generate a `pkg` folder. Inside there will be: |
||||
- a Rust-compiled to wasm file |
||||
- a JavaScript wrapper file around the wasm |
||||
- TypeScript declaration files to convey information about types |
||||
- a `package.json` file |
@ -0,0 +1 @@ |
||||
# Cargo.toml WIP |
@ -0,0 +1,3 @@ |
||||
# src/lib.rs |
||||
|
||||
🚧 COMING SOON 🚧 |
@ -0,0 +1,91 @@ |
||||
# Run The Code |
||||
|
||||
The Rust Webpack template is designed for creating monorepo-style Web applications with |
||||
Rust-generated WebAssembly and Webpack without publishing your wasm to NPM. |
||||
This portion of the tutorial will explain how to build a [Webpack] JavaScript project |
||||
that will run your WebAssembly code in the browser. |
||||
|
||||
[Webpack]: https://webpack.js.org/ |
||||
|
||||
## Scaffold a JavaScript Project |
||||
|
||||
To generate a new Rust Webpack project, we've used the [`rust-webpack`] npm template. |
||||
|
||||
[`rust-webpack`]: https://github.com/rustwasm/rust-webpack-template |
||||
|
||||
``` |
||||
npm init rust-webpack your-package-name |
||||
``` |
||||
|
||||
A new project folder will be created with the name you supply. |
||||
|
||||
If we look in the project, we'll see the following: |
||||
|
||||
- `.gitignore`: ignores `node_modules` |
||||
- `LICENSE-APACHE` and `LICENSE-MIT`: most Rust projects are licensed this way, so these are included for you |
||||
- `README.md`: the file you are reading now! |
||||
- `index.html`: a bare bones html document that includes the webpack bundle |
||||
- `js/index.js`: example JS file with a comment showing how to import and use a wasm pkg |
||||
- `package.json` and `package-lock.json`: |
||||
- pulls in devDependencies for using webpack: |
||||
- [`webpack`](https://www.npmjs.com/package/webpack) |
||||
- [`webpack-cli`](https://www.npmjs.com/package/webpack-cli) |
||||
- [`webpack-dev-server`](https://www.npmjs.com/package/webpack-dev-server) |
||||
- defines a `start` script to run `webpack-dev-server` |
||||
- `webpack.config.js`: configuration file for bundling your JS with webpack |
||||
- `crate/src/lib.rs`: your Rust crate code! |
||||
|
||||
## Your Rust Crate |
||||
|
||||
The scaffolded project includes an example Rust WebAssembly webpack crate. |
||||
|
||||
Inside the `crate/src/lib.rs` file we see a `run` function that's callable from our JS file: |
||||
```rust |
||||
// Called by our JS entry point to run the example. |
||||
#[wasm_bindgen] |
||||
pub fn run() -> Result<(), JsValue> { |
||||
set_panic_hook(); |
||||
|
||||
// ... |
||||
let p: web_sys::Node = document.create_element("p")?.into(); |
||||
p.set_text_content(Some("Hello from Rust, WebAssembly, and Webpack!")); |
||||
// ... |
||||
|
||||
Ok(()) |
||||
} |
||||
``` |
||||
|
||||
Now, open up the `js/index.js` file. We see our Rust-generated wasm `run` function being |
||||
called inside our JS file. |
||||
|
||||
```js |
||||
import("../crate/pkg").then(module => { |
||||
module.run(); |
||||
}); |
||||
``` |
||||
|
||||
## Run The Project |
||||
|
||||
To generate our Rust-compiled to wasm code, in the `crate` directory we run: |
||||
```bash |
||||
wasm-pack build |
||||
``` |
||||
You can see this generated code in the `pkg` directory that's just been created. |
||||
|
||||
In the `crate` directory, we will also run: |
||||
```bash |
||||
npm run build |
||||
``` |
||||
This will create our bundled JavaScript module in a new directory `dist`. |
||||
|
||||
We should be ready to run our project now! |
||||
In the `dist` directory, we'll run: |
||||
|
||||
```bash |
||||
npm start |
||||
``` |
||||
|
||||
Then in a web browser navigate to `http://localhost:8080` and you should be greeted |
||||
with text in the body of the page that says "Hello from Rust, WebAssembly, and Webpack!" |
||||
|
||||
If you did congrats! You've successfully used the rust-webpack template! |
Loading…
Reference in new issue