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