Browser SDK for EdgeBase
Auth, database, realtime, storage, functions, analytics, and rooms for modern web apps
React · Next.js · Vite · Vanilla TS · PWAs
Quickstart · Client SDK Docs · Database Live · Room Docs
--- `@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`](https://www.npmjs.com/package/@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](https://github.com/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](https://edgebase.fun/docs/getting-started/quickstart) Create a project and run EdgeBase locally - [Client SDK](https://edgebase.fun/docs/database/client-sdk) Full browser SDK reference and query patterns - [Database Subscriptions](https://edgebase.fun/docs/database/subscriptions) Live queries and `onSnapshot()` patterns - [Authentication](https://edgebase.fun/docs/authentication) Email/password, OAuth, MFA, sessions, passkeys - [Room Client SDK](https://edgebase.fun/docs/room/client-sdk) Presence, state, members, and signals - [Functions Client SDK](https://edgebase.fun/docs/functions/client-sdk) Calling EdgeBase functions from the browser - [Analytics Client SDK](https://edgebase.fun/docs/analytics/client-sdk) Event tracking from web clients - [Push Client SDK](https://edgebase.fun/docs/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](https://github.com/edge-base/edgebase/blob/main/packages/sdk/js/packages/web/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, and room summaries | | 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 ```bash npm install @edge-base/web ``` Starting a brand new project? ```bash 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](https://edgebase.fun/docs/getting-started/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: ```bash cd your-frontend-project npm create edgebase@latest edgebase ``` That gives you a layout like: ```text 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 ```ts import { createClient } from '@edge-base/web'; const client = createClient('https://your-project.edgebase.fun', { refreshTokenTransport: 'httpOnlyCookie', }); await client.auth.signIn({ email: 'june@example.com', 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); ``` This example assumes the server has `auth.session.cookie.enabled: true`. If it does not, omit `refreshTokenTransport`; body transport remains the compatibility default. `app` in the example above is your database block name from `edgebase.config.ts`. For instance databases, pass both a namespace and an id: ```ts client.db('workspace', 'ws-123'); client.db('user', 'user-123'); ``` Read more: [Client SDK](https://edgebase.fun/docs/database/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 ```ts await client.auth.signUp({ email: 'june@example.com', password: 'pass1234', data: { displayName: 'June', }, }); await client.auth.signIn({ email: 'june@example.com', password: 'pass1234', }); client.auth.onAuthStateChange((user) => { console.log('auth changed:', user); }); ``` ### OAuth ```ts 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. Call `handleOAuthCallback()` in a browser route, not a server route. EdgeBase returns callback fields in the URL fragment, scrubs them before storage or network access, and binds the callback to the exact SDK-started flow. The fragment carries a five-minute completion ticket, never a bearer credential; the SDK atomically posts it to `/api/auth/oauth/exchange`. With the recommended `httpOnlyCookie` transport, JavaScript receives no refresh token and EdgeBase owns a rotating `__Host-` HttpOnly cookie on HTTPS. The SDK persists the exact ticket before exchange. If the response is lost or local session persistence fails, retrying `handleOAuthCallback()` uses that same ticket and receives the server's cached exact result without creating a second session. The server must enable `auth.session.cookie`, and every release app callback must be HTTPS and match `auth.allowedRedirectUrls`. All credential-creating auth requests are serialized across tabs. A persisted auth epoch and pending sign-out tombstone ensure a late sign-in, refresh, or OAuth response cannot restore a session after sign-out. Read more: [Authentication Docs](https://edgebase.fun/docs/authentication) ## Database Queries ```ts type Post = { id: string; title: string; published: boolean; createdAt: string; }; const posts = client.db('app').table