From c91d3dcfe336406dde26c62f438be885f9c2a24d Mon Sep 17 00:00:00 2001 From: Tom Cavanaugh <61805809+tomgcavanaugh@users.noreply.github.com> Date: Wed, 5 May 2021 14:36:50 -0500 Subject: [PATCH] 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 Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com> Co-authored-by: Simon --- docs/getting-started/build-a-sample-app.md | 62 +++++++++++++++------- docs/getting-started/project-setup.md | 56 ++++++++----------- docs/more/wasm-build-tools.md | 45 ++++++++++++++++ website/sidebars.json | 3 +- 4 files changed, 112 insertions(+), 54 deletions(-) create mode 100644 docs/more/wasm-build-tools.md diff --git a/docs/getting-started/build-a-sample-app.md b/docs/getting-started/build-a-sample-app.md index 335535aa727..b85477a4e70 100644 --- a/docs/getting-started/build-a-sample-app.md +++ b/docs/getting-started/build-a-sample-app.md @@ -2,7 +2,9 @@ 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 @@ -10,7 +12,26 @@ 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::()` inside `main()` starts your application and mounts it to the page's `` tag. +If you would like to start your application with any dynamic properties, you can instead use `yew::start_app_with_props::(..)`. +::: + ```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::()` inside `main()` which starts your app and mounts it to the page's `` tag. -If you would like to start your application with any dynamic properties, you can instead use `yew::start_app_with_props::(..)`. +### 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 @@ -99,24 +127,18 @@ Finally, add an `index.html` file in the root directory of your app: ``` -## 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. \ No newline at end of file diff --git a/docs/getting-started/project-setup.md b/docs/getting-started/project-setup.md index 1d296227295..7edec58ac4a 100644 --- 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 |
  • wasm32-unknown-unknown
|
  • wasm32-unknown-unknown
| -| 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 new file mode 100644 index 00000000000..e6d4855d993 --- /dev/null +++ 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 |
  • wasm32-unknown-unknown
|
  • wasm32-unknown-unknown
| +| 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 index 925fabd3c74..f8d0538ab00 100644 --- 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" ] } }