rustwasm · ashleygwilliams · Dec 28, 2018 · Dec 28, 2018 · Jan 2, 2019 · Jan 2, 2019
diff --git a/README.md b/README.md
@@ -7,9 +7,10 @@
 
 This tool seeks to be a one-stop shop for building and working with rust-
 generated WebAssembly that you would like to interop with JavaScript, in the
-browser or with Node.js. `wasm-pack` helps you build and publish rust-generated
-WebAssembly to the npm registry to be used alongside any other javascript
-package in workflows that you already use, such as [webpack] or [greenkeeper].
+browser or with Node.js. `wasm-pack` helps you build rust-generated
+WebAssembly packages that you could publish to the npm registry, or otherwise use
+alongside any javascript packages in workflows that you already use, such as [webpack]
+or [greenkeeper].
 
 [bundler-support]: https://github.com/rustwasm/team/blob/master/goals/bundler-integration.md#details
 [webpack]: https://webpack.js.org/

diff --git a/docs/index.html b/docs/index.html
@@ -2,6 +2,7 @@
 <head>
   <meta charset="utf-8">
   <title>wasm-pack</title>
+  <link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.1/normalize.min.css" rel="stylesheet">
   <link href="https://cdnjs.cloudflare.com/ajax/libs/skeleton/2.0.4/skeleton.min.css" rel="stylesheet">
   <link rel="stylesheet" href="./public/custom.css" />
   <link rel="apple-touch-icon" sizes="180x180" href="./apple-touch-icon.png">
@@ -51,6 +52,60 @@ <h2>📦✨ your favorite rust -> wasm workflow tool!</h2>
         </div>
       </div>
     </header>
+    <hr/>
+    <section id="build">
+      <div class="container">
+        <h2>Build it with wasm-pack!</h2>
+        <div class="row">
+          <div class="four columns">
+            <header>
+              <img src="./public/img/webpack.jpeg" alt="webpack" />
+              <h4>Hybrid Applications with Webpack</h4>
+            </header>
+            <p>
+              Develop a WebAssembly module alongside any JavaScript project
+              that leverages <a href="https://webpack.js.org/">Webpack</a>.
+              Edit your Rust and watch your WebAssembly compile and reload as
+              you work- a great way to start exploring WebAssembly in a JavaScript
+              application you already work on!
+            </p>
+            <a href="#" class="button">Learn More</a>
+          </div>
+          <div class="four columns">
+            <header>
+              <img src="./public/img/npm-packages.png" alt="npm packages" />
+              <h4>npm Packages for the Broswer and Node.js</h4>
+            </header>
+            <p>
+              Leverage the power and breadth of the Rust ecosystem by compiling
+              and publishing packages from <a href="https://crates.io">crates.io</a>
+              as WebAssembly packages to the <a href="https://npmjs.com">npm Registry</a>
+              - or write your own! Surgically replace hotpaths in your JavaScript or
+              Node.js application with WebAssembly modules- using the same tools you
+              use for your JavaScript dependencies!
+            </p>
+            <a href="#" class="button">Learn More</a>
+          </div>
+          <div class="four columns">
+            <header>
+              <img src="./public/img/wasmbinaries.png" alt="webpack" />
+              <h4>Standalone WASM binaries</h4>
+            </header>
+            <p>
+              No registry? <br/> No bundler?<br/> No problem!<br/>
+            </p>
+            <p>
+              wasm-pack plays well with others but is also happy to generate
+              standalone binaries for consumption in the browser.
+            </p>
+            <a href="#" class="button">Learn More</a>
+          </div>
+        </div>
+      </div>
+    </section>
+    <footer>
+      <p>Maintained by <a href="">Ashley Williams</a> and the <a href="">Rust-WebAssembly Working Group</a>. Found a typo? <a href="">File an issue!<a/></p>
+    </footer>
   </div>
 </div>
 <script type="text/javascript" src="installer/wasm-pack.js"></script>

diff --git a/docs/public/custom.css b/docs/public/custom.css
@@ -24,6 +24,7 @@
   position: relative;
   float: left;
   margin-bottom: 0;
+  bottom: -5px;
 }
 
 .navbar-logo a img {
@@ -96,3 +97,48 @@
 a {
   color: #6556EC;
 }
+
+img {
+  width: 100%;
+}
+
+.button {
+  display: block;
+}
+
+div header {
+  min-height: 270px;
+  font-weight: 400;
+}
+
+footer {
+  background-color: #6556EC;
+  color: white;
+  margin: 50px 0 0 0;
+  padding: 20px 0 5px;
+  text-align: center;
+}
+
+footer a {
+  color: white;
+}
+
+@media only screen and (min-width: 800px) { 
+  #build .columns {
+    position: relative;
+    min-height: 550px;
+  }
+
+  #build a.button {
+    width: 100%;
+    position: absolute;
+    bottom: 0;
+  }
+}
+
+@media only screen and (max-width: 800px) {
+  #build .columns {
+    padding: 40px 0;
+    border-top: solid rgb(187, 187, 187) 1px;
+  }
+}
diff --git a/docs/public/img/npm-packages.png b/docs/public/img/npm-packages.png
diff --git a/docs/public/img/wasmbinaries.png b/docs/public/img/wasmbinaries.png
diff --git a/docs/public/img/webpack.jpeg b/docs/public/img/webpack.jpeg
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -3,21 +3,31 @@
 - [Prerequisites](./prerequisites/index.md)
   - [Rust](./prerequisites/rust.md)
   - [npm](./prerequisites/npm.md)
