---
title: 'Build a sample app'
---

Once you have the environment ready, you can either choose to use a starter template that contains
the boilerplate needed for a basic Yew app or manually set up a small project.

## Using a starter template

Install [`cargo-generate`](https://github.com/cargo-generate/cargo-generate) by following their installation instructions
then take the following steps:

### Checkout and customize project

```shell
cargo generate yewstack/yew-trunk-minimal-template
```

### Run project

```shell
trunk serve
```

:::note

Trunk [has a bug](https://github.com/trunk-rs/trunk/issues/852) on windows when `trunk serve` command fails. To workaround the issue you can run `trunk build` before running `trunk serve`.

:::

## Setting up the application manually

### Create Project

To get started, create a new cargo project.

```bash
cargo new yew-app
```

Open the newly created directory.

```bash
cd yew-app
```

### Run a hello world example

To verify the Rust environment is set up, run the initial project using `cargo run`. You should see
a "Hello World!" message.

```bash
cargo run
# output: Hello World!
```

### Setting up the project as 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:

```toml title=Cargo.toml {7}
[package]
name = "yew-app"
version = "0.1.0"
edition = "2021"

[dependencies]
yew = { {{yew_dependency}}, features = ["csr"] }
```

:::info

You only need the feature `csr` if you are building an application.
It will enable the `Renderer` and all client-side rendering-related code.

If you are making a library, do not enable this feature as it will pull in
client-side rendering logic into the server-side rendering bundle.

If you need the Renderer for testing or examples, you should enable it
in the `dev-dependencies` instead.

:::

#### Update main.rs

We need to generate a template that sets up a root Component called `App` which renders a button
that updates its value when clicked. Replace the contents of `src/main.rs` with the following code.

:::note
The call to `yew::Renderer::<App>::new().render()` inside the `main` function 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::Renderer::<App>::with_props(..).render()`.
If you would like to mount your application to a specific element rather than the `<body>` tag, use `yew::Renderer::<App>::with_root(element).render()` where `element` is a `web_sys::Element`.
:::

```rust ,no_run, title=main.rs
use yew::prelude::*;

#[component]
fn App() -> Html {
    let counter = use_state(|| 0);
    let onclick = {
        let counter = counter.clone();
        move |_| {
            let value = *counter + 1;
            counter.set(value);
        }
    };

    html! {
        <div>
            <button {onclick}>{ "+1" }</button>
            <p>{ *counter }</p>
        </div>
    }
}

fn main() {
    yew::Renderer::<App>::new().render();
}
```

#### Create index.html

Finally, add an `index.html` file in the root directory of your app.

```html , title=index.html
<!doctype html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>Yew App</title>
        <body></body>
    </head>
    <body></body>
</html>
```

## View your web application

Run the following command to build and serve the application locally.

```bash
trunk serve
```

:::info
Add option '--open' to open your default browser `trunk serve --open`.
:::

Trunk will rebuild your application if you modify any of its source code files.
By default server will be listening at address '127.0.0.1' and port '8080' => [http://localhost:8080](http://127.0.0.1:8080).
To change it, create the following file and edit as needed:

```toml title="Trunk.toml"
[serve]
# The address to serve on LAN.
address = "127.0.0.1"
# The address to serve on WAN.
# address = "0.0.0.0"
# The port to serve on.
port = 8000
```

## Congratulations

You have now successfully set up your Yew development environment, and built your first web application.

Experiment with this application and review the [examples](./examples.mdx) to further your learning.
