Refactor example dependency toggling and docs

Author: steida

examples/README.md

@@ -1,10 +1,12 @@
 # Examples
 
-## Dependency Management
+## Testing examples
 
-During the preview phase, examples use monorepo dependencies (`workspace:*`) for local development and testing. After the official release, dependencies will point to published packages on npm.
+To test an example, move its directory out of Evolu monorepo. Otherwise, package managers will not work correctly. Examples are meant to work in isolation.
+
+If you are using Yarn, you must install peer dependencies manually.
 
-To switch between development and production modes, use:
+## Toggle dependencies
 
 ```bash
 pnpm examples:toggle-deps
@@ -13,10 +15,4 @@ pnpm examples:toggle-deps
 This script toggles all example dependencies between:
 
 - **Development**: `workspace:*` (uses local monorepo packages)
-- **Production**: `npm:@evolu/package@latest` (uses published packages)
-
-## Testing Examples
-
-To test an example, move its directory out of Evolu monorepo. Otherwise, package managers will not work correctly. Examples are meant to work in isolation.
-
-If you are using Yarn, you must install peer dependencies manually.
+- **Production**: `latest` (uses published packages)

examples/angular-vite-pwa/src/app/app.config.ts

@@ -11,10 +11,10 @@ import { Schema } from "./schema";
 const evolu = createEvolu(evoluWebDeps)(Schema, {
   name: getOrThrow(SimpleName.from("angular-vite-pwa-minimal")),
 
-  ...(typeof window !== "undefined" &&
-    window.location.hostname === "localhost" && {
-      transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
-    }),
+  // ...(typeof window !== "undefined" &&
+  //   window.location.hostname === "localhost" && {
+  //     transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
+  //   }),
 });
 
 // This injection token allows us to use Angular's dependency injection to get

examples/react-electron/components/EvoluMinimalExample.tsx

@@ -26,11 +26,9 @@ const Schema = {
 const evolu = Evolu.createEvolu(evoluReactWebDeps)(Schema, {
   name: Evolu.SimpleName.orThrow("minimal-example"),
 
-  reloadUrl: "/playgrounds/minimal",
-
-  ...(process.env.NODE_ENV === "development" && {
-    transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
-  }),
+  // ...(process.env.NODE_ENV === "development" && {
+  //   transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
+  // }),
 });
 
 // Creates a typed React Hook returning an instance of Evolu.

examples/react-expo/app/index.tsx

@@ -54,9 +54,9 @@ export default function Index(): React.ReactNode {
         ),
         encryptionKey: authResult?.owner?.encryptionKey,
         externalAppOwner: authResult?.owner,
-        ...(process.env.NODE_ENV === "development" && {
-          transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
-        }),
+        // ...(process.env.NODE_ENV === "development" && {
+        //   transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
+        // }),
       });
 
       setEvolu(evolu as EvoluType<typeof Schema>);

examples/react-nextjs/components/EvoluMinimalExample.tsx

@@ -28,11 +28,9 @@ const Schema = {
 const evolu = Evolu.createEvolu(evoluReactWebDeps)(Schema, {
   name: Evolu.SimpleName.orThrow("minimal-example"),
 
-  reloadUrl: "/playgrounds/minimal",
-
-  ...(process.env.NODE_ENV === "development" && {
-    transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
-  }),
+  // ...(process.env.NODE_ENV === "development" && {
+  //   transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
+  // }),
 });
 
 // Creates a typed React Hook returning an instance of Evolu.

examples/react-vite-pwa/src/components/EvoluMinimalExample.tsx

@@ -35,12 +35,11 @@ const evolu = Evolu.createEvolu(evoluReactWebDeps)(Schema, {
   name: Evolu.SimpleName.orThrow(
     `${service}-${authResult?.owner?.id ?? "guest"}`,
   ),
-  reloadUrl: "/",
   encryptionKey: authResult?.owner?.encryptionKey,
   externalAppOwner: authResult?.owner,
-  ...(process.env.NODE_ENV === "development" && {
-    transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
-  }),
+  // ...(process.env.NODE_ENV === "development" && {
+  //   transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
+  // }),
 });
 
 // Creates a typed React Hook returning an instance of Evolu.

examples/svelte-vite-pwa/src/App.svelte

@@ -23,11 +23,9 @@
   const evolu = Evolu.createEvolu(evoluSvelteDeps)(Schema, {
     name: Evolu.SimpleName.orThrow("minimal-example"),
 
-    reloadUrl: "/",
-
-    ...(process.env.NODE_ENV === "development" && {
-      transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
-    }),
+    // ...(process.env.NODE_ENV === "development" && {
+    //   transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
+    // }),
   });
 
   /**

examples/vue-vite-pwa/src/App.vue

@@ -55,15 +55,10 @@ const DatabaseSchema = {
 type DatabaseSchema = typeof DatabaseSchema;
 
 const evolu = createEvolu(evoluWebDeps)(DatabaseSchema, {
-  reloadUrl: "/",
   name: SimpleName.orThrow("minimal-example"),
-  ...(isDev && {
-    transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
-  }),
-  indexes: (create) => [
-    create("todoCreatedAt").on("todo").column("createdAt"),
-    create("todoCategoryCreatedAt").on("todoCategory").column("createdAt"),
-  ],
+  // ...(isDev && {
+  //   transports: [{ type: "WebSocket", url: "ws://localhost:4000" }],
+  // }),
 });
 
 provideEvolu(evolu);

pnpm-workspace.yaml

@@ -3,6 +3,8 @@ packages:
   - packages/*
   - examples/*
 
+# Catalogs enforce consistent versions across the monorepo, especially important
+# for react-expo which requires exact React versions
 catalogs:
   react19:
     "@types/react": ~19.1.13

scripts/toggle-examples-deps.ts

@@ -5,23 +5,64 @@ import path from "node:path";
 
 const examplesDir = path.resolve(__dirname, "../examples");
 
-type Mode = "Development" | "Production";
+type Mode = "development" | "production";
+
+// Hardcoded catalogs matching pnpm-workspace.yaml
+const CATALOGS = {
+  react19: {
+    "@types/react": "~19.1.13",
+    "@types/react-dom": "~19.1.9",
+    react: "19.1.0",
+    "react-dom": "19.1.0",
+  },
+} as const;
 
 // Function to toggle the mode for a single example
 const toggleMode = (examplePath: string, mode: Mode): void => {
   const packageJsonPath = path.join(examplePath, "package.json");
   const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
 
+  // Toggle @evolu/* dependencies
   for (const dep in packageJson.dependencies) {
-    if (!dep.startsWith("@evolu/")) {
-      continue;
+    if (dep.startsWith("@evolu/")) {
+      if (mode === "production") {
+        packageJson.dependencies[dep] = `latest`;
+      } else if (mode === "development") {
+        packageJson.dependencies[dep] = `workspace:*`;
+      }
     }
+  }
 
-    if (mode === "Production") {
-      packageJson.dependencies[dep] = `npm:${dep}@latest`;
-    } else if (mode === "Development") {
-      packageJson.dependencies[dep] = `workspace:*`;
+  // Toggle catalog references in both dependencies and devDependencies
+  const toggleCatalogRefs = (deps: Record<string, string>): void => {
+    for (const dep in deps) {
+      const value = deps[dep];
+      if (mode === "production" && value.startsWith("catalog:")) {
+        const catalogName = value.replace("catalog:", "");
+        const catalog = CATALOGS[catalogName as keyof typeof CATALOGS];
+        if (catalog && dep in catalog) {
+          deps[dep] = catalog[dep as keyof typeof catalog];
+        }
+      } else if (mode === "development") {
+        // Find which catalog this dep belongs to
+        for (const [catalogName, catalogDeps] of Object.entries(CATALOGS)) {
+          if (
+            dep in catalogDeps &&
+            catalogDeps[dep as keyof typeof catalogDeps] === value
+          ) {
+            deps[dep] = `catalog:${catalogName}`;
+            break;
+          }
+        }
+      }
     }
+  };
+
+  if (packageJson.dependencies) {
+    toggleCatalogRefs(packageJson.dependencies);
+  }
+  if (packageJson.devDependencies) {
+    toggleCatalogRefs(packageJson.devDependencies);
   }
 
   fs.writeFileSync(
@@ -53,7 +94,7 @@ const askForMode = async (): Promise<Mode> => {
       type: "list",
       name: "mode",
       message: "Which mode do you want to switch to?",
-      choices: ["Development", "Production"],
+      choices: ["development", "production"],
     },
   ]);