-- [Project Setup](./project-setup/index.md)
-  - [Using a Template](./project-setup/using-a-template.md)
-  - [Manual Setup](./project-setup/manual-setup.md)
 - [Commands](./commands/index.md)
   - [`init` (DEPRECATED)](./commands/init.md)
   - [`build`](./commands/build.md)
   - [`pack` and `publish`](./commands/pack-and-publish.md)
-- [Tutorial](./tutorial/index.md)
-  - [Getting Started](./tutorial/getting-started.md)
-  - [Template Deep Dive](./tutorial/template-deep-dive/index.md)
-    - [`Cargo.toml`](./tutorial/template-deep-dive/cargo-toml.md)
-    - [`src/lib.rs`](./tutorial/template-deep-dive/src-lib-rs.md)
-    - [`src/utils.rs`](./tutorial/template-deep-dive/src-utils-rs.md)
-    - [`wee_alloc`](./tutorial/template-deep-dive/wee_alloc.md)
-  - [Packaging and Publishing](./tutorial/packaging-and-publishing.md)
-  - [Using your Library](./tutorial/using-your-library.md)
+- [Tutorials](./tutorials/index.md)
+  - [Hybrid applications with Webpack](./tutorials/hybrid-applications-with-webpack/index.md)
+    - [Getting started](./tutorials/hybrid-applications-with-webpack/getting-started.md)
+    - [Template deep dive](./tutorials/hybrid-applications-with-webpack/template-deep-dive/index.md)
+      - [`Cargo.toml`](./tutorials/hybrid-applications-with-webpack/template-deep-dive/cargo-toml.md)
+      - [`src/lib.rs`](./tutorials/hybrid-applications-with-webpack/template-deep-dive/src-lib-rs.md)
+    - [Building your project](./tutorials/hybrid-applications-with-webpack/template-deep-dive/building-your-project.md)
+    - [Using your library](./tutorials/hybrid-applications-with-webpack/using-your-library.md)
+  - [npm browser packages](./tutorials/npm-browser-packages/index.md)
+    - [Getting started](./tutorials/npm-browser-packages/getting-started.md)
+      - [Project setup](./tutorials/npm-browser-packages/project-setup/index.md)
+        - [Using a Template](./tutorials/npm-browser-packages/project-setup/using-a-template.md)
+        - [Manual Setup](./tutorials/npm-browser-packages/project-setup/manual-setup.md)
+    - [Template deep dive](./tutorials/npm-browser-packages/template-deep-dive/index.md)
+      - [`Cargo.toml`](./tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md)
+      - [`src/lib.rs`](./tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md)
+      - [`src/utils.rs`](./tutorials/npm-browser-packages/template-deep-dive/src-utils-rs.md)
+      - [`wee_alloc`](./tutorial/template-deep-dive/wee_alloc.md)
+    - [Building your project](./tutorials/npm-browser-packages/template-deep-dive/building-your-project.md)
+    - [Packaging and publishing](./tutorials/npm-browser-packages/packaging-and-publishing.md)
+    - [Using your library](./tutorials/npm-browser-packages/using-your-library.md)
+  - [Standalone WASM binaries](./tutorials/standalone-wasm-binaries/index.md)
 - [`Cargo.toml` Configuration](./cargo-toml-configuration.md)
 - [Contributing](./contributing.md)
