@edge-base/web is the main client SDK for browser environments.

It is designed for apps that need:

• user authentication with session persistence
• direct database access from the client through access rules
• live updates with onSnapshot()
• multiplayer and presence flows with rooms
• storage uploads and file URLs
• client-side function calls, analytics, and web push

If you need privileged or server-only access, use @edge-base/admin instead.

EdgeBase is the open-source edge-native BaaS that runs on Edge, Docker, and Node.js.

This package is one part of the wider EdgeBase platform. For the full platform, CLI, Admin Dashboard, server runtime, docs, and all public SDKs, see the main repository: edge-base/edgebase.

Beta: the package is already usable, but some APIs may still evolve before general availability.

Documentation Map

Use this README for the fast overview, then jump into the docs when you need depth:

• Quickstart Create a project and run EdgeBase locally
• Client SDK Full browser SDK reference and query patterns
• Database Subscriptions Live queries and onSnapshot() patterns
• Authentication Email/password, OAuth, MFA, sessions, passkeys
• Room Client SDK Presence, state, members, signals, and media
• Functions Client SDK Calling EdgeBase functions from the browser
• Analytics Client SDK Event tracking from web clients
• Push Client SDK Web push registration and client-side handling

For AI Coding Assistants

This package ships with an llms.txt file for AI-assisted development.

Use it when you want an agent or code assistant to:

• avoid common API mistakes
• use the correct method signatures
• choose the right database and auth patterns
• prefer the documented EdgeBase flow instead of guessing

You can find it:

• in this package after install: node_modules/@edge-base/web/llms.txt
• in the repository: llms.txt

For deeper behavioral details, pair llms.txt with the docs linked above.

Why This Package

Most browser SDKs stop at auth + CRUD.

@edge-base/web is meant to be the single browser entry point for the whole EdgeBase app surface:

| Capability | Included | |---|---| | Auth | Email/password, OAuth, sessions, auth state | | Database | Query, insert, update, delete | | Database Live | onSnapshot() subscriptions | | Rooms | Presence, room state, signals, media-ready client surface | | Storage | Uploads, bucket access, file URLs | | Functions | Call EdgeBase functions from the browser | | Analytics | Client-side analytics helpers | | Push | Web push registration and message handling |

Installation

npm install @edge-base/web

Starting a brand new project?

npm create edgebase@latest my-app

That scaffold creates a full EdgeBase app and wires in the local CLI for development and deployment.

Read more: Quickstart

Recommended Project Layout

If you already have a frontend app, a good default is to create EdgeBase inside that project as a dedicated subdirectory:

cd your-frontend-project
npm create edgebase@latest edgebase

That gives you a layout like:

your-frontend-project/
  src/
  app/
  package.json
  edgebase/
    edgebase.config.ts
    functions/
    package.json

This is only a recommendation, not a requirement.

You can also:

• create EdgeBase as a completely separate project
• keep frontend and backend in different repos
• use a different subdirectory name if that fits your monorepo better

The main thing we recommend is avoiding scaffolding directly into an existing app root unless that is intentionally how you want to organize the repo.

Quick Start

import { createClient } from '@edge-base/web';

const client = createClient('https://your-project.edgebase.fun');

await client.auth.signIn({
  email: '[email protected]',
  password: 'pass1234',
});

const posts = await client
  .db('app')
  .table('posts')
  .where('published', '==', true)
  .orderBy('createdAt', 'desc')
  .limit(10)
  .getList();

const health = await client.functions.get('health');

console.log(posts.items, health);

app in the example above is your database block name from edgebase.config.ts.

For instance databases, pass both a namespace and an id:

client.db('workspace', 'ws-123');
client.db('user', 'user-123');

Read more: Client SDK

Core API

Once you create a client, these are the main surfaces you will use:

