npm package: @pagedotapp/page-db-read
Description: PageDbRead - Fetches rows from Supabase via GraphQL using Relay
Author: PageStudio
Latest version: 0.0.0-alpha.14

# @pagedotapp/page-db-read

A database read component that queries data from Supabase using GraphQL/Relay with optional realtime updates support.

## Installation

```bash
npm install @pagedotapp/page-db-read
```

## Usage

### Basic Usage (GraphQL Only)

Ensure your application is wrapped in `RelayEnvironmentProvider`. The component performs a GraphQL query to the `demoCollection` table and lists the rows.

```tsx
import { PageDbRead } from "@pagedotapp/page-db-read"

function Example() {
	return <PageDbRead />
}
```

### With Realtime Updates

To enable realtime updates, wrap the component with `SupabaseProvider`:

```tsx
import { createClient } from "@supabase/supabase-js"
import { PageDbRead, SupabaseProvider } from "@pagedotapp/page-db-read"

// Initialize Supabase client in your app
const supabase = createClient(
	process.env.NEXT_PUBLIC_SUPABASE_URL,
	process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
)

function App() {
	return (
		<SupabaseProvider client={supabase}>
			<PageDbRead />
		</SupabaseProvider>
	)
}
```

When realtime is enabled, the component will:

- Display initial data from GraphQL
- Listen for INSERT, UPDATE, and DELETE events on the demo table
- Automatically update the UI when changes occur
- Show a "Live" indicator when realtime is active

## Props

| Prop             | Type      | Default | Description                                              |
| ---------------- | --------- | ------- | -------------------------------------------------------- |
| `className`      | `string`  | `''`    | Additional CSS class name                                |
| `enableRealtime` | `boolean` | `true`  | Enable realtime updates when Supabase client is provided |

## Features

- **GraphQL Integration**: Uses Relay for efficient data fetching
- **Realtime Updates**: Optional WebSocket-based realtime updates via Supabase
- **Automatic Merging**: Intelligently merges GraphQL and realtime data
- **Visual Indicators**: Shows "Live" badge when realtime is active
- **Optimistic Updates**: New records appear instantly without page refresh
- **Sorted Display**: Records are sorted by creation date (newest first)

## GraphQL Query

The component uses the following GraphQL query (exported as `PageDbReadQuery`):

```graphql
query PageDbReadQuery {
	demoCollection {
		edges {
			node {
				id
				created_at
				text
			}
		}
	}
}
```

## Realtime Configuration

### Prerequisites

1. Enable Realtime in your Supabase project
2. Ensure the `demo` table has Realtime enabled:

```sql
-- Enable realtime for the demo table
ALTER PUBLICATION supabase_realtime ADD TABLE demo;
```

3. Configure Row Level Security (RLS) as needed

### How It Works

The component listens to Postgres changes on the `demo` table:

- **INSERT**: New records appear automatically
- **UPDATE**: Existing records update in place
- **DELETE**: Removed records disappear from the list

## Exported Components and Hooks

- `PageDbRead` - Main component
- `SupabaseProvider` - Context provider for Supabase client
- `useSupabase` - Hook to access Supabase client from context
- `PageDbReadQuery` - GraphQL query for copying to your app

## Styling

The component uses CSS modules with these classes:

- `.dbRead` - Main container
- `.realtimeIndicator` - Live status badge
- `.record` - Individual record item
- `.emptyState` - Shown when no records exist

## Example: Complete Setup

```tsx
// app.tsx
import { RelayEnvironmentProvider } from "react-relay/hooks"
import { createClient } from "@supabase/supabase-js"
import { PageDbRead, SupabaseProvider } from "@pagedotapp/page-db-read"
import { environment } from "./relay-environment"

const supabase = createClient(url, key)

export function App() {
	return (
		<RelayEnvironmentProvider environment={environment}>
			<SupabaseProvider client={supabase}>
				<PageDbRead />
			</SupabaseProvider>
		</RelayEnvironmentProvider>
	)
}
```

## Dependencies

- react >=16.8.0
- react-relay >=14.0.0
- @supabase/supabase-js (optional, for realtime features)

## License

MIT © PageStudio