refactor: partitioned examples and moved in tests

Examples are now core, demo, or comprehensive, and the core ones contain
E2E tests. I think this is the best architecture for both clarity and
deduplication. Note that the docs haven't been updated for this change yet.

Cargo.toml

@@ -1,12 +1,13 @@
 [workspace]
 members = [
 	"packages/*",
-    "examples/*",
-    "tests/*",
+    "examples/core/*",
+    "examples/demos/*",
+    "examples/comprehensive/*",
     "website",
     # We have the CLI subcrates as workspace members so we can actively develop on them
     # They also can't be a workspace until nested workspaces are supported
-    "tests/basic/.perseus",
-    "tests/basic/.perseus/server",
-    "tests/basic/.perseus/builder"
+    "examples/core/basic/.perseus",
+    "examples/core/basic/.perseus/server",
+    "examples/core/basic/.perseus/builder"
 ]

bonnie.toml

@@ -45,20 +45,11 @@ dev.subcommands.example.cmd = [
     "bonnie copy-subcrates",
     "cd packages/perseus-cli",
     # Point this live version of the CLI at the given example
-    "TEST_EXAMPLE=../../examples/%example cargo run -- %%"
+    "TEST_EXAMPLE=../../examples/%category/%example cargo run -- %%"
 ]
-dev.subcommands.example.args = [ "example" ]
+dev.subcommands.example.args = [ "category", "example" ]
 dev.subcommands.example.desc = "runs the given example using a live version of the cli"
 