• client.auth Sign up, sign in, sign out, OAuth, MFA flows, and auth state listeners
• client.db(namespace, id?) Query tables, mutate records, and subscribe to live changes
• client.storage Upload files and resolve bucket URLs
• client.functions Call app functions from the browser
• client.room(namespace, roomId) Join realtime rooms for presence, state sync, and signals
• client.analytics Send analytics data from the client
• client.push Register and manage web push flows

Auth

Email and password

await client.auth.signUp({
  email: '[email protected]',
  password: 'pass1234',
  data: {
    displayName: 'June',
  },
});

await client.auth.signIn({
  email: '[email protected]',
  password: 'pass1234',
});

client.auth.onAuthStateChange((user) => {
  console.log('auth changed:', user);
});

OAuth

await client.auth.signInWithOAuth('google');

const result = await client.auth.handleOAuthCallback();
if (result) {
  console.log('signed in with OAuth:', result.user);
}

By default, the browser SDK uses /auth/callback on the current origin as the redirect target.

Read more: Authentication Docs

Database Queries

type Post = {
  id: string;
  title: string;
  published: boolean;
  createdAt: string;
};

const posts = client.db('app').table<Post>('posts');

const latest = await posts
  .where('published', '==', true)
  .orderBy('createdAt', 'desc')
  .limit(20)
  .getList();

await posts.insert({
  title: 'Hello EdgeBase',
  published: true,
});

Read more: Database Client SDK

Database Live

const unsubscribe = client
  .db('app')
  .table('posts')
  .onSnapshot((snapshot) => {
    console.log(snapshot.items);
    console.log(snapshot.changes.added);
  });

// later
unsubscribe();

Use this for feeds, counters, collaborative UIs, moderation dashboards, or any UI that should react instantly to server-side changes.

Read more: Database Subscriptions

Storage

const bucket = client.storage.bucket('avatars');

await bucket.upload('me.jpg', file);

const publicUrl = bucket.getUrl('me.jpg');
console.log(publicUrl);

Read more: Storage Docs

Functions

const result = await client.functions.post('contact/send', {
  email: '[email protected]',
  message: 'Hello from the web SDK',
});

console.log(result);

Read more: Functions Client SDK

Rooms

const room = client.room('game', 'lobby-1');

const summary = await client.getRoomSummary('game', 'lobby-1');
console.log(summary.occupancy.activeMembers);

const summaries = await client.getRoomSummaries('game', ['lobby-1', 'lobby-2']);
console.log(summaries.items.map((item) => item.roomId));

const readiness = await client.checkRoomConnection('game', 'lobby-1');
console.log(readiness.ok);

await room.join();

room.leave();

Use rooms when you need:

• presence
• room state
• peer signals
• multiplayer coordination
• media/session-style realtime flows

Room Media Transports

room.media.transport() is the high-level browser transport entry point.

const transport = room.media.transport({
  provider: 'cloudflare_realtimekit',
});

const capabilities = await room.media.checkReadiness({
  provider: 'cloudflare_realtimekit',
});
console.log(capabilities.issues);

await transport.connect();
await transport.enableAudio();
await transport.enableVideo();

Available providers:

• cloudflare_realtimekit Default managed media path backed by the Room Media control plane
• p2p STUN-only best-effort mesh for lightweight direct calls

The lower-level room.media.realtime.* HTTP wrappers and RoomRealtimeMediaTransport export still exist for raw WebRTC/SFU flows, but room.media.transport() is the recommended browser entry point for new room media integrations.

Read more: Room Client SDK

Which EdgeBase Package Should You Use?

| Package | Use it when | |---|---| | @edge-base/web | You are in the browser or another untrusted client runtime | | @edge-base/admin | You need trusted server/admin access | | @edge-base/ssr | You want cookie-based SSR helpers for frameworks like Next.js | | @edge-base/auth-ui-react | You want headless React auth UI built on top of the web SDK | | @edge-base/react-native | You are building a React Native app |

Docs

• Quickstart
• Client SDK
• Database Live
• Room Client SDK
• Authentication Docs
• Functions Client SDK
• Analytics Client SDK
• Push Client SDK

License

MIT