diff --git a/examples/basic-example/README.md b/examples/basic-example/README.md index 2d0e1de22d..c96bb2d705 100644 --- a/examples/basic-example/README.md +++ b/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 +``` \ No newline at end of file diff --git a/examples/basic-example/db/migrations/01-create_items_table.sql b/examples/basic-example/db/migrations/01-create_items_table.sql index 55865a2769..05cec7ab9a 100644 --- a/examples/basic-example/db/migrations/01-create_items_table.sql +++ b/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 diff --git a/examples/basic-example/package.json b/examples/basic-example/package.json index 595f4fb9e8..b47c1ae9de 100644 --- a/examples/basic-example/package.json +++ b/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" diff --git a/examples/basic-example/src/Example.tsx b/examples/basic-example/src/Example.tsx index 3ae18fc9e5..797fc72e6f 100644 --- a/examples/basic-example/src/Example.tsx +++ b/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`) - } - -
- - -
- */ return (
{items.map((item: Item, index: number) => ( diff --git a/examples/gatekeeper-auth/README.md b/examples/gatekeeper-auth/README.md index 840aa64281..ce7ca4d512 100644 --- a/examples/gatekeeper-auth/README.md +++ b/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 ``` diff --git a/examples/linearlite/README.md b/examples/linearlite/README.md index 88f23c4b8f..04c7cb12b8 100644 --- a/examples/linearlite/README.md +++ b/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 +``` \ No newline at end of file diff --git a/examples/nextjs-example/README.md b/examples/nextjs-example/README.md index e8622a9ea0..98c672f631 100644 --- a/examples/nextjs-example/README.md +++ b/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 +``` \ No newline at end of file diff --git a/examples/proxy-auth/README.md b/examples/proxy-auth/README.md index 4c691dcc36..11d1ea7950 100644 --- a/examples/proxy-auth/README.md +++ b/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 +``` diff --git a/examples/redis-sync/README.md b/examples/redis-sync/README.md index f98dc20940..4f8ace0ed6 100644 --- a/examples/redis-sync/README.md +++ b/examples/redis-sync/README.md @@ -6,27 +6,79 @@ You don't need to manage cache invalidation seperately or set expiry dates of TT ## 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/redis-sync +``` -4. Connect a redis client to see the data in redis: -- `hkeys items` — see all the keys -- `kgetall items` — see keys/values -- `monitor` — run this to see updates as they come in. Try running this while making changes -to the items table in Postgres. +Start the example backend services using [Docker Compose](https://docs.docker.com/compose/): -5. When done, tear down the backend containers so you can run other examples +```shell +pnpm backend:up +``` -`pnpm run backend:down` +> 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 +``` + +Connect a redis client to see the data in redis, e.g.: + +```shell +redis-cli -h 127.0.0.1 -p 6379 +``` + +To see all the keys: + +```console +redis> HKEYS items +``` + +See all the keys and values: + +```console +redis> KGETALL items +``` + +See all updates as they come in: + +```console +MONITOR +``` + +Try running this while making changes to the items table in Postgres, e.g. using `psql`: + +```shell +psql "postgresql://postgres:password@localhost:54321/electric" +``` + +Insert new data and watch it sync into Redis in real time: + +```sql +insert into items (id, title) values (gen_random_uuid(), 'foo'); +``` + +When you're done, stop the backend services using: + +```shell +pnpm backend:down +``` diff --git a/examples/remix-basic/README.md b/examples/remix-basic/README.md index 49a66ab337..9e074e42f9 100644 --- a/examples/remix-basic/README.md +++ b/examples/remix-basic/README.md @@ -1,22 +1,46 @@ # Basic Remix example +This is an example Remix app 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/remix-basic +``` -- `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 +``` \ No newline at end of file diff --git a/examples/tanstack-example/README.md b/examples/tanstack-example/README.md index c60d288472..569c64bae1 100644 --- a/examples/tanstack-example/README.md +++ b/examples/tanstack-example/README.md @@ -1,24 +1,48 @@ # Basic Tanstack Query example -[demo](https://x.com/msfstef/status/1828763769498952173) +This is an example TanStack application developed using ElectricSQL for read path sync, together with Tanstack Query for local writes with optimistic state. + +See the [Electric <> Tanstack integration docs](https://electric-sql.com/docs/integrations/tanstack) for more context and a [video of the example running here](https://x.com/msfstef/status/1828763769498952173). ## 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/tanstack-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 +``` \ No newline at end of file diff --git a/examples/todo-app/README.md b/examples/todo-app/README.md index 4948e9769b..ce69e3e8ed 100644 --- a/examples/todo-app/README.md +++ b/examples/todo-app/README.md @@ -1,22 +1,46 @@ # Todo example +This is a classic TodoMVC example app, 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/todo-app +``` -- `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 +``` \ No newline at end of file diff --git a/package.json b/package.json index dab5c2db14..a92aeac659 100644 --- a/package.json +++ b/package.json @@ -6,8 +6,9 @@ "dotenv-cli": "^7.4.2" }, "scripts": { - "example-backend:up": "dotenv -e .env.dev -- docker compose -f ./.support/docker-compose.yml up -d ", "example-backend:down": "dotenv -e .env.dev -- docker compose -f .support/docker-compose.yml down --volumes", + "example-backend:just_up": "dotenv -e .env.dev -- docker compose -f ./.support/docker-compose.yml up -d", + "example-backend:up": "pnpm example-backend:down && pnpm example-backend:just_up", "stylecheck-all": "pnpm --if-present --recursive run stylecheck", "ci:version": "pnpm exec changeset version", "ci:publish": "pnpm '/^ci:publish:.+/'",