examples: always start clean and update running instructions. (#2045)

I've been working with the examples quite a lot and I've commonly
experienced stale database and disk state from running `docker compose
up` in the foreground followed by `ctl+c` to stop and also from
forgetting to run `pnpm backend:down`.

So ... as a systemic solution, I've updated the `example-backend:up`
script in the root package.json to always run `example-backend:down`
first. This means that examples always start with a clean slate and no
weird / stuck table and or disk state.

I also then did a pass through the example READMEs, explaining this and
re-formatting the instructions a touch.

examples/basic-example/README.md

@@ -1,22 +1,60 @@
 # Basic example
 
+This is an example of a basic ElectricSQL app using React. The Electric-specific code is in [`./src/Example.tsx`](./src/Example.tsx).
+
 ## Setup
 
-1. Make sure you've installed all dependencies for the monorepo and built packages
+This example is part of the [ElectricSQL monorepo](../..) and is designed to be built and run as part of the [pnpm workspace](https://pnpm.io/workspaces) defined in [`../../pnpm-workspace.yaml`](../../pnpm-workspace.yaml).
+
+Navigate to the root directory of the monorepo, e.g.:
+
+```shell
+cd ../../
+```
+
+Install and build all of the workspace packages and examples:
+
+```shell
+pnpm install
+pnpm run -r build
+```
+
+Navigate back to this directory:
+
+```shell
+cd examples/basic-example
+```
+
+Start the example backend services using [Docker Compose](https://docs.docker.com/compose/):
+
+```shell
+pnpm backend:up
+```
+
+> Note that this always stops and deletes the volumes mounted by any other example backend containers that are running or have been run before. This ensures that the example always starts with a clean database and clean disk.
+
+Now start the dev server:
 
-From the root directory:
+```shell
+pnpm dev
+```
 
-- `pnpm i`
-- `pnpm run -r build`
+You should see three items listed in the page. These are created when first running the [`./db/migrations`](./db/migrations).
 
-2. Start the docker containers
+Now let's connect to Postgres, e.g.: using `psql`:
 
-`pnpm run backend:up`
+```shell
+psql "postgresql://postgres:password@localhost:54321/electric"
+```
 
-3. Start the dev server
+Insert new data and watch it sync into the page in real time:
 
-`pnpm run dev`
+```sql
+insert into items (id) values (gen_random_uuid());
+```
 
-4. When done, tear down the backend containers so you can run other examples
+When you're done, stop the backend services using:
 
-`pnpm run backend:down`
+```shell
+pnpm backend:down
+```

examples/basic-example/db/migrations/01-create_items_table.sql

@@ -3,11 +3,11 @@ CREATE TABLE IF NOT EXISTS items (
   id TEXT PRIMARY KEY NOT NULL
 );
 
--- Populate the table with 10 items.
+-- Populate the table with 3 items.
 -- FIXME: Remove this once writing out of band is implemented
 WITH generate_series AS (
     SELECT gen_random_uuid()::text AS id
-    FROM generate_series(1, 10)
+    FROM generate_series(1, 3)
 )
 INSERT INTO items (id)
 SELECT id

examples/basic-example/package.json

@@ -11,6 +11,7 @@
     "db:migrate": "dotenv -e ../../.env.dev -- pnpm exec pg-migrations apply --directory ./db/migrations",
     "dev": "vite",
     "build": "vite build",
+    "format": "eslint . --ext ts,tsx --fix",
     "stylecheck": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit"

examples/basic-example/src/Example.tsx

@@ -11,24 +11,6 @@ export const Example = () => {
     table: `items`,
   })
 
-  /*
-  const addItem = async () => {
-    console.log(`'addItem' is not implemented`)
-  }
-
-  const clearItems = async () => {
-    console.log(`'clearItems' is not implemented`)
-  }
-
-      <div className="controls">
-        <button className="button" onClick={addItem}>
-          Add
-        </button>
-        <button className="button" onClick={clearItems}>
-          Clear
-        </button>
-      </div>
-      */
   return (
     <div>
       {items.map((item: Item, index: number) => (

examples/gatekeeper-auth/README.md

@@ -84,6 +84,12 @@ Build the local API image:
 docker compose build api
 ```
 
+Make sure you're starting with a clean slate:
+
+```shell
+docker compose down --volumes
+```
+
 Run `postgres`, `electric` and the `api` services:
 
 ```console
@@ -209,6 +215,12 @@ Build the local docker images:
 docker compose build api caddy
 ```
 
+Make sure you're starting with a clean slate:
+
+```shell
+docker compose down --volumes
+```
+
 Run `postgres`, `electric`, `api` and `caddy` services with the `.env.caddy` env file:
 
 ```shell
@@ -278,6 +290,14 @@ The example in the [`./edge`](./edge) folder contains a small [Deno HTTP server]
 
 Here, we'll run it locally using Docker in order to demonstrate it working with the other services:
 
+Make sure you're starting with a clean slate:
+
+```shell
+docker compose down --volumes
+```
+
+Then:
+
 ```shell
 docker compose --env-file .env.edge up postgres electric api edge
 ```

examples/linearlite/README.md

@@ -1,22 +1,46 @@
 # Linearlite
 
+This is an example Linear clone developed using ElectricSQL.
+
 ## Setup
 
-1. Make sure you've installed all dependencies for the monorepo and built packages
+This example is part of the [ElectricSQL monorepo](../..) and is designed to be built and run as part of the [pnpm workspace](https://pnpm.io/workspaces) defined in [`../../pnpm-workspace.yaml`](../../pnpm-workspace.yaml).
+
+Navigate to the root directory of the monorepo, e.g.:
+
+```shell
+cd ../../
+```
+
+Install and build all of the workspace packages and examples:
+
+```shell
+pnpm install
+pnpm run -r build
+```
+
+Navigate back to this directory:
 
-From the root directory:
+```shell
+cd examples/linearlite
+```
 
-- `pnpm i`
-- `pnpm run -r build`
+Start the example backend services using [Docker Compose](https://docs.docker.com/compose/):
 
-2. Start the docker containers
+```shell
+pnpm backend:up
+```
 
-`pnpm run backend:up`
+> Note that this always stops and deletes the volumes mounted by any other example backend containers that are running or have been run before. This ensures that the example always starts with a clean database and clean disk.
 
-3. Start the dev server
+Now start the dev server:
 
-`pnpm run dev`
+```shell
+pnpm dev
+```
 
-4. When done, tear down the backend containers so you can run other examples
+When you're done, stop the backend services using:
 
-`pnpm run backend:down`
+```shell
+pnpm backend:down
+```

examples/nextjs-example/README.md

@@ -1,22 +1,46 @@
 # Basic Next.js example
 
+This is an example Next.js application developed using ElectricSQL.
+
 ## Setup
 
-1. Make sure you've installed all dependencies for the monorepo and built packages
+This example is part of the [ElectricSQL monorepo](../..) and is designed to be built and run as part of the [pnpm workspace](https://pnpm.io/workspaces) defined in [`../../pnpm-workspace.yaml`](../../pnpm-workspace.yaml).
+
+Navigate to the root directory of the monorepo, e.g.:
+
+```shell
+cd ../../
+```
+
+Install and build all of the workspace packages and examples:
+
+```shell
+pnpm install
+pnpm run -r build
+```
+
+Navigate back to this directory:
 
-From the root directory:
+```shell
+cd examples/nextjs-example
+```
 
-- `pnpm i`
-- `pnpm run -r build`
+Start the example backend services using [Docker Compose](https://docs.docker.com/compose/):
 
-2. Start the docker containers
+```shell
+pnpm backend:up
+```
 
-`pnpm run backend:up`
+> Note that this always stops and deletes the volumes mounted by any other example backend containers that are running or have been run before. This ensures that the example always starts with a clean database and clean disk.
 
-3. Start the dev server
+Now start the dev server:
 
-`pnpm run dev`
+```shell
+pnpm dev
+```
 
-4. When done, tear down the backend containers so you can run other examples
+When you're done, stop the backend services using:
 
-`pnpm run backend:down`
+```shell
+pnpm backend:down
+```

examples/proxy-auth/README.md

@@ -15,21 +15,43 @@ https://github.com/user-attachments/assets/eab62c23-513c-4ed8-a6fa-249b761f8667
 
 ## Setup
 
-1. Make sure you've installed all dependencies for the monorepo and built packages
+This example is part of the [ElectricSQL monorepo](../..) and is designed to be built and run as part of the [pnpm workspace](https://pnpm.io/workspaces) defined in [`../../pnpm-workspace.yaml`](../../pnpm-workspace.yaml).
 
-From the root directory:
+Navigate to the root directory of the monorepo, e.g.:
 
-- `pnpm i`
-- `pnpm run -r build`
+```shell
+cd ../../
+```
 
-2. Start the docker containers
+Install and build all of the workspace packages and examples:
 
-`pnpm run backend:up`
+```shell
+pnpm install
+pnpm run -r build
+```
 
-3. Start the dev server
+Navigate back to this directory:
 
-`pnpm run dev`
+```shell
+cd examples/proxy-auth
+```
 
-4. When done, tear down the backend containers so you can run other examples
+Start the example backend services using [Docker Compose](https://docs.docker.com/compose/):
 
-`pnpm run backend:down`
+```shell
+pnpm backend:up
+```
+
+> Note that this always stops and deletes the volumes mounted by any other example backend containers that are running or have been run before. This ensures that the example always starts with a clean database and clean disk.
+
+Now start the dev server:
+
+```shell
+pnpm dev
+```
+
+When you're done, stop the backend services using:
+
+```shell
+pnpm backend:down
+```