From f96f1131471ca2b3caa0f4ea7780f5b80b1d5dd0 Mon Sep 17 00:00:00 2001
From: TimJentzsch <commits@timjen.net>
Date: Sun, 29 Dec 2024 19:42:55 +0100
Subject: [PATCH] Add `--bundle` option to `web` commands (#195)

# Objective

Closes #68.

Adds the `--bundle` argument to the `bevy build web` and `bevy run web`
commands.
This will pack all files needed for the web into a single folder.
The location of the bundle will be `target/bevy_web/{profile}/{binary}`.

This makes it a lot easier to deploy the app e.g. on itch.io or a
generic web server.
It also unblocks the switch from `trunk` to the Bevy CLI for the Bevy 2D
template: <https://github.com/TheBevyFlock/bevy_new_2d/pull/312>.

# Solution

- Add the `--bundle` option to the build and run web commands.
- Create a new `WebBundle` enum, which can represent a linked or packed
bundle:
- A linked bundle is what we use by default, which is optimized for dev.
It keeps e.g. the asset folder and WASM artifacts in their place to
avoid duplication and copy operations. When running the app, the local
web server will "link" together all the files and folders needed to run
the app.
- A packed bundle is a folder that contains all the necessary web
artifacts. They will be copied in the directory. This option is most
useful to deploy the web app.
---
 Cargo.lock            |   7 ++
 Cargo.toml            |   3 +
 assets/web/index.html |   1 +
 src/build/args.rs     |  13 +++-
 src/build/mod.rs      |  13 +++-
 src/run/args.rs       |   4 +
 src/run/mod.rs        |  16 +++-
 src/run/serve.rs      |  91 ++++++++++------------
 src/web/bundle.rs     | 170 ++++++++++++++++++++++++++++++++++++++++++
 src/web/mod.rs        |   3 +
 10 files changed, 265 insertions(+), 56 deletions(-)
 create mode 100644 src/web/bundle.rs

diff --git a/Cargo.lock b/Cargo.lock
index 6f040a6c..cbda72ef 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -492,6 +492,7 @@ dependencies = [
  "cargo-generate",
  "clap",
  "dialoguer",
+ "fs_extra",
  "regex",
  "reqwest",
  "semver",
@@ -1612,6 +1613,12 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "fs_extra"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+
 [[package]]
 name = "futures-channel"
 version = "0.3.31"
diff --git a/Cargo.toml b/Cargo.toml
index 8d569518..737a9670 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -48,5 +48,8 @@ actix-web = "4.9.0"
 # Opening the app in the browser
 webbrowser = "1.0.2"
 
+# Copying directories
+fs_extra = "1.3.0"
+
 # Optimizing Wasm binaries
 wasm-opt = { version = "0.116.1", optional = true }
diff --git a/assets/web/index.html b/assets/web/index.html
index 476d79a3..b7de1fc0 100644
--- a/assets/web/index.html
+++ b/assets/web/index.html
@@ -65,6 +65,7 @@
 
     <script type="module">
       // Starting the game
+      // The template uses `bevy_app.js`, which will be replaced by the name of the generated JS entrypoint when creating the local web server
       import init from "./build/bevy_app.js";
       init().catch((error) => {
         if (
diff --git a/src/build/args.rs b/src/build/args.rs
index fe463ef1..618a2c8a 100644
--- a/src/build/args.rs
+++ b/src/build/args.rs
@@ -1,4 +1,4 @@
-use clap::{Args, Subcommand};
+use clap::{ArgAction, Args, Subcommand};
 
 use crate::external_cli::{arg_builder::ArgBuilder, cargo::build::CargoBuildArgs};
 
@@ -16,7 +16,7 @@ pub struct BuildArgs {
 impl BuildArgs {
     /// Determine if the app is being built for the web.
     pub(crate) fn is_web(&self) -> bool {
-        matches!(self.subcommand, Some(BuildSubcommands::Web))
+        matches!(self.subcommand, Some(BuildSubcommands::Web(_)))
     }
 
     /// Whether to build with optimizations.
@@ -44,5 +44,12 @@ impl BuildArgs {
 #[derive(Debug, Subcommand)]
 pub enum BuildSubcommands {
     /// Build your app for the browser.
-    Web,
+    Web(BuildWebArgs),
+}
+
+#[derive(Debug, Args)]
+pub struct BuildWebArgs {
+    // Bundle all web artifacts into a single folder.
+    #[arg(short = 'b', long = "bundle", action = ArgAction::SetTrue, default_value_t = false)]
+    pub create_packed_bundle: bool,
 }
diff --git a/src/build/mod.rs b/src/build/mod.rs
index d49f8d0f..445c17d4 100644
--- a/src/build/mod.rs
+++ b/src/build/mod.rs
@@ -1,6 +1,9 @@
+use args::BuildSubcommands;
+
 use crate::{
     external_cli::{cargo, rustup, wasm_bindgen, CommandHelpers},
     run::select_run_binary,
+    web::bundle::{create_web_bundle, PackedBundle, WebBundle},
 };
 
 pub use self::args::BuildArgs;
@@ -10,7 +13,7 @@ mod args;
 pub fn build(args: &BuildArgs) -> anyhow::Result<()> {
     let cargo_args = args.cargo_args_builder();
 
-    if args.is_web() {
+    if let Some(BuildSubcommands::Web(web_args)) = &args.subcommand {
         ensure_web_setup()?;
 
         let metadata = cargo::metadata::metadata_with_args(["--no-deps"])?;
@@ -33,6 +36,14 @@ pub fn build(args: &BuildArgs) -> anyhow::Result<()> {
         if args.is_release() {
             crate::web::wasm_opt::optimize_bin(&bin_target)?;
         }
+
+        if web_args.create_packed_bundle {
+            let web_bundle = create_web_bundle(&metadata, args.profile(), bin_target, true)?;
+
+            if let WebBundle::Packed(PackedBundle { path }) = &web_bundle {
+                println!("Created bundle at file://{}", path.display());
+            }
+        }
     } else {
         cargo::build::command().args(cargo_args).ensure_status()?;
     }
diff --git a/src/run/args.rs b/src/run/args.rs
index 26b4d67d..91afd7dc 100644
--- a/src/run/args.rs
+++ b/src/run/args.rs
@@ -56,4 +56,8 @@ pub struct RunWebArgs {
     /// Open the app in the browser.
     #[arg(short = 'o', long = "open", action = ArgAction::SetTrue, default_value_t = false)]
     pub open: bool,
+
+    // Bundle all web artifacts into a single folder.
+    #[arg(short = 'b', long = "bundle", action = ArgAction::SetTrue, default_value_t = false)]
+    pub create_packed_bundle: bool,
 }
diff --git a/src/run/mod.rs b/src/run/mod.rs
index d5f57ebe..ba3d53db 100644
--- a/src/run/mod.rs
+++ b/src/run/mod.rs
@@ -1,5 +1,6 @@
 use std::path::PathBuf;
 
+use anyhow::Context;
 use args::RunSubcommands;
 
 use crate::{
@@ -8,6 +9,7 @@ use crate::{
         cargo::{self, metadata::Metadata},
         wasm_bindgen, CommandHelpers,
     },
+    web::bundle::{create_web_bundle, PackedBundle, WebBundle},
 };
 
 pub use self::args::RunArgs;
@@ -43,6 +45,18 @@ pub fn run(args: &RunArgs) -> anyhow::Result<()> {
             crate::web::wasm_opt::optimize_bin(&bin_target)?;
         }
 
+        let web_bundle = create_web_bundle(
+            &metadata,
+            args.profile(),
+            bin_target,
+            web_args.create_packed_bundle,
+        )
+        .context("Failed to create web bundle")?;
+
+        if let WebBundle::Packed(PackedBundle { path }) = &web_bundle {
+            println!("Created bundle at file://{}", path.display());
+        }
+
         let port = web_args.port;
         let url = format!("http://localhost:{port}");
 
@@ -58,7 +72,7 @@ pub fn run(args: &RunArgs) -> anyhow::Result<()> {
             println!("Open your app at <{url}>!");
         }
 
-        serve::serve(bin_target, port)?;
+        serve::serve(web_bundle, port)?;
     } else {
         // For native builds, wrap `cargo run`
         cargo::run::command().args(cargo_args).ensure_status()?;
diff --git a/src/run/serve.rs b/src/run/serve.rs
index 5ca53433..1dcc8081 100644
--- a/src/run/serve.rs
+++ b/src/run/serve.rs
@@ -1,8 +1,7 @@
 //! Serving the app locally for the browser.
 use actix_web::{rt, web, App, HttpResponse, HttpServer, Responder};
-use std::path::Path;
 
-use super::BinTarget;
+use crate::web::bundle::{Index, LinkedBundle, PackedBundle, WebBundle};
 
 /// Serve a static HTML file with the given content.
 async fn serve_static_html(content: &'static str) -> impl Responder {
@@ -15,62 +14,52 @@ async fn serve_static_html(content: &'static str) -> impl Responder {
         .body(content)
 }
 
-/// Create the default `index.html` if the user didn't provide one.
-fn default_index(bin_target: &BinTarget) -> &'static str {
-    let template = include_str!(concat!(
-        env!("CARGO_MANIFEST_DIR"),
-        "/assets/web/index.html"
-    ));
-
-    // Insert correct path to JS bindings
-    let index = template.replace(
-        "./build/bevy_app.js",
-        format!("./build/{}.js", bin_target.bin_name).as_str(),
-    );
-
-    // Only static strings can be served in the web app,
-    // so we leak the string memory to convert it to a static reference.
-    // PERF: This is assumed to be used only once and is needed for the rest of the app running
-    // time, making the memory leak acceptable.
-    Box::leak(index.into_boxed_str())
-}
-
 /// Launch a web server running the Bevy app.
-pub(crate) fn serve(bin_target: BinTarget, port: u16) -> anyhow::Result<()> {
-    let index_html = default_index(&bin_target);
-
+pub(crate) fn serve(web_bundle: WebBundle, port: u16) -> anyhow::Result<()> {
     rt::System::new().block_on(
         HttpServer::new(move || {
             let mut app = App::new();
-            let bin_target = bin_target.clone();
 
-            // Serve the build artifacts at the `/build/*` route
-            // A custom `index.html` will have to call `/build/{bin_name}.js`
-            app = app.service(
-                actix_files::Files::new("/build", bin_target.artifact_directory.clone())
-                    // This potentially includes artifacts which we will not need,
-                    // but we can't add the bin name to the check due to lifetime requirements
-                    .path_filter(move |path, _| {
-                        path.file_stem().is_some_and(|stem| {
-                            // Using `.starts_with` instead of equality, because of the `_bg` suffix
-                            // of the WASM bindings
-                            stem.to_string_lossy().starts_with(&bin_target.bin_name)
-                        }) && (path.extension().is_some_and(|ext| ext == "js")
-                            || path.extension().is_some_and(|ext| ext == "wasm"))
-                    }),
-            );
+            match web_bundle.clone() {
+                WebBundle::Packed(PackedBundle { path }) => {
+                    app = app.service(actix_files::Files::new("/", path).index_file("index.html"));
+                }
+                WebBundle::Linked(LinkedBundle {
+                    build_artifact_path,
+                    wasm_file_name,
+                    js_file_name,
+                    index,
+                    assets_path,
+                }) => {
+                    // Serve the build artifacts at the `/build/*` route
+                    // A custom `index.html` will have to call `/build/{bin_name}.js`
+                    app = app.service(
+                        actix_files::Files::new("/build", build_artifact_path)
+                            // This potentially includes artifacts which we will not need,
+                            // but we can't add the bin name to the check due to lifetime
+                            // requirements
+                            .path_filter(move |path, _| {
+                                path.file_name() == Some(&js_file_name)
+                                    || path.file_name() == Some(&wasm_file_name)
+                            }),
+                    );
 
-            // If the app has an assets folder, serve it under `/assets`
-            if Path::new("assets").exists() {
-                app = app.service(actix_files::Files::new("/assets", "./assets"))
-            }
+                    // If the app has an assets folder, serve it under `/assets`
+                    if let Some(assets_path) = assets_path {
+                        app = app.service(actix_files::Files::new("/assets", assets_path))
+                    }
 
-            if Path::new("web").exists() {
-                // Serve the contents of the `web` folder under `/`, if it exists
-                app = app.service(actix_files::Files::new("/", "./web").index_file("index.html"));
-            } else {
-                // If the user doesn't provide a custom web setup, serve a default `index.html`
-                app = app.route("/", web::get().to(|| serve_static_html(index_html)))
+                    match index {
+                        Index::Folder(path) => {
+                            app = app.service(
+                                actix_files::Files::new("/", path).index_file("index.html"),
+                            );
+                        }
+                        Index::Static(contents) => {
+                            app = app.route("/", web::get().to(move || serve_static_html(contents)))
+                        }
+                    }
+                }
             }
 
             app
diff --git a/src/web/bundle.rs b/src/web/bundle.rs
new file mode 100644
index 00000000..b47ca2da
--- /dev/null
+++ b/src/web/bundle.rs
@@ -0,0 +1,170 @@
+use std::{
+    ffi::OsString,
+    fs,
+    path::{Path, PathBuf},
+};
+
+use anyhow::Context;
+
+use crate::{external_cli::cargo::metadata::Metadata, run::BinTarget};
+
+#[derive(Debug, Clone)]
+pub enum Index {
+    /// The folder containing a custom `index.html` file.
+    Folder(PathBuf),
+    /// A static string representing the contents of `index.html`.
+    Static(&'static str),
+}
+
+#[derive(Debug, Clone)]
+pub struct LinkedBundle {
+    /// The path to the folder containing the Wasm and JS build artifacts.
+    pub build_artifact_path: PathBuf,
+    /// The name of the Wasm artifact, in the build folder.
+    pub wasm_file_name: OsString,
+    /// The name of the JS artifact, in the build folder.
+    pub js_file_name: OsString,
+    /// The path to the Bevy assets folder, if it exists.
+    pub assets_path: Option<PathBuf>,
+    /// The index file to serve.
+    pub index: Index,
+}
+
+#[derive(Debug, Clone)]
+pub struct PackedBundle {
+    /// The path to the folder containing the packed web bundle.
+    pub path: PathBuf,
+}
+
+/// A bundle of all the files needed to serve the app in the web.
+#[derive(Debug, Clone)]
+pub enum WebBundle {
+    /// A bundle that needs to be linked together, keeping the files at their original places.
+    /// Most useful during development, to avoid additional copy operations and duplication.
+    Linked(LinkedBundle),
+    /// A bundle packed into a single folder, ready to be deployed on a web server.
+    Packed(PackedBundle),
+}
+
+/// Create a bundle of all the files needed for serving the app in the web.
+///
+/// If `packed` is set to `true`, the files will be packed together in a single folder.
+/// Use this option e.g. to upload it to a web server.
+///
+/// Otherwise, the assets and build artifacts will be kept at their original place
+/// to avoid duplication.
+pub fn create_web_bundle(
+    metadata: &Metadata,
+    profile: &str,
+    bin_target: BinTarget,
+    packed: bool,
+) -> anyhow::Result<WebBundle> {
+    let assets_path = Path::new("assets");
+    // The "_bg" suffix is needed to reference the bindings created by wasm_bindgen,
+    // instead of the artifact created directly by cargo.
+    let wasm_file_name = OsString::from(format!("{}_bg.wasm", bin_target.bin_name));
+    let js_file_name = OsString::from(format!("{}.js", bin_target.bin_name));
+
+    let custom_web_folder = Path::new("web");
+
+    let linked = LinkedBundle {
+        build_artifact_path: bin_target.artifact_directory.clone(),
+        wasm_file_name,
+        js_file_name,
+        assets_path: if assets_path.exists() {
+            Some(assets_path.to_owned())
+        } else {
+            None
+        },
+        index: if custom_web_folder.join("index.html").exists() {
+            Index::Folder(custom_web_folder.to_path_buf())
+        } else {
+            println!("No custom `web` folder found, using defaults.");
+            Index::Static(default_index(&bin_target))
+        },
+    };
+
+    if !packed {
+        return Ok(WebBundle::Linked(linked));
+    }
+
+    let base_path = metadata
+        .target_directory
+        .join("bevy_web")
+        .join(profile)
+        .join(bin_target.bin_name);
+
+    // Remove the previous bundle
+    // The error can be ignored, because the folder doesn't need to exist yet
+    // and the files will also be overwritten if they already exist
+    let _ = fs::remove_dir_all(&base_path);
+
+    // Build artifacts
+    fs::create_dir_all(base_path.join("build"))?;
+    fs::copy(
+        linked.build_artifact_path.join(&linked.wasm_file_name),
+        base_path.join("build").join(&linked.wasm_file_name),
+    )
+    .context("failed to copy WASM artifact")?;
+    fs::copy(
+        linked.build_artifact_path.join(&linked.js_file_name),
+        base_path.join("build").join(&linked.js_file_name),
+    )
+    .context("failed to copy JS artifact")?;
+
+    // Assets
+    if let Some(assets_path) = linked.assets_path {
+        fs_extra::dir::copy(
+            assets_path,
+            &base_path,
+            &fs_extra::dir::CopyOptions {
+                overwrite: true,
+                ..Default::default()
+            },
+        )
+        .context("failed to copy assets")?;
+    }
+
+    // Index
+    let index_path = base_path.join("index.html");
+    match linked.index {
+        Index::Folder(path) => {
+            fs_extra::dir::copy(
+                path,
+                &base_path,
+                &fs_extra::dir::CopyOptions {
+                    overwrite: true,
+                    content_only: true,
+                    ..Default::default()
+                },
+            )
+            .context("failed to copy custom web assets")?;
+        }
+        Index::Static(contents) => {
+            fs::write(index_path, contents).context("failed to create index.html")?;
+        }
+    }
+
+    Ok(WebBundle::Packed(PackedBundle { path: base_path }))
+}
+
+/// Returns the contents of the default `index.html`,
+/// customized to use the name of the generated binary.
+fn default_index(bin_target: &BinTarget) -> &'static str {
+    let template = include_str!(concat!(
+        env!("CARGO_MANIFEST_DIR"),
+        "/assets/web/index.html"
+    ));
+
+    // Insert correct path to JS bindings
+    let index = template.replace(
+        "./build/bevy_app.js",
+        format!("./build/{}.js", bin_target.bin_name).as_str(),
+    );
+
+    // Only static strings can be served in the web app,
+    // so we leak the string memory to convert it to a static reference.
+    // PERF: This is assumed to be used only once and is needed for the rest of the app running
+    // time, making the memory leak acceptable.
+    Box::leak(index.into_boxed_str())
+}
diff --git a/src/web/mod.rs b/src/web/mod.rs
index 0566276a..d4e3500f 100644
--- a/src/web/mod.rs
+++ b/src/web/mod.rs
@@ -1,2 +1,5 @@
+//! Utilities for building and running the app in the browser.
+
+pub(crate) mod bundle;
 #[cfg(feature = "wasm-opt")]
 pub(crate) mod wasm_opt;