# Bevy Web Initiative

> [!Warning]
>
> **DRAFT**. Once reviewed and approved by the working group, it can be published as a Discussion on the Bevy repo to invite a broader discussion.

In this initiative, we aim to improve the process of developing web applications with Bevy.
It's part of the **Bevy CLI** working group, [join us on Discord](https://discord.com/channels/691052431525675048/1278871953721262090) if you wish to participate!

> [!Note]
>
> The Bevy CLI is about more than just the web functionality (e.g. also linting Bevy apps).
> However, this design document is scoped to just the web aspects.

## Motivation

Developing Bevy apps for the browser has long been a second class citizen.
This is problematic, because many users' first contact with Bevy is in its web form -- through the Bevy game jam.

One goal of the Bevy game jam is to pull in new users and encourage them to get started with Bevy. But through the nature of game jams, web apps have a higher chance of being played and rated. Hence, having a good web dev experience can make a big difference in onboarding and user success.

Let's compare how you can run the app on native vs. in the browser:

### Native

Setup:
1. Create a basic Bevy app scaffold.

Dev cycle:
1. Run `cargo run`, to build and run the app.

### Web

Setup:

1. Create a basic Bevy app scaffold.
2. Run `rustup target add wasm32-unknown-unknown`, to be able to compile to Wasm.
3. Run `cargo install wasm-bindgen-cli`, which can create JS bindings for the Wasm executable.
4. Add an `index.html` file, which is the entrypoint for the web application.

Dev cycle:

1. Run `cargo build --target wasm32-unknown-unknown` to build the app for Wasm.
2. Run `wasm-bindgen` (with sensible arguments) to create JS bindings for the Wasm executable.
3. Bundle up the `index.html`, Wasm, JS and asset files into a folder.
4. Serve the folder with a local web server. Tools like `trunk` can simplify this process.

Developing for the browser is more challenging than native because of the numerous steps required. This leads to developers writing custom scripts to automate the process, fracturing the community, and the increased number of steps expands the margin for error.

And with all of this work, you won't even get a *good* product: Wasm binaries have quite different needs than native builds. File size, for example, is often more important than speed because it determines the loading times of your app. Cargo's `--release` profile doesn't prioritize this by default, however, hurting player experience on the web. You can amend this by configuring custom profiles, but you must remember to use them for all your web builds.

The Bevy CLI abstracts over the difficulties of building games for Wasm by reducing the above steps into a single command, and providing sane defaults that developers rarely need to override.

## Design Guidelines

So now that we want to develop a Bevy CLI and use it to improve the web dev experience, we need to set some general design guidelines to streamline this process.

- **Works out of the box**: Running a web app should be as simple as running a native app, with no additional setup required. All necessary tools should be bundled into the CLI or installed automatically.
- **Familiar API**: Users are already familiar with the `cargo` CLI. They shouldn't have to learn many new commands to be able to use the Bevy CLI. We should reuse as many command arguments as possible to make it easy to get started.
- **Good defaults**: Web apps have different requirements than native apps. For web builds, we should set sensible defaults so that most users do not have to customize the commands.
- **Configurable**: For power users (e.g. developers of commercial Bevy apps), we still want to retain their full control. They shouldn't have to switch back off the Bevy CLI just because a part of the build process isn't configurable. In general, the Bevy CLI should allow the same configuration options as if you would use `cargo` directly.

## MVP Functionality

Here is an overview of the functionality we want to include in the first user-facing release of the Bevy CLI:

- **Tool installation**: All necessary tools should be installed automatically (after asking the user).
- **Integrated web server**: The Bevy CLI should be able to directly serve web app locally. A sensible default `index.html` should be provided automatically if the user didn't set one up.
- **Good defaults**: Web builds should use compilation profiles optimized for the web. Debug builds should favor iteration times (including build, bundling, loading, etc.) while release builds should favor performance (both load and run time).

## Future Functionality

Beyond the MVP, we can already envision other functionality that would benefit users, but is either not critical to get working or requires a lot more implementation work:

- **Support for `no_std`**: The Bevy community, spearheaded by @bushrat, is currently pushing forward to support using `no_std` in Bevy apps. This not only unlocks an entirely new set of platforms to target with Bevy apps, but also opens up the use of the [`wasm32v1-none` target](https://doc.rust-lang.org/beta/rustc/platform-support/wasm32v1-none.html). Currently, we always use `wasm32-unknown-unknown` for web builds. This target has several issues though: It supports `std`, but only a stubbed version where random parts will not work due to missing support. Additionally, it's a moving target where Rust updates can enable new features that are not supported on every browser yet. That makes it hard to develop for a broad range of browsers. Contrary, the `wasm32v1-none` target is well scoped to the [W3C WebAssembly Core 1.0 spec](https://www.w3.org/TR/wasm-core-1/) and doesn't offer a stubbed `std`. Especially for bigger projects, supporting this target will make a lot of sense, even more so when more parts of Bevy receive `no_std` support.
- **Support for multithreading**: Bevy is designed to be multi-threaded from the ground up. Due to the smart system scheduling, a lot of work can be done in parallel. On the web, all of these efforts are completely negated: It's currently only possible to run the app in a single thread. This leaves a lot of performance on the table. However, there is a light at the end of the tunnel: Wasm is receiving support for shared memory and thus also multi-threading and Rust has experimental support for this. There is a [Bevy initiative to make it multi-threaded on Wasm](https://github.com/bevyengine/bevy/issues/4078), but it has stalled out a bit. One reason might be that [compiling and running the app gets a lot more complicated](https://github.com/bevyengine/bevy/issues/4078#issuecomment-2030735387). That's where we can support the community on the CLI side: With a simple command or flag, we can simplify the workflow and make it easier for more people to contribute to the initiative. Supporting to run the app on a web worker instead of the main thread is a closely related work that will also unlock additional performance.
- **Hot reloading assets**: A big gap between native and web dev is that we currently don't support asset hot reloading for web builds. This has an even bigger impact due to the long build times when targeting the web. Implementing this will be a bigger initiative and require changes both in the CLI and Bevy itself.
- **Automatic rebuild**: While asset hot reloading can already significantly improve the iteration speeds, it's also desireable to automatically rebuild and relaunch the app when either the Rust code or the web assets have changed. This is similar to `cargo watch` for native builds (which we could also integrate into the CLI). The browser tab should automatically refresh once the rebuild is complete. Re-creating the state in the Bevy app (i.e., *hot* reloading) would also be cool, but not necessary for the first iteration of this feature.
- **Streamline UX**: Once more users play around with Bevy web apps due to the simplicity of the CI, we will likely find many small things that can be changed to improve the UX and align the web closer to native. For example, automatically resizing the app window size to the browser `canvas` size. Many of these adjustments will likely need changes in Bevy itself instead of the CLI.

## Prototype

With the [Bevy CLI prototype](https://github.com/TheBevyFlock/bevy_cli), we have already implemented most of the MVP functionality.

You can try it out by running `cargo install --git https://github.com/TheBevyFlock/bevy_cli --locked bevy_cli`.

Play around with the `bevy build web` and `bevy run web` commands. For example, use `bevy run --example breakout web` inside the Bevy repository.
The `bevy build` and `bevy run` commands offer almost the same arguments as their `cargo` counterparts. Use `bevy run web --help` to find out about additional arguments available for web builds.

Note that this is still a _prototype_, which means that some things might not yet work as expected. At the same time, it also means that nothing is set in stone yet -- we will make adjustments based on the feedback we receive.
Of course, you can also contribute directly to the project!