SheetDB JavaScript Client

JavaScript/TypeScript client for SheetDB - Use Google Sheets as a relational database.

Installation

npm install sheetdb-js

Quick Start

import { SheetDB } from "sheetdb-js";

// Connect to SheetDB REST API
const db = new SheetDB("http://localhost:8000/api");

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

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

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

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

React Hooks

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

function MonsterList() {
  const { data, loading, error } = useQuery("monsters", {
    filter: { danger_level__gte: 7 },
  });

  const { mutate: createMonster } = useMutation("monsters", "create");

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data.map((monster) => (
        <div key={monster.id}>{monster.name}</div>
      ))}
      <button onClick={() => createMonster({ name: "Vampire" })}>
        Add Monster
      </button>
    </div>
  );
}

API Reference

SheetDB Class

Constructor

const db = new SheetDB(baseUrl, options);

• baseUrl: Base URL of the SheetDB REST API
• options.apiKey: Optional API key for authentication

Methods

• table(name): Get a table query builder
• sync(): Trigger cache refresh
• listTables(): Get list of all tables

Table Query Builder

• filter(conditions): Add filter conditions
• orderBy(field): Order results (prefix with - for descending)
• limit(n): Limit number of results
• offset(n): Skip n results
• fields(fieldList): Select specific fields
• get(): Execute query and return results
• create(data): Create a new record
• update(id, data): Update a record
• delete(id): Delete a record

React Hooks

useQuery

const { data, loading, error, refetch } = useQuery(table, options);

useMutation

const { mutate, loading, error } = useMutation(table, operation);

License

MIT

Repository Structure Note

⚠️ Important: This JavaScript client is currently part of the SheetDB monorepo but is a separate component from the Python package.

Current Status:

• Located in sheetdb-js/ directory of the monorepo
• Not included when you pip install sheetdb
• Separate npm package with its own dependencies

Installation (Current):

# Clone the monorepo
git clone https://github.com/yourusername/sheetdb.git
cd sheetdb/sheetdb-js

# Install and build
npm install
npm run build

# Link for local development
npm link

Future Plans:

This component will be split into a separate repository:

• Repository: sheetdb-js (standalone)
• Package: npm install sheetdb-js
• Independent versioning

See REPOSITORY_STRUCTURE.md in the main repo for details.

Development

# Install dependencies
npm install

# Build the package
npm run build

# Watch mode for development
npm run dev

# Run tests (if available)
npm test

Examples

Complete examples are available in the main repository:

• examples/js-client-vanilla.html - Vanilla JavaScript example
• examples/js-client-react.jsx - React example
• examples/react-monster-tracker/ - Full React application

Contributing

This is part of the SheetDB project. See the main repository for contribution guidelines.

---

Part of the SheetDB project - See main documentation