JS_CLIENT_EXAMPLES.md

SheetDB JavaScript Client Examples

This directory contains example applications demonstrating how to use the SheetDB JavaScript client.

Examples

1. Vanilla JavaScript Example (js-client-vanilla.html)

A complete single-page application using vanilla JavaScript (no framework required).

Features:

• Monster CRUD operations (Create, Read, Update, Delete)
• Filtering by danger level
• Sync data from Google Sheets
• No build tools required

To run:

1. Make sure the SheetDB REST API server is running:

   cd sheetdb_server
   python server.py

2. Open js-client-vanilla.html in your web browser

3. The app will connect to http://localhost:8000/api by default

What it demonstrates:

• Direct usage of SheetDB client class
• Fluent query API with filtering and ordering
• Error handling and loading states
• CRUD operations

2. React Example (js-client-react.jsx)

A React application using SheetDB React hooks for state management.

Features:

• React hooks for data fetching (useQuery)
• React hooks for mutations (useMutation)
• Sync hook (useSync)
• Automatic loading and error states
• Context provider for SheetDB client

To run:

1. Create a new React project (if you don't have one):

   npm create vite@latest sheetdb-react-example -- --template react
   cd sheetdb-react-example

2. Install dependencies:

   npm install
   npm install sheetdb-js

3. Copy the example code from js-client-react.jsx to src/App.jsx

4. Make sure the SheetDB REST API server is running:

   cd sheetdb_server
   python server.py

5. Start the React development server:

   npm run dev

6. Open your browser to the URL shown (usually http://localhost:5173)

What it demonstrates:

• SheetDBProvider for context
• useQuery hook for data fetching
• useMutation hook for create/update/delete
• useSync hook for cache refresh
• Automatic refetching after mutations
• Loading and error states

API Overview

Core Client

import { SheetDB } from "sheetdb-js";

const db = new SheetDB("http://localhost:8000/api", {
  apiKey: "your-api-key", // optional
});

// Query data
const monsters = await db
  .table("monsters")
  .filter({ danger_level__gte: 7 })
  .orderBy("name")
  .limit(10)
  .get();

// Create
await db.table("monsters").create({
  name: "Vampire",
  danger_level: 8,
});

// Update
await db.table("monsters").update(1, {
  danger_level: 9,
});

// Delete
await db.table("monsters").delete(1);

// Sync
await db.sync();

React Hooks

import {
  SheetDBProvider,
  useQuery,
  useMutation,
  useSync,
} from "sheetdb-js/react";

// In your root component
<SheetDBProvider value={db}>
  <App />
</SheetDBProvider>;

// In your components
const { data, loading, error, refetch } = useQuery("monsters", {
  filter: { danger_level__gte: 7 },
});

const { mutate, loading, error } = useMutation("monsters", "create");

const { sync, loading, error } = useSync();

Filter Operators

The client supports the same filter operators as the REST API:

• field: Exact match
• field__gte: Greater than or equal
• field__lte: Less than or equal
• field__gt: Greater than
• field__lt: Less than
• field__contains: String contains

Example:

const monsters = await db
  .table("monsters")
  .filter({
    danger_level__gte: 5,
    name__contains: "wolf",
  })
  .get();

Building the Client

If you want to build the SheetDB JavaScript client from source:

cd sheetdb-js
npm install
npm run build

This will create the distribution files in sheetdb-js/dist/.

Testing

To test the examples:

1. Make sure you have a Google Sheet set up with the Monster Hunt Tracker schema
2. Configure the SheetDB server with your credentials
3. Start the server: python sheetdb_server/server.py
4. Open the vanilla JS example in your browser or run the React example
5. Try creating, updating, and deleting monsters
6. Make changes directly in Google Sheets and click "Sync" to see them reflected

Troubleshooting

CORS errors:

• Make sure the SheetDB server has CORS enabled (it should be by default)
• Check that you're accessing the correct URL

Connection refused:

• Verify the SheetDB server is running on port 8000
• Check the console for error messages

API key errors:

• If the server requires an API key, pass it in the SheetDB constructor
• Make sure the key is valid

Data not updating:

• Click the "Sync" button to refresh the cache
• Check the browser console for errors
• Verify the Google Sheet has the correct structure

Next Steps

• Explore the SheetDB documentation
• Learn about cache modes
• Set up public mode for no-auth access
• Build your own application using SheetDB!