@sygnl/supabase-cf

Lightweight Supabase REST API client for Cloudflare Workers with local development support

Zero-dependency Supabase client optimized for Cloudflare Workers edge runtime. Now with local development support via relayze.app!

Features

• Zero dependencies - Optimized for edge runtime
• Type-safe - Full TypeScript support
• Lightweight - Minimal bundle size
• Fast - Direct REST API calls
• Local dev - Test against local Supabase with relayze.app
• Simple API - Familiar Supabase-like interface

Installation

npm install @sygnl/supabase-cf @sygnl/talon

Quick Start

Basic Usage

import { SupabaseClient } from '@sygnl/supabase-cf';

const client = new SupabaseClient({
  url: 'https://your-project.supabase.co',
  serviceKey: 'your-service-role-key',
});

// Insert data
const { data, error } = await client
  .from('users')
  .insert({
    name: 'John Doe',
    email: '[email protected]',
  });

// Query data
const { data: users } = await client
  .from('users')
  .select('*')
  .eq('email', '[email protected]')
  .limit(10)
  .execute();

Local Development

Test against your local Supabase instance using relayze.app:

const client = new SupabaseClient({
  url: 'https://your-project.supabase.co',
  serviceKey: 'your-service-role-key',
  
  // Enable local development
  localDev: {
    enabled: true,
    relayzeUrl: 'https://relayze.app/h/YOUR_ID',
    timeout: 30000,
    debug: true,
  },
});

// Queries automatically route through relayze.app to your local Supabase!

See LOCAL_DEV_SETUP.md for detailed setup instructions.

API Reference

Client Configuration

interface SupabaseConfig {
  /** Supabase project URL */
  url: string;
  
  /** Service role key */
  serviceKey: string;
  
  /** Request timeout in ms (default: 10000) */
  timeout?: number;
  
  /** Number of retries (default: 0) */
  retries?: number;
  
  /** Custom headers */
  headers?: Record<string, string>;
  
  /** Local development config */
  localDev?: {
    enabled: boolean;
    relayzeUrl: string;
    timeout?: number;
    debug?: boolean;
  };
}

Query Builder

// Select
client.from('table')
  .select('*')
  .eq('column', 'value')
  .gt('age', 18)
  .order('created_at', 'desc')
  .limit(10)
  .execute();

// Insert
client.from('table')
  .insert({ name: 'John' });

// Upsert
client.from('table')
  .upsert({ id: 1, name: 'John' });

// Single row
client.from('table')
  .select('*')
  .eq('id', 1)
  .single();

Type Safety

interface Database {
  users: {
    id: number;
    name: string;
    email: string;
  };
}

const result = await client
  .from<Database['users']>('users')
  .select('*')
  .execute();

// TypeScript knows the types!
result.data.forEach(user => {
  console.log(user.name); // ✅ Type-safe
});

Supported Operations

Filters

• eq - Equals
• neq - Not equals
• gt - Greater than
• gte - Greater than or equal
• lt - Less than
• lte - Less than or equal

Modifiers

• select - Choose columns
• order - Sort results
• limit - Limit rows
• offset - Skip rows
• single - Get single row

Data Operations

• insert - Insert rows
• upsert - Insert or update rows

Cloudflare Workers Example

export default {
  async fetch(request: Request, env: Env) {
    const client = new SupabaseClient({
      url: env.SUPABASE_URL,
      serviceKey: env.SUPABASE_SERVICE_KEY,
    });

    const { data } = await client
      .from('logs')
      .insert({
        timestamp: new Date().toISOString(),
        path: new URL(request.url).pathname,
      });

    return new Response(JSON.stringify(data), {
      headers: { 'Content-Type': 'application/json' },
    });
  },
};

Local Development Setup

1. Start local Supabase:

   supabase start

2. Get relayze.app URL:
   Visit relayze.app

3. Run local dev server:

   npx tsx examples/local-dev-server.ts

4. Configure worker:

   localDev: {
     enabled: true,
     relayzeUrl: 'https://relayze.app/h/YOUR_ID',
   }

See LOCAL_DEV_SETUP.md for complete guide.

Why @sygnl/supabase-cf?

• Edge-optimized - Built for Cloudflare Workers
• No bloat - Zero dependencies, small bundle
• Simple - Just the REST API you need
• Local dev - Test locally with relayze.app
• Type-safe - Full TypeScript support

Related Packages

• @sygnl/talon - Bidirectional event delivery (used for local dev)
• relayze.app - WebSocket relay for local development

License

Apache-2.0 © Edge Foundry, Inc.

Links

• npm
• GitHub
• Homepage