Support workspaces at library level

.github/workflows/CI.yml

@@ -91,4 +91,4 @@ jobs:
       - uses: actions-rs/[email protected]
         with:
           command: fmt
-          args: --all -- --check
+          args: --all -- --check

README.md

@@ -155,6 +155,17 @@ create-rust-app create <project_name>
   - Add a task to the queue with `create_rust_app::tasks::queue()`
   - Run the queue with `cargo run --bin tasks`
 
+- **Workspace Support** (Enabled by default, not tied to a feature flag)
+  - allows you to organize your rust app in workspaces, and changes the defaults for the environment variables that specify paths to various important places.
+  - to organize you project as a workspace:
+    - enable this feature
+    - refactor your codebase into workspaces (see [#194](https://github.com/Wulf/create-rust-app/issues/194))
+    - Optional: set the following environment variables (paths are relative to the directory you call cargo fullstack/backend/run from)
+      - `CRA_MANIFEST_PATH`: default `./frontend/dist/manifest.json` when called from workspace root, `../frontend/dist/manifest.json` otherwise.
+      - `CRA_FRONTEND_DIR`: default `./frontend` when called from workspace root, `../frontend` otherwise.
+      - `CRA_VIEWS_GLOB`: default `backend/views/\*\*/\*.html` when called from workspace root, `views/\*\*/\*.html` otherwise.
+    - Note that in any non-standard setup, you will need to set the above environment variables to the correct values for your project to ensure correct behavior.
+
 ### 2. Code-gen to reduce boilerplate
 
 ```sh

create-rust-app/Cargo.toml

@@ -174,10 +174,13 @@ plugin_storage = [
   "md5",
   "mime_guess",
   "base64",
-  "futures-util"
+  "futures-util",
 ]
 plugin_graphql = []
-plugin_utoipa = ["utoipa", "backend_actix-web"] # for now, only works with actix-web!
+plugin_utoipa = [
+  "utoipa",
+  "backend_actix-web",
+] # for now, only works with actix-web!
 plugin_tasks = ["fang", "tokio"]
 backend_poem = ["poem", "anyhow", "mime_guess", "tokio"]
 backend_actix-web = [

create-rust-app/src/dev/mod.rs

@@ -197,7 +197,11 @@ fn get_features(project_dir: &'static str) -> Vec<String> {
     let cargo_toml = Manifest::from_path(PathBuf::from_iter([project_dir, "Cargo.toml"]))
         .unwrap_or_else(|_| panic!("Could not find \"{}\"", project_dir));
     // .expect(&format!("Could not find \"{project_dir}\""));
-    let deps = cargo_toml.dependencies;
+    let mut deps = cargo_toml.dependencies;
+    if let Some(workspace) = cargo_toml.workspace {
+        // if the manifest has a workspace table, also read dependencies in there
+        deps.extend(workspace.dependencies);
+    }
     let dep = deps.get("create-rust-app").unwrap_or_else(|| {
         panic!(
             "Expected \"{}\" to list 'create-rust-app' as a dependency.",

create-rust-app/src/util/actix_web_utils.rs

@@ -4,6 +4,7 @@ use std::str::FromStr;
 use std::sync::Mutex;
 
 use super::template_utils::SinglePageApplication;
+use super::workspace_utils::frontend_dir;
 use crate::util::template_utils::{to_template_name, DEFAULT_TEMPLATE, TEMPLATES};
 use actix_files::NamedFile;
 #[cfg(debug_assertions)]
@@ -102,13 +103,14 @@ pub async fn render_views(req: HttpRequest) -> HttpResponse {
         #[cfg(debug_assertions)]
         {
             // dev asset serving
-            let asset_path = &format!("./frontend{path}");
+            let asset_path = &format!("{frontend_dir}{path}", frontend_dir = frontend_dir());
             if std::path::PathBuf::from(asset_path).is_file() {
                 println!("ASSET_FILE {path} => {asset_path}");
                 return NamedFile::open(asset_path).unwrap().into_response(&req);
             }
 
-            let public_path = &format!("./frontend/public{path}");
+            let public_path =
+                &format!("{frontend_dir}/public{path}", frontend_dir = frontend_dir());
             if std::path::PathBuf::from(public_path).is_file() {
                 println!("PUBLIC_FILE {path} => {public_path}");
                 return NamedFile::open(public_path).unwrap().into_response(&req);
@@ -118,7 +120,7 @@ pub async fn render_views(req: HttpRequest) -> HttpResponse {
         #[cfg(not(debug_assertions))]
         {
             // production asset serving
-            let static_path = &format!("./frontend/dist{path}");
+            let static_path = &format!("{frontend_dir}/dist{path}", frontend_dir = frontend_dir());
             if std::path::PathBuf::from(static_path).is_file() {
                 return NamedFile::open(static_path).unwrap().into_response(&req);
             }

create-rust-app/src/util/mod.rs

@@ -3,6 +3,9 @@
 /// are exposed directly as create_rust_app::<utilty-fn>.
 ///
 
+/// constants for paths and files in workspaces
+pub(crate) mod workspace_utils;
+
 #[cfg(feature = "backend_actix-web")]
 mod actix_web_utils;
 

create-rust-app/src/util/poem_utils.rs

@@ -1,5 +1,6 @@
 use std::sync::Mutex;
 
+use super::workspace_utils::frontend_dir;
 use poem::http::{StatusCode, Uri};
 use poem::middleware::{AddData, AddDataEndpoint};
 use poem::web::Data;
@@ -95,14 +96,15 @@ pub async fn render_views(uri: &Uri) -> impl IntoResponse {
         #[cfg(debug_assertions)]
         {
             // dev asset serving
-            let asset_path = &format!("./frontend{path}");
+            let asset_path = &format!("{frontend_dir}{path}", frontend_dir = frontend_dir());
             if std::path::PathBuf::from(asset_path).is_file() {
                 println!("ASSET_FILE {path} => {asset_path}");
 
                 return file_response(asset_path).await;
             }
 
-            let public_path = &format!("./frontend/public{path}");
+            let public_path =
+                &format!("{frontend_dir}/public{path}", frontend_dir = frontend_dir());
             if std::path::PathBuf::from(public_path).is_file() {
                 println!("PUBLIC_FILE {path} => {public_path}");
 
@@ -113,7 +115,7 @@ pub async fn render_views(uri: &Uri) -> impl IntoResponse {
         #[cfg(not(debug_assertions))]
         {
             // production asset serving
-            let static_path = &format!("./frontend/dist{path}");
+            let static_path = &format!("{frontend_dir}/dist{path}", frontend_dir = frontend_dir());
             if std::path::PathBuf::from(static_path).is_file() {
                 return file_response(static_path).await;
             }

create-rust-app/src/util/template_utils.rs

@@ -1,3 +1,4 @@
+use super::workspace_utils::{manifest_path, views_glob};
 use lazy_static::lazy_static;
 use std::collections::HashMap;
 use tera::Tera;
@@ -12,7 +13,7 @@ lazy_static! {
     /// all the Templates (html files) included in backend/views/..., uses Tera to bundle the frontend into the template
     /// TODO: ensure this is accurate documentation
     pub static ref TEMPLATES: Tera = {
-        let mut tera = match Tera::new("backend/views/**/*.html") {
+        let mut tera = match Tera::new(views_glob()) {
             Ok(t) => t,
             Err(e) => {
                 println!("Parsing error(s): {e}");
@@ -155,7 +156,7 @@ fn load_manifest_entries() -> ViteManifest {
 
     use serde_json::Value;
     let manifest_json = serde_json::from_str(
-        std::fs::read_to_string(std::path::PathBuf::from("./frontend/dist/manifest.json"))
+        std::fs::read_to_string(std::path::PathBuf::from(manifest_path()))
             .unwrap()
             .as_str(),
     )

create-rust-app/src/util/workspace_utils.rs

@@ -0,0 +1,236 @@
+use std::path::Path;
+use std::sync::OnceLock; // use LazyLock instead once that's stable
+
+/// OnceLock wrapper around output of `cargo locate-project --workspace --message-format=plain`
+///
+/// if the command fails (e.g. if we're in a container or otherwise don't have access to the projects source code), or output can't be parsed,  we return None
+fn cargo_locate_project_workspace() -> Option<&'static str> {
+    static CARGO_LP_WORKSPACE: OnceLock<Option<String>> = OnceLock::new();
+    CARGO_LP_WORKSPACE
+        .get_or_init(|| {
+            let output = std::process::Command::new(env!("CARGO"))
+                .arg("locate-project")
+                .arg("--workspace")
+                .arg("--message-format=plain")
+                .output()
+                .ok()?;
+            let cargo_path = Path::new(std::str::from_utf8(&output.stdout).ok()?.trim());
+            Some(
+                cargo_path
+                    .parent()
+                    .and_then(|p| p.canonicalize().ok().or(Some(p.to_path_buf())))? // if we can't canonicalize the path, just use the original path
+                    .to_str()?
+                    .to_owned(),
+            )
+        })
+        .as_deref()
+}
+
+/// OnceLock wrapper around output of `cargo locate-project --message-format=plain`
+///
+/// if the command fails (e.g. if we're in a container or otherwise don't have access to the projects source code), or output can't be parsed, we return None
+fn cargo_locate_project() -> Option<&'static str> {
+    static CARGO_LP: OnceLock<Option<String>> = OnceLock::new();
+    CARGO_LP
+        .get_or_init(|| {
+            let output = std::process::Command::new(env!("CARGO"))
+                .arg("locate-project")
+                .arg("--workspace")
+                .arg("--message-format=plain")
+                .output()
+                .ok()?;
+            let cargo_toml_path = Path::new(std::str::from_utf8(&output.stdout).ok()?.trim())
+                .parent()
+                .and_then(|p| p.canonicalize().ok().or(Some(p.to_path_buf())))? // if we can't canonicalize the path, just use the original path, paths should be canonicalized anyway but this is just to guarentee it
+                .to_str()?
+                .to_owned();
+            Some(cargo_toml_path)
+        })
+        .as_deref()
+}
+
+/// isolate logic for determining fallback values for the public functions below
+/// we isolate the logic to here so we can ensure consistency and test it
+///
+/// # Arguments
+/// - `cargo_lp_workspace_dir`: the output of `cargo locate-project --workspace --message-format=plain`, or None if the command failed
+/// - `cargo_lp_dir`: the output of `cargo locate-project --message-format=plain`, or None if the command failed
+/// - `comptime_manifest_dir`: the output of `env!("CARGO_MANIFEST_DIR")`
+/// - `special_case`: the value to return if we're in a workspace, but not in the workspace root (like a workspace member)
+/// - `default_case`: the value to return in all other cases
+fn fallback(
+    cargo_lp_workspace_dir: Option<&'static str>,
+    cargo_lp_dir: Option<&'static str>,
+    comptime_manifest_dir: &'static str,
+    special_case: &'static str,
+    default_case: &'static str,
+) -> &'static str {
+    match (cargo_lp_workspace_dir, cargo_lp_dir, comptime_manifest_dir) {
+        // if we're in a container or something, both functions will fail and return None, so this case won't be hit
+        // if we aren't using workspaces, both functions will return the same value, so this case won't be hit
+        // if we are using workspaces, and running in the workspace root, both functions will succeed and return the same value, so this case won't be hit
+        // if we're using workspaces, but executing from, say, the backend directory, the functions will return different values, so this case **will** be hit
+        // if the executable is being run from some other location, the functions might fail, they won't if the executable is being run in a directory containing another cargo project
+        //      - but in that case, the "CARGO_MANIFEST_DIR" env var will not be the same as the output of the second function, so this case won't be hit
+        (Some(workspace_dir), Some(crate_dir), comptime_crate_dir)
+            // if !const_string_comp(workspace_dir,crate_dir) && const_string_comp(comptime_crate_dir, crate_dir) =>
+            if workspace_dir != crate_dir && comptime_crate_dir == crate_dir =>
+        {
+            special_case
+        }
+        _ => default_case,
+    }
+}
+
+/// fn for the path to the project's frontend directory
+pub(crate) fn frontend_dir() -> &'static str {
+    static FRONTEND_DIR: OnceLock<String> = OnceLock::new();
+    FRONTEND_DIR.get_or_init(|| {
+        std::env::var("CRA_FRONTEND_DIR").unwrap_or_else(|_| {
+            fallback(
+                cargo_locate_project_workspace(),
+                cargo_locate_project(),
+                env!("CARGO_MANIFEST_DIR"),
+                "../frontend",
+                "./frontend",
+            )
+            .to_string()
+        })
+    })
+}
+/// fn for the path to the project's manifest.json file
+pub(crate) fn manifest_path() -> &'static str {
+    static MANIFEST_PATH: OnceLock<String> = OnceLock::new();
+    MANIFEST_PATH.get_or_init(|| {
+        std::env::var("CRA_MANIFEST_PATH").unwrap_or_else(|_| {
+            fallback(
+                cargo_locate_project_workspace(),
+                cargo_locate_project(),
+                env!("CARGO_MANIFEST_DIR"),
+                "../frontend/dist/manifest.json",
+                "./frontend/dist/manifest.json",
+            )
+            .to_string()
+        })
+    })
+}
+/// fn for the path to the project's views directory
+pub(crate) fn views_glob() -> &'static str {
+    static VIEWS_GLOB: OnceLock<String> = OnceLock::new();
+    VIEWS_GLOB.get_or_init(|| {
+        std::env::var("CRA_VIEWS_GLOB").unwrap_or_else(|_| {
+            fallback(
+                cargo_locate_project_workspace(),
+                cargo_locate_project(),
+                env!("CARGO_MANIFEST_DIR"),
+                "views/**/*.html",
+                "backend/views/**/*.html",
+            )
+            .to_string()
+        })
+    })
+}
+
+#[cfg(test)]
+mod fallback_logic_tests {
+    use super::fallback;
+
+    #[test]
+    // we want the special case here
+    fn test_both_fail() {
+        assert_eq!(
+            fallback(None, None, "foo/bar", "special_case", "default_case"),
+            "default_case"
+        );
+    }
+
+    #[test]
+    // we want the default case here
+    fn test_not_using_workspaces() {
+        assert_eq!(
+            fallback(
+                Some("foo/bar"),
+                Some("foo/bar"),
+                "foo/bar",
+                "special_case",
+                "default_case"
+            ),
+            "default_case"
+        );
+    }
+
+    #[test]
+    // we want the default case here
+    fn test_using_workspaces_at_workspace_root() {
+        assert_eq!(
+            fallback(
+                Some("foo/bar"),
+                Some("foo/bar"),
+                "foo/bar",
+                "special_case",
+                "default_case"
+            ),
+            "default_case"
+        );
+    }
+
+    #[test]
+    // we want the special case here
+    fn test_using_workspaces_not_at_workspace_root() {
+        assert_eq!(
+            fallback(
+                Some("foo/bar"),
+                Some("foo/bar/baz"),
+                "foo/bar/baz",
+                "special_case",
+                "default_case"
+            ),
+            "special_case"
+        );
+    }
+
+    #[test]
+    /// we can't know what the user would want here, so they should set the environment variables to determine the behavior
+    fn test_compiled_at_root_but_running_somewhere_else() {
+        assert_eq!(
+            fallback(
+                Some("foo/bar"),
+                Some("foo/bar/baz"),
+                "foo/bar",
+                "special_case",
+                "default_case"
+            ),
+            "default_case"
+        );
+    }
+
+    #[test]
+    // we want the default case here
+    fn test_compiled_somewhere_else_but_running_at_root() {
+        assert_eq!(
+            fallback(
+                Some("foo/bar"),
+                Some("foo/bar"),
+                "foo/bar/baz",
+                "special_case",
+                "default_case"
+            ),
+            "default_case"
+        );
+    }
+
+    #[test]
+    /// we can't know what the user would want here, so they should set the environment variables to determine the behavior
+    fn test_running_in_another_cargo_project() {
+        assert_eq!(
+            fallback(
+                Some("foo2/bar2"),
+                Some("foo2/bar2"),
+                "foo/bar/baz",
+                "special_case",
+                "default_case"
+            ),
+            "default_case"
+        );
+    }
+}