diff --git a/docs/src/command/pack-and-publish.md b/docs/src/command/pack-and-publish.md
diff --git a/docs/src/tutorials/hybrid-applications-with-webpack/getting-started.md b/docs/src/tutorials/hybrid-applications-with-webpack/getting-started.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
diff --git a/docs/src/tutorials/hybrid-applications-with-webpack/index.md b/docs/src/tutorials/hybrid-applications-with-webpack/index.md
@@ -0,0 +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
diff --git a/...ls/hybrid-applications-with-webpack/template-deep-dive/building-your-project.md b/...ls/hybrid-applications-with-webpack/template-deep-dive/building-your-project.md
@@ -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
diff --git a/...src/tutorials/hybrid-applications-with-webpack/template-deep-dive/cargo-toml.md b/...src/tutorials/hybrid-applications-with-webpack/template-deep-dive/cargo-toml.md
@@ -0,0 +1,123 @@
+# Cargo.toml
+
+We'll see more about how to use this library when we discuss what has been generated in `lib.rs`.
+
+`Cargo.toml` is the manifest file for Rust's package manager, `cargo`. This file contains
+metadata such as name, version, and dependencies for packages, which are call "crates" in Rust.
+
+There's a bunch of metadata that the template gives us, but there are 4 key parts to discuss:
+
+- [`crate-type`](#a1-crate-type)
+- [`wasm-bindgen` dependency](#a2-wasm-bindgen-dependency)
+- [`[features]` and `wee-alloc`, `console-error-panic-hook` dependencies](#a3-features-and-wee-alloc-console-error-panic-hook-dependencies)
+- [`web-sys` dependency](#a4-web-sys-dependency)
+
+<hr/>
+
+## 1. `crate-type`
+
+```toml
+[lib]
+crate-type = ["cdylib"]
+```
+
+A Rust-`wasm` crate is a bit different from a normal crate, and as a result, we need to note
+this in our `Cargo.toml`.
+
+When `cargo` is told to build a project, or compilation is otherwise done on a Rust project,
+the Rust compiler will need to link crates together, using a particular method, either
+statically or dynamically. The two types of crate that you are likely most familiar with are
+`#[crate_type = "bin"]` and `#[crate_type = "lib"]`, which are the crate types that largely
+represent the difference between Rust application projects and Rust libraries.
+
+`#[crate_type = "cdylib"]` signifies that you'd like the compiler to create a dynamic system
+library. This type of library is suited for situations where you'd like to compile Rust code
+as a dynamic library to be loaded from another language. In our case, we'll be compiling to a
+`*.wasm` file, but this output type will create `*.so` files on Linux, `*.dylib` files on
+macOS, and `*.dll` files on Windows in non-`wasm` circumstances.
+
+You can read more about linking and crate types, [here](https://doc.rust-lang.org/reference/linkage.html).
+
+## 2. `wasm-bindgen` dependency
+
+`wasm-bindgen` is our most important dependency. This package allows us to use the
+`#[wasm-bindgen]` attribute to tag code that represents the interface we want between
+our JavaScript and Rust-generated `wasm`. We can import JS and export Rust by using this
+attribute.
+
+```toml
+wasm-bindgen = "0.2"
+```
+
+We'll see more about how to use this library when we discuss what has been generated in `lib.rs`.
+
+⚠️ If you are coming from JavaScript, you might note that when we add the dependency
+there is no `^` or `~` symbol- it looks like we're locking to the `0.2` version.
+However, that's not the case! In Rust, the `^` is implied.
+
+## 3. `[features]` and `wee-alloc`, `console-error-panic-hook` dependencies
+
+As part of our effort to design a template that helps people discover useful crates
+for their particular use case, this template includes 2 dependencies that can be
+very useful for folks developing Rust-`wasm` crates: `console-error-panic-hook` and
+`wee-alloc`.
+
+Because these dependencies are useful primarily in a specific portion of the Rust-`wasm`
+crate development workflow, we've also set up a bit of glue code that allows us to include
+them both as dependences, but allowing for them to be optionally included.
+
+```toml
+[features]
+default-features = ["console_error_panic_hook"]
+
+[dependencies]
+cfg-if = "0.1.5"
+
+# The `console_error_panic_hook` crate provides better debugging of panics by
+# logging them with `console.error`. This is great for development, but requires
+# all the `std::fmt` and `std::panicking` infrastructure, so isn't great for
+# code size when deploying.
+console_error_panic_hook = { version = "0.1.1", optional = true }
+
+# `wee_alloc` is a tiny allocator for wasm that is only ~1K in code size
+# compared to the default allocator's ~10K. It is slower than the default
+# allocator, however.
+wee_alloc = { version = "0.4.2", optional = true }
+```
+
+[`cfg-if`] allows us to check if certain features are enabled on a Rust crate. We'll
+use this crate in `lib.rs` to optionally enable `console_error_panic_hook` or
+`wee_alloc`. By default, we have `console_error_panic_hook` enabled.
+To disable features, we can remove their entry from the `default-features` vector.
+
+To learn more about these features, we discuss them in depth in the `lib.rs` section.
+
+Briefly, they include:
+
++ **console_error_panic_hook** for logging panic messages to the developer console.
++ **wee_alloc**, an allocator optimized for small code size.
+
+## 4. `web-sys` dependency
+
+The [`web-sys` crate](https://crates.io/crates/web-sys) provides raw wasm-bindgen imports for all of the Web's APIs.
+In our `Cargo.toml` file, we list the APIs we want to use from `web-sys` in
+order to have them compiled. This crate by default contains very little
+when compiled as almost all of its exposed APIs are gated by Cargo features.
+Below we see the features that are pulled in by generated Cargo.toml
+from the rust-webpack template.
+
+```toml
+[dependencies.web-sys]
+version = "0.3"
+features = [
+  "Document",
+  "Element",
+  "HtmlElement",
+  "Node",
+  "Window",
+]
+```
+
+You can see the exhaustive list of features in `crates/web-sys/Cargo.toml`
+and enable them by looking at the [documentation](https://rustwasm.github.io/wasm-bindgen/api/web_sys/)
+to see what features they depend on.
diff --git a/docs/src/tutorials/hybrid-applications-with-webpack/template-deep-dive/index.md b/docs/src/tutorials/hybrid-applications-with-webpack/template-deep-dive/index.md
@@ -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)