chore: cleanup / improve docs site (#1484)

Partially address #1436

---------

Co-authored-by: Sam Willis <[email protected]>

README.md

@@ -35,7 +35,7 @@ Your Postgres data, in sync, wherever you need it.
 
 ## What is Electric?
 
-Electric provides an [HTTP API](https://next.electric-sql.com/api/http) for syncing [Shapes](https://next.electric-sql.com/guides/shapes) of data from Postgres. This can be used directly or via [client libraries](https://next.electric-sql.com/api/clients/typescript) and [connectors](https://next.electric-sql.com/api/connectors/react).
+Electric provides an [HTTP API](https://next.electric-sql.com/api/http) for syncing [Shapes](https://next.electric-sql.com/guides/shapes) of data from Postgres. This can be used directly or via [client libraries](https://next.electric-sql.com/api/clients/typescript) and [integrations](https://next.electric-sql.com/api/integrations/react).
 
 ### This looks a bit different than the last time I visited?
 
@@ -61,7 +61,7 @@ You can then use the [HTTP API](https://next.electric-sql/api/http) to sync data
 curl -i 'http://localhost:3000/v1/shape/foo?offset=-1'
 ```
 
-Or use one of the clients or connectors, such as the [`useShape`](https://next.electric-sql/api/connectors/react) React hook:
+Or use one of the clients or integrations, such as the [`useShape`](https://next.electric-sql/api/integrations/react) React hook:
 
 ```jsx
 import { useShape } from '@electric-sql/react'

docs/.vitepress/config.mts

@@ -24,13 +24,13 @@ export default defineConfig({
       { text: 'Product', link: '/product/electric', activeMatch: '/product/' },
       { text: 'Guides', link: '/guides/quickstart', activeMatch: '/guides/'},
       { text: 'API', link: '/api/http', activeMatch: '/api/'},
-      { text: 'Examples', link: '/examples/basic', activeMatch: '/examples/'},
+      { text: 'Examples', link: 'https://github.com/electric-sql/electric/tree/main/examples'},
     ],
     sidebar: [
       {
         text: 'About',
         items: [
-          { text: '<code>electric-next</code>', link: '/about' }
+          { text: '<code>electric</code>', link: '/about' }
         ]
       },
       {
@@ -48,7 +48,7 @@ export default defineConfig({
           // { text: 'Usage', link: '/guides/usage' },
           { text: 'Shapes', link: '/guides/shapes' },
           // { text: 'Deployment', link: '/guides/deployment' },
-          { text: 'Writing clients', link: '/guides/write-your-own-client' }
+          // { text: 'Writing clients', link: '/guides/write-your-own-client' }
         ]
       },
       {
@@ -64,12 +64,12 @@ export default defineConfig({
             collapsed: false
           },
           {
-            text: 'Connectors',
+            text: 'Integrations',
             items: [
-              // { text: 'MobX', link: '/api/connectors/mobx' },
-              { text: 'React', link: '/api/connectors/react' },
-              { text: 'Redis', link: '/api/connectors/redis' },
-              // { text: 'TanStack', link: '/api/connectors/tanstack' },
+              // { text: 'MobX', link: '/api/integrations/mobx' },
+              { text: 'React', link: '/api/integrations/react' },
+              // { text: 'Redis', link: '/api/integrations/redis' },
+              // { text: 'TanStack', link: '/api/integrations/tanstack' },
             ],
             collapsed: false
           }
@@ -79,7 +79,7 @@ export default defineConfig({
     siteTitle: false,
     socialLinks: [
       { icon: 'discord', link: 'https://discord.electric-sql.com' },
-      { icon: 'github', link: 'https://github.com/electric-sql/electric-next' }
+      { icon: 'github', link: 'https://github.com/electric-sql/electric' }
     ]
   }
 })

docs/about.md

@@ -36,9 +36,9 @@ What started as tinkering in private now looks certain to be the way forward for
 
 We created a new repo at [electric-sql/electric-next](https://github.com/electric-sql/electric-next) and started by porting the absolute minimum code necessary from the previous repo.
 
-It provides an [HTTP API](/api/http) for syncing [Shapes](/guides/shapes) of data from Postgres. This can be used directly or via [client libraries](/api/clients/typescript) and [connectors](/api/connectors/react).
+It provides an [HTTP API](/api/http) for syncing [Shapes](/guides/shapes) of data from Postgres. This can be used directly or via [client libraries](/api/clients/typescript) and [integrations](/api/integrations/react).
 
-It's also simple to [write your own client](/guides/write-your-own-client) in any language.
+It's also simple to write your own client in any language.
 
 ## Why build a new system?
 
@@ -248,7 +248,7 @@ You can sync data into:
 
 - apps, replacing data fetching with data sync
 - development environments, for example syncing data into [an embedded PGlite](/product/pglite)
-- edge workers and services, for example maintaining a low-latency [edge data cache](/api/connectors/redis)
+- edge workers and services, for example maintaining a low-latency [edge data cache](/api/integrations/redis)
 - local AI systems running RAG, as per the example below
 
 <figure>
@@ -282,8 +282,8 @@ At the time of writing this document, we are early in the development of `electr
 However, even just with the first release of `electric-next` you can already sync partial subsets of data from a Postgres database into a wide variety of clients and environments, for example:
 
 - syncing data into local apps using the [TypeScript](/api/clients/typescript) and [Elixir](/api/clients/elixir) clients
-- replacing hot-path data fetching and database queries in apps using [React](/api/connectors/react), [MobX](/api/connectors/react) and [TanStack](/api/connectors/tanstack)
-- maintain live caches with automatic invalidation, as per [our Redis connector](/api/connectors/redis)
+- replacing hot-path data fetching and database queries in apps using [React](/api/integrations/react), [MobX](/api/integrations/react) and [TanStack](/api/integrations/tanstack)
+- maintain live caches with automatic invalidation, as per [our Redis example](https://github.com/electric-sql/electric/blob/main/examples/redis-client/src/index.ts)
 
 ### Roadmap
 
@@ -301,7 +301,7 @@ See the:
 
 - [Quickstart guide](/guides/quickstart)
 - [API docs](/api/http)
-- [Examples](/examples/basic)
+- [Examples](https://github.com/electric-sql/electric/tree/main/examples)
 
 If you have any questions or need support, ask on the `#help-and-support` channel in the [Electric Discord](https://discord.electric-sql.com).
 

docs/api/clients/typescript.md

@@ -81,4 +81,4 @@ shape.subscribe(shapeData => {
 })
 ```
 
-See the [Examples](/examples/basic) and [Connectors](/api/connectors/react) for more usage examples.
+See the [Examples](https://github.com/electric-sql/electric/tree/main/examples) and [integrations](/api/integrations/react) for more usage examples.

docs/api/http.md

@@ -95,4 +95,4 @@ The server holds open the request until either a timeout (returning `204 No cont
 
 The algorithm for consuming the HTTP API described above can be implemented from scratch for your application. Howerver, it's typically implemented by clients that can be re-used and provide a simpler interface for application code.
 
-There are a number of existing clients, such as the [TypeScript](/api/clients/typescript) and [Elixir](/api/clients/elixir) clients. If one doesn't exist for your language or environment, we hope that the pattern is simple enough that you should be able to [write your own client](/guides/write-your-own-client) quite simply.
+There are a number of existing clients, such as the [TypeScript](/api/clients/typescript) and [Elixir](/api/clients/elixir) clients. If one doesn't exist for your language or environment, we hope that the pattern is simple enough that you should be able to write your own client quite simply.

docs/api/integrations/react.md

@@ -0,0 +1,38 @@
+---
+outline: deep
+---
+
+# React integration
+
+To use Electric with React, we maintain a React provider and hook to simplify reading shape data in components.
+
+Example usage in a component.
+```tsx
+import { useShape } from "@electric-sql/react"
+
+export default function MyComponent() {
+  const { isUpToDate, data: fooData } = useShape({
+    url: `http://localhost:3000/v1/shape/foo`,
+  })
+
+  if (!isUpToDate) {
+    return <div>loading</div>
+  }
+
+  return (
+    <div>
+      {data.map(foo => <div>{foo.title}</div>)}
+    </div>
+  )
+}
+```
+
+You should wrap your application with a `ShapeProvider` which maintains a global cache of Shapes and ShapeStreams.
+
+Other helpful functions:
+
+- `useShapeContext` — access the Shape Context
+- `preloadShape` — useful to call in route loading functions or elsewhere when you want to ensure Shape data is loaded before rendering a route or component.
+- `getShapeStream` — get (or create) a ShapeStream off the global cache
+- `getShape` — get (or create) a Shape off the global cache
+

docs/guides/quickstart.md

@@ -4,7 +4,7 @@ outline: 2
 
 # Quickstart
 
-This guide will get you up and running with `electric-next` and real-time sync of your Postgres data. First using the [HTTP API](/api/http) directly. Then using our [TypeScript client](/api/clients/typescript) with a [React hook](/api/connectors/react) to sync data into a simple application.
+This guide will get you up and running with `electric-next` and real-time sync of your Postgres data. First using the [HTTP API](/api/http) directly. Then using our [TypeScript client](/api/clients/typescript) with a [React hook](/api/integrations/react) to sync data into a simple application.
 
 ## Setup
 

docs/guides/shapes.md

@@ -4,4 +4,10 @@ outline: deep
 
 # Shapes
 
-This page is under construction.
+Shapes are the core primitive for controlling sync in the ElectricSQL system.
+
+Local apps establish shape subscriptions. This syncs data over the [http](/api/http) API from the Electric server onto the local device.
+
+The Electric sync service maintains shape subscriptions and streams any new data and data changes onto the local device. In this way, local devices can sync a sub-set of a larger database for interactive local use.
+
+Local apps ask the server for a specific set of related data that gets synced to the device. The central Postgres instance will often have too much data to fit on any one device, so shapes allow us to sync only a required subset of data onto the device. There is a balance between local data availability and storage usage on the device that is unique to every application, and shapes allow you to balance those properties while maintaining required guarantees.

docs/guides/usage.md

@@ -4,4 +4,4 @@ outline: deep
 
 # Usage guide
 
-See the [Quickstart](./quickstart) and [Examples](../examples/basic).
+See the [Quickstart](./quickstart) and [Examples](https://github.com/electric-sql/electric/tree/main/examples).

docs/index.md

@@ -53,4 +53,4 @@ Why build APIs and write code to fetch data over the network when you could just
 
 <br />
 <br />
--->
+-->