-dev.subcommands.test.cmd = [
-    "bonnie copy-subcrates",
-    "cd packages/perseus-cli",
-    # Point this live version of the CLI at the given test
-    "TEST_EXAMPLE=../../tests/%test cargo run -- %%"
-]
-dev.subcommands.test.args = [ "test" ]
-dev.subcommands.test.desc = "runs the given test using a live version of the cli"
-
 site.cmd = "concurrently \"bonnie site export\" \"bonnie site build-tailwind\""
 site.desc = "builds and serves the site for local development (requires `concurrently`)"
 site.subcommands.export.cmd = [
@@ -124,7 +115,7 @@ copy-subcrates.cmd = [
     # The CLI needs the `.perseus/` directory copied in for packaging (and we need to rename `Cargo.toml` to `Cargo.toml.old`)
     "cd packages/perseus-cli",
     "rm -rf ./.perseus",
-    "cp -r ../../tests/basic/.perseus/ .perseus/",
+    "cp -r ../../examples/core/basic/.perseus/ .perseus/",
     "mv .perseus/Cargo.toml .perseus/Cargo.toml.old",
     "mv .perseus/server/Cargo.toml .perseus/server/Cargo.toml.old",
     "mv .perseus/builder/Cargo.toml .perseus/builder/Cargo.toml.old",
@@ -135,14 +126,14 @@ copy-subcrates.cmd = [
     "mkdir -p .perseus/dist/exported",
     # Replace the example's package name with a token the CLI can use (compatible with alternative engines as well)
     # We only need to do this in the root package, the others depend on it
-    "sed -i 's/perseus-test-basic/USER_PKG_NAME/' .perseus/Cargo.toml.old",
+    "sed -i 's/perseus-example-basic/USER_PKG_NAME/' .perseus/Cargo.toml.old",
     # Replace the relative path references with tokens too
-    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus\"/PERSEUS_VERSION/' .perseus/Cargo.toml.old",
-    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus\"/PERSEUS_VERSION/' .perseus/builder/Cargo.toml.old",
+    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus\"/PERSEUS_VERSION/' .perseus/Cargo.toml.old",
+    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus\"/PERSEUS_VERSION/' .perseus/builder/Cargo.toml.old",
     # These will need to be updated as more integrations are added
-    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus\"/PERSEUS_VERSION/' .perseus/server/Cargo.toml.old",
-    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus-actix-web\"/PERSEUS_ACTIX_WEB_VERSION/' .perseus/server/Cargo.toml.old",
-    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus-warp\"/PERSEUS_WARP_VERSION/' .perseus/server/Cargo.toml.old"
+    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus\"/PERSEUS_VERSION/' .perseus/server/Cargo.toml.old",
+    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus-actix-web\"/PERSEUS_ACTIX_WEB_VERSION/' .perseus/server/Cargo.toml.old",
+    "sed -i 's/path = \"\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/\\.\\.\\/packages\\/perseus-warp\"/PERSEUS_WARP_VERSION/' .perseus/server/Cargo.toml.old"
 
 ]
 copy-subcrates.desc = "copies `.perseus/` into the CLI directory for packaging/usage"

examples/.base/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus", features = [ "hydrate" ] }
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
 sycamore = "0.7"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

examples/README.md

@@ -1,15 +1,9 @@
 # Examples
 
-This folder contains examples for Perseus to be used as learning resources! If any of these don't work, please [open an issue](https://github.com/arctic-hen7/perseus/issues/choose) to let us know!
+This folder contains all the examples for Perseus! These are divided into three categories: core examples, which demonstrate core features of Perseus and are used as end-to-end tests; demonstrative examples, which quickly demonstrate how to do certain things with Perseus; and comprehensive examples, which show off whole systems built with Perseus.
 
-These examples are all fully self-contained, and do not serve as examples in the traditional Cargo way, they are each indepedent Perseus apps, just with relative path dependencies so that they use the bleeding edge version of Perseus in this crate. If you want the examples for a particualr version, you should navigate to the appropriate tag for that version in GitHub and then come back to this directory at that point in the commit history.
+There's also a `.base/` folder that contains a template that new examples should be built from. If you'd like to create a new exmaple, you should copy this directory and modify it to your needs, placing your new example in the appropriate category (this will usually be `demos` or `comprehensive`, you should only put it in `core` if you've confirmed this with a maintainer or if you've built the feature it shows off).
 
-*Note: these examples used toto double as end-to-end tests for Perseus. Those have now been moved to the `tests/` directory.*
+Each of the examples here are fully self-contained Perseus apps, though they use relative path dependencies to the bleeding edge versions of the Perseus packages in this repository. They're also designed to be used with the local, bleeding-edge version of the CLI, which can be invoked by running `bonnie dev example <category> <example> <cli-command>`, where `<cli-command>` is any series of arguments you'd provide to the usual Perseus CLI.
 
--   Showcase -- an app that demonstrates all the different features of Perseus, including SSR, SSG, and ISR (this example is actively used for testing/development)
--   Basic -- a simple app that uses the Perseus CLI
-    -   This has `.perseus/` included in Git, it's where that's developed
--   i18n -- a simple app that showcases internationalization in particular
--   Tiny -- the smallest Perseus can get, the _Hello World!_ example
--   Plugins -- an example of creating and integrating plugins into Perseus
--   Fetching -- an example of fetching data at build time and in the browser with `reqwasm`
+If any of these examples don't work, please [open an issue](https://github.com/arctic-hen7/perseus/issues/choose) and let us know!

examples/tiny/Cargo.toml → examples/comprehensive/tiny/Cargo.toml

@@ -6,5 +6,5 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus" }
+perseus = { path = "../../../packages/perseus" }
 sycamore = "0.7"

tests/basic/.perseus/Cargo.toml → examples/core/basic/.perseus/Cargo.toml

@@ -10,9 +10,9 @@ edition = "2018"
 
 [dependencies]
 # We alias here because the package name will change based on whatever's in the user's manifest
-app = { package = "perseus-test-basic", path = "../" }
+app = { package = "perseus-example-basic", path = "../" }
 
-perseus = { path = "../../../packages/perseus" }
+perseus = { path = "../../../../packages/perseus" }
 sycamore = { version = "^0.7.1", features = ["ssr"] }
 sycamore-router = "^0.7.1"
 web-sys = { version = "0.3", features = ["Event", "Headers", "Request", "RequestInit", "RequestMode", "Response", "ReadableStream", "Window"] }

tests/basic/.perseus/builder/Cargo.toml → examples/core/basic/.perseus/builder/Cargo.toml

@@ -12,7 +12,7 @@ default-run = "perseus-builder"
 
 [dependencies]
 perseus-engine = { path = "../" }
-perseus = { path = "../../../../packages/perseus", features = [ "tinker-plugins", "server-side" ] }
+perseus = { path = "../../../../../packages/perseus", features = [ "tinker-plugins", "server-side" ] }
 futures = "0.3"
 fs_extra = "1"
 tokio = { version = "1", features = [ "macros", "rt-multi-thread" ] }

tests/basic/.perseus/server/Cargo.toml → examples/core/basic/.perseus/server/Cargo.toml

@@ -9,9 +9,9 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../../../packages/perseus", features = [ "server-side" ] }
-perseus-actix-web = { path = "../../../../packages/perseus-actix-web", optional = true }
-perseus-warp = { path = "../../../../packages/perseus-warp", optional = true }
+perseus = { path = "../../../../../packages/perseus", features = [ "server-side" ] }
+perseus-actix-web = { path = "../../../../../packages/perseus-actix-web", optional = true }
+perseus-warp = { path = "../../../../../packages/perseus-warp", optional = true }
 perseus-engine = { path = "../" }
 actix-web = { version = "=4.0.0-beta.20", optional = true }
 actix-http = { version = "=3.0.0-beta.18", optional = true } # We need this to prevent breaking changes in the dependency tree

examples/basic/Cargo.toml → examples/core/basic/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus", features = [ "hydrate" ] }
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
 sycamore = "0.7"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

examples/global_state/Cargo.toml → examples/core/global_state/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus", features = [ "hydrate" ] }
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
 sycamore = "0.7"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

examples/i18n/Cargo.toml → examples/core/i18n/Cargo.toml

@@ -7,7 +7,7 @@ edition = "2018"
 
 [dependencies]
 # Perseus itself, which we (amazingly) need for a Perseus app
-perseus = { path = "../../packages/perseus", features = [ "translator-fluent", "hydrate" ] }
+perseus = { path = "../../../packages/perseus", features = [ "translator-fluent", "hydrate" ] }
 # Sycamore, the library Perseus depends on for lower-leve reactivity primitivity
 sycamore = { version = "0.7", features = ["ssr"] }
 sycamore-router = "0.7"

examples/plugins/Cargo.toml → examples/core/plugins/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus" }
+perseus = { path = "../../../packages/perseus" }
 sycamore = "0.7"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

examples/unreactive/Cargo.toml → examples/core/unreactive/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus", features = [ "hydrate" ] }
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
 sycamore = "0.7"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

examples/fetching/Cargo.toml → examples/demos/fetching/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-perseus = { path = "../../packages/perseus", features = [ "hydrate" ] }
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
 sycamore = "0.7"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

packages/perseus-cli/src/prepare.rs

@@ -157,21 +157,26 @@ pub fn prepare(dir: PathBuf, engine_url: &str) -> Result<(), PrepError> {
         // Development
         #[cfg(debug_assertions)]
         let updated_root_manifest = updated_root_manifest
-            .replace("PERSEUS_VERSION", "path = \"../../../packages/perseus\"");
+            .replace("PERSEUS_VERSION", "path = \"../../../../packages/perseus\"");
         #[cfg(debug_assertions)]
         let updated_server_manifest = updated_server_manifest
-            .replace("PERSEUS_VERSION", "path = \"../../../../packages/perseus\"")
+            .replace(
+                "PERSEUS_VERSION",
+                "path = \"../../../../../packages/perseus\"",
+            )
             .replace(
                 "PERSEUS_ACTIX_WEB_VERSION",
-                "path = \"../../../../packages/perseus-actix-web\"",
+                "path = \"../../../../../packages/perseus-actix-web\"",
             )
             .replace(
                 "PERSEUS_WARP_VERSION",
-                "path = \"../../../../packages/perseus-warp\"",
+                "path = \"../../../../../packages/perseus-warp\"",
             );
         #[cfg(debug_assertions)]
-        let updated_builder_manifest = updated_builder_manifest
-            .replace("PERSEUS_VERSION", "path = \"../../../../packages/perseus\"");
+        let updated_builder_manifest = updated_builder_manifest.replace(
+            "PERSEUS_VERSION",
+            "path = \"../../../../../packages/perseus\"",
+        );
 
         // Write the updated manifests back
         if let Err(err) = fs::write(&root_manifest, updated_root_manifest) {