feat(docs): start filling in docs for rust webpack template

Co-authored-by: Patrick McCarver <patrick@merklebros.com>
master
DebugSteven 6 years ago committed by Ashley Williams
parent b2b7abf43e
commit 3e77644235
  1. 15
      docs/src/tutorials/hybrid-applications-with-webpack/getting-started.md
  2. 20
      docs/src/tutorials/hybrid-applications-with-webpack/index.md
  3. 23
      docs/src/tutorials/hybrid-applications-with-webpack/template-deep-dive/building-your-project.md
  4. 1
      docs/src/tutorials/hybrid-applications-with-webpack/template-deep-dive/cargo-toml.md
  5. 15
      docs/src/tutorials/hybrid-applications-with-webpack/template-deep-dive/index.md
  6. 3
      docs/src/tutorials/hybrid-applications-with-webpack/template-deep-dive/src-lib-rs.md
  7. 91
      docs/src/tutorials/hybrid-applications-with-webpack/using-your-library.md

@ -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

@ -1 +1,21 @@
# Hybrid Applications with Webpack
The goal of this tutorial is to introduce you to the `rust-webpack-template`
and the `wasm-pack` workflow by building the example app in the template.
This tutorial is aimed at folks who are both beginners to WebAssembly and Rust- you don't need
much Rust knowledge to complete this tutorial.
Be sure to have done the following before starting:
1. [Install `wasm-pack`](../../installer)
1. Read and install the [Prerequisites](../prerequisites/index.html).
- You'll need [Rust], version 1.30 or higher. (Currently either `beta` or `nightly` channels). [Learn more](../project-setup/rust.html).
- You'll need [Node.js] and [npm] installed. [Learn more](../project-setup/npm.html).
We strongly recommend that you install [Node.js] using a version manager. You can learn more [here](https://npmjs.com/get-npm).
[Rust]: https://www.rust-lang.org
[Node.js]: https://nodejs.org
[npm]: https://npmjs.com

@ -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,15 @@
# Template Deep Dive
This section is a deep dive into the contents of the rust-wasm webpack template project,
specifically written for people who are not that familiar with Rust. If you'd rather just
checkout the workflow, feel free to skip this section!
If you haven't used a template to set up your project, the contents of your files
may look slightly different than what is described here.
### What the Template Gave Us
Let's start by taking a look at what the template generated for us.
- [`Cargo.toml`](./cargo-toml.html)
- [`src/lib.rs`](./src-lib-rs.html)

@ -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…
Cancel
Save