Getting started (#1805)

* Streamline tool setup, add headings to project setup * Address typos * resolve link * resolve link 2 * resolve link 3 * resolve link 4 * Update docs/getting-started/build-a-sample-app.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/build-a-sample-app.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/build-a-sample-app.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/build-a-sample-app.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/build-a-sample-app.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/project-setup.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/project-setup.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/project-setup.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/project-setup.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Update docs/getting-started/project-setup.md Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> * Add header info to wasm-build-tools.md, added wasm-build-tools to sidebar.json, updated build-a-sample-app.md * Apply suggestions from code review Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> Co-authored-by: EC2 Default User <ec2-user@ip-172-31-51-38.ec2.internal> Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> Co-authored-by: Simon <simon@siku2.io>
yewstack · May 5, 2021 · c91d3dc · c91d3dc
1 parent c0b1ba4
commit c91d3dc
Show file tree

Hide file tree

Showing 4 changed files with 112 additions and 54 deletions.
diff --git a/docs/getting-started/build-a-sample-app.md b/docs/getting-started/build-a-sample-app.md
@@ -2,15 +2,36 @@
 title: Build a sample app
 ---
 
-First, create a new cargo project:
+## Create Project
+
+To get started, create a new cargo project.
 
 ```bash
 cargo new yew-app
 ```
 
 Open the newly created directory.
 
-First, let's add `yew` as a dependencies in the `Cargo.toml` file:
+```bash
+cd yew-app
+```
+
+## Run a hello world example
+
+To verify the Rust environment is setup, run the initial project using the cargo build tool.  After output about the build process, you should see the expected "Hello World" message.
+
+
+```bash
+cargo run
+```
+
+## Converting the project into a Yew web application
+
+To convert this simple command line application to a basic Yew web application, a few changes are needed.
+
+### Update Cargo.toml
+
+Add `yew` to the list of dependencies in the `Cargo.toml` file.
 
 ```toml
 [package]
@@ -23,7 +44,16 @@ edition = "2018"
 yew = "0.17"
 ```
 
-Copy the following template into your `src/main.rs` file:
+### Update main.rs
+
+We need to generate a template which sets up a root Component called `Model` which renders a button that updates its value when clicked.
+Replace the contents of `src/main.rs` with the following code.
+
+:::note
+The line `yew::start_app::<Model>()` inside `main()` starts your application and mounts it to the page's `<body>` tag.  
+If you would like to start your application with any dynamic properties, you can instead use `yew::start_app_with_props::<Model>(..)`.
+:::
+
 
 ```rust
 use yew::prelude::*;
@@ -83,11 +113,9 @@ fn main() {
 }
 ```
 
-This template sets up your root `Component`, called `Model` which shows a button that updates itself when you click it.
-Take special note of `yew::start_app::<Model>()` inside `main()` which starts your app and mounts it to the page's `<body>` tag.
-If you would like to start your application with any dynamic properties, you can instead use `yew::start_app_with_props::<Model>(..)`.
+### Create index.html
 
-Finally, add an `index.html` file in the root directory of your app:
+Finally, add an `index.html` file in the root directory of your app.
 
 ```html
 <!DOCTYPE html>
@@ -99,24 +127,18 @@ Finally, add an `index.html` file in the root directory of your app:
 </html>
 ```
 
-## Run your app
+## View your web application
 
-If you haven't already, install [Trunk](https://github.com/thedodd/trunk):
+Run the following command to build and serve the application locally.
 
 ```bash
-cargo install --locked trunk
-cargo install wasm-bindgen-cli
+trunk serve
 ```
 
-Also specify the WASM target.
-```
-rustup target add wasm32-unknown-unknown
-```
+Trunk will helpfully rebuild your application if you modify any of its files.
 
-Now all you have to do is run the following:
+## Congratulations
 
-```bash
-trunk serve
-```
+You have now successfully setup your Yew development environment, and built your first web application.
 
-This will start a development server which continually updates the app every time you change something.
+Experiment with this application and review the [examples](./examples.md) to further your learning.
diff --git a/docs/getting-started/project-setup.md b/docs/getting-started/project-setup.md
@@ -4,54 +4,44 @@ sidebar_label: Introduction
 description: Set yourself up for success
 ---
 
-## Rust
+## Overview
 
-First, you'll need Rust. To install Rust and the `cargo` build tool, follow the [official instructions](https://www.rust-lang.org/tools/install).
+Your local development environment will need a couple of tools to compile, build, package and debug your Yew application.
 
-You also need to install the `wasm32-unknown-unknown` target to compile Rust to Wasm.
-If you're using rustup, you just need to run `rustup target add wasm32-unknown-unknown`.
+
+## Installing Rust
+
+To install Rust follow the [official instructions](https://www.rust-lang.org/tools/install).
 
 :::important
 The minimum supported Rust version (MSRV) for Yew is `1.45.0`. Older versions can cause unexpected issues accompanied by incomprehensible error messages.
 You can check your toolchain version using `rustup show` (under "active toolchain") or alternatively `rustc --version`. To update your toolchain, run `rustup update`.
 :::
 
-## **Wasm Build Tools**
+## Install WebAssembly target
+
+Rust can compile source codes for different "targets" (e.g. different processors). The compilation target for browser-based WebAssembly is called "wasm32-unknown-unknown".  The following command will add this target to your development environment.
 
-Extra tooling is needed to facilitate the interop between WebAssembly and JavaScript. Additionally,
-depending on the tool you choose, they can help make deployment and packaging much less of a
-headache by generating all of the JavaScript code necessary to load and run your app's `.wasm`
-binary in a browser.
+`rustup target add wasm32-unknown-unknown`
 
-### [**`trunk`**](https://github.com/thedodd/trunk/)
+## Install Trunk
 
-A tool practically made for building Yew apps.
-It can build any `wasm-bindgen` based app and its design is inspired by rollup.js.
-With Trunk you don't need to have Node.js installed or touch any JavaScript code for that matter.
-It can bundle assets for your app and even ships with a Sass compiler.
+Trunk is the recommended tool for managing deployment and packaging, and will be used throughout the documentation and examples.
+See [Wasm Build Tools](./../more/wasm-build-tools.md) for more information on packaging and alternatives.
 
-All of our examples are built with Trunk.
+\```
+# note that this might take a while to install, because it compiles everything from scratch
+# Trunk also provides prebuilt binaries for a number of major package managers
+# See https://trunkrs.dev/#install for further details
+cargo install trunk
+\```
 
-[Getting started with `trunk`](project-setup/using-trunk.md)
+## Install wasm-bindgen-cli
 
-### [**`wasm-pack`**](https://rustwasm.github.io/docs/wasm-pack/)
+Trunk uses a tool called wasm-bindgen-cli to perform deployment and packaging, which should be installed using the following command.
 
-A CLI tool developed by the Rust / Wasm Working Group for packaging up WebAssembly. Best used
-together with the [`wasm-pack-plugin`](https://github.com/wasm-tool/wasm-pack-plugin) for Webpack.
-The primary purpose of `wasm-pack` is building Wasm libraries for use in JavaScript.
-Because of this, it can only build libraries and doesn't provide useful tools like a development server or automatic rebuilds.
 
-[Get started with `wasm-pack`](project-setup/using-wasm-pack.md)
 
-### Comparison
+## Summary
 
-|                               | `trunk`                                                          | `wasm-pack`                                                                                           |
-| ----------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------  |
-| Project Status                | Actively maintained                                              | Actively maintained by the [Rust / Wasm Working Group](https://rustwasm.github.io)                    |
-| Dev Experience                | Just works! Batteries included, no external dependencies needed. | Bare-bones. You'll need to write some scripts to streamline the experience or use the webpack plugin. |
-| Local Server                  | Supported                                                        | Only with webpack plugin                                                                              |
-| Auto rebuild on local changes | Supported                                                        | Only with webpack plugin                                                                              |
-| Asset handling                | Supported                                                        | Only with webpack plugin                                                                              |
-| Headless Browser Testing      | [In Progress](https://github.com/thedodd/trunk/issues/20)        | [Supported](https://rustwasm.github.io/wasm-pack/book/commands/test.html)                             |
-| Supported Targets             | <ul><li><code>wasm32-unknown-unknown</code></li></ul>            | <ul><li><code>wasm32-unknown-unknown</code></li></ul>                                                 |
-| Example Usage                 | [Sample app](./build-a-sample-app.md)                            | [Starter template](https://github.com/yewstack/yew-wasm-pack-minimal)                                 |
+Now that you have all the tools needed, we can [build a sample application](./build-a-sample-app.md).
diff --git a/docs/more/wasm-build-tools.md b/docs/more/wasm-build-tools.md
@@ -0,0 +1,45 @@
+---
+title: Wasm Build Tools
+description: Information about build tools
+---
+
+
+## **Wasm Build Tools**
+
+Extra tooling is needed to facilitate the interop between WebAssembly and JavaScript. Additionally,
+depending on the tool you choose, they can help make deployment and packaging much less of a
+headache by generating all of the JavaScript code necessary to load and run your app's `.wasm`
+binary in a browser.
+
+### [**`trunk`**](https://github.com/thedodd/trunk/)
+
+A tool practically made for building Yew apps.
+It can build any `wasm-bindgen` based app and its design is inspired by rollup.js.
+With Trunk you don't need to have Node.js installed or touch any JavaScript code for that matter.
+It can bundle assets for your app and even ships with a Sass compiler.
+
+All of our examples are built with Trunk.
+
+[Getting started with `trunk`](project-setup/using-trunk.md)
+
+### [**`wasm-pack`**](https://rustwasm.github.io/docs/wasm-pack/)
+
+A CLI tool developed by the Rust / Wasm Working Group for packaging up WebAssembly. Best used
+together with the [`wasm-pack-plugin`](https://github.com/wasm-tool/wasm-pack-plugin) for Webpack.
+The primary purpose of `wasm-pack` is building Wasm libraries for use in JavaScript.
+Because of this, it can only build libraries and doesn't provide useful tools like a development server or automatic rebuilds.
+
+[Get started with `wasm-pack`](project-setup/using-wasm-pack.md)
+
+### Comparison
+
+|                               | `trunk`                                                          | `wasm-pack`                                                                                           |
+| ----------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------  |
+| Project Status                | Actively maintained                                              | Actively maintained by the [Rust / Wasm Working Group](https://rustwasm.github.io)                    |
+| Dev Experience                | Just works! Batteries included, no external dependencies needed. | Bare-bones. You'll need to write some scripts to streamline the experience or use the webpack plugin. |
+| Local Server                  | Supported                                                        | Only with webpack plugin                                                                              |
+| Auto rebuild on local changes | Supported                                                        | Only with webpack plugin                                                                              |
+| Asset handling                | Supported                                                        | Only with webpack plugin                                                                              |
+| Headless Browser Testing      | [In Progress](https://github.com/thedodd/trunk/issues/20)        | [Supported](https://rustwasm.github.io/wasm-pack/book/commands/test.html)                             |
+| Supported Targets             | <ul><li><code>wasm32-unknown-unknown</code></li></ul>            | <ul><li><code>wasm32-unknown-unknown</code></li></ul>                                                 |
+| Example Usage                 | [Sample app](./../getting-started/build-a-sample-app.md)             | [Starter template](https://github.com/yewstack/yew-wasm-pack-minimal)                                 |
diff --git a/website/sidebars.json b/website/sidebars.json
@@ -70,7 +70,8 @@
       "more/development-tips",
       "more/css",
       "more/testing",
-      "more/roadmap"
+      "more/roadmap",
+      "more/wasm-build-tools"
     ]
   }
 }