Client and configuration

The client is a single object per page or process. You start it once with client.init, passing a SeedConfig that says where to keep data, which schema to load and which gateways to use. After that, the Schema, Model and Item classes work against the local database it opened. In React, SeedClientGate calls client.init for you.

import { client, getClient } from '@seedprotocol/sdk'
import type { SeedConfig, SeedConstructorOptions } from '@seedprotocol/sdk'

client

client is the SDK's singleton. getClient() returns the same object, so use whichever reads better.

const client: {
  init(options: SeedConstructorOptions): Promise<void>
  isInitialized(): boolean
  onReady(callback: () => void): () => void
  setAddresses(addresses: AddressConfiguration): Promise<void>
  getAddresses(): Promise<{ owned: string[]; watched: string[] }>
  getOwnedAddresses(): Promise<string[]>
  getWatchedAddresses(): Promise<string[]>
  claimUnpublishedDrafts(publisher: string): Promise<{ seeds: number; versions: number; metadata: number; pendingCreates: number; seedLocalIds: string[] }>
  removeLocalCopiesForAddresses(addresses: string[], options?: { includeUnpublished?: boolean }): Promise<{ removedSeedLocalIds: string[]; removedSeedUids: string[]; keptSeedLocalIds: string[] }>
  syncFromEas(options?: { addresses?: string[] }): Promise<void>
  stop(): Promise<void>
  unload(): Promise<void>
  resetLocalData(options?: ResetLocalDataOptions): Promise<ResetLocalDataResult>
  getService(): Actor   // the client's XState actor
  subscribeService(listener: (service: Actor) => void): () => void
}

This is simplified from the published types.

Every method in the table except init, isInitialized, onReady, getService, subscribeService, stop, unload and resetLocalData throws ClientNotInitializedError before init has finished and after stop() or unload(). Check error instanceof ClientNotInitializedError or error.code === 'CLIENT_NOT_INITIALIZED'; the message is still ClientManager is not initialized. Please call init() first.

Stopping the client

stop() and unload() work in any state: before init, while it runs, after it fails, and once the client is ready. They cancel pending retries, unregister the client's @seedprotocol/query source, and then release, in this order:

1. The outbox stops applying writes in this tab. Pending writes stay in the database, and the leader tab applies them once the next init finishes.
2. Every cached Item, ItemProperty, Schema, Model and ModelProperty is stopped and dropped from the cache, whoever holds it.
3. In the browser, this tab hands tab leadership to another tab and closes its channel.
4. The database closes (BaseDb.close()): in the browser the SQLite worker ends and the change feed stops; on Node the libSQL client closes.

The promise resolves once all of that is done. unload() also ends the client's internal subscription to its own state; otherwise the two are the same. An instance you kept from before the stop is stopped for good: reads return its last values, and writes throw EntityUnloadedError. Look the item up again after the next init, which gets a new instance.

Once the client has stopped, client.getService().getSnapshot() has status: 'stopped' and context.stopReason says why: 'stop' after stop() or unload(), 'reset' after resetLocalData() in this tab or another. It's undefined before init and while the client runs.

init can run again afterwards, with any config. With another filesDir, it opens that directory's database and schema files, not the previous one's. An init called while a stop is still releasing waits for it. Called again on a client that's already stopped, stop() and unload() log a console.warn (client.stop() or client.unload() was called after the client had already stopped; this call does nothing…) and resolve.

import { client } from '@seedprotocol/sdk'
import schema from '../seed.schema.json'

await client.stop()
await client.init({ config: { schema, filesDir: 'other-account' } })

Deleting local data

In the browser, client.resetLocalData() deletes the client's database and files, so the next init starts empty. Use it to wipe a shared device or offer a "reset this app" action.

import { client } from '@seedprotocol/sdk'

const { deleted, failed } = await client.resetLocalData()
if (failed.length > 0) console.warn('Could not delete', failed)

It stops this tab's client from any state, asks every other tab that has the same database open to stop its client, and waits up to otherTabsTimeoutMs (default 10000) for them to close it. It then deletes filesDir from OPFS entry by entry: the database, the schema files and stored files. filesDir defaults to the running or last init's, else '.seed'; pass { filesDir } to delete another one.

It resolves with deleted, the paths it removed, and failed, each entry it couldn't remove as { path, error }, where error is <error name>: <message>. A file another tab still holds open after the timeout ends up in failed; the rest are removed anyway. Unpublished items are gone for good. The saved addresses go with the database, so pass them to the next init; its EAS sync brings their published items back.

The other tabs stop with stopReason: 'reset' and don't reload; your app decides what they show next. An init started during a reset, in this tab or another, waits for it to finish and then opens an empty database. A tab running with multiTab: 'off' takes no part: it doesn't hear the reset, the reset doesn't wait for it, and its init doesn't wait for the reset.

localStorage isn't touched. @seedprotocol/publish keeps its in-app wallet session there; to clear it as well, call clearInAppPublishSession from Components and hooks.

In Node, resetLocalData() throws ResetLocalDataBrowserOnlyError (code: 'RESET_LOCAL_DATA_BROWSER_ONLY'), with the message client.resetLocalData() runs in the browser only; in Node, stop the client and delete filesDir. Do that instead: await client.stop(), then remove the directory.

client also has an addModel(def) method. It's left over from an older API and only inserts a model name into the database. Define models through config.schema or Model.create instead.

client.init

Opens the local database and file store, applies your schema, and saves your config and addresses. It resolves when the client is ready and rejects with the error that stopped it.

init(options: SeedConstructorOptions): Promise<void>

Parameters

SeedConstructorOptions:

Example

import { client } from '@seedprotocol/sdk'
import type { SeedConstructorOptions } from '@seedprotocol/sdk'
import schema from '../seed.schema.json'

const options: SeedConstructorOptions = {
  config: { schema },
}

await client.init(options)

Behavior

• Init runs once per config. Calls made while init is in progress share the same promise, and the first call's addresses are the ones applied. Once the client is ready, a call with the same config (compared deeply) resolves immediately and leaves the stored addresses alone, whatever its addresses hold. To change them, call setAddresses. A call with a different config throws INIT_CONFIG_CONFLICT_MESSAGE (exported), whether the first init has finished or not. To change the config, await client.stop() first. If init fails, you can call it again with any config.
• It waits up to 120 seconds, then rejects.
• Steps, in order: pick the browser or Node platform and resolve the gateway, mount the file system, open and migrate the database, save the config and addresses, load schemas, then register models. The ClientManagerState enum names these steps.
• On Node, a relative filesDir, the default included, needs a writable working directory. It resolves under <cwd>/.seed (see filesDir and endpoints), and init rejects with EACCES: permission denied, mkdir '<cwd>/.seed/…' if it can't create it. An absolute filesDir works from any working directory.
• Schema errors fail init. If schema or schemaFile can't be read or applied, init rejects with Could not load config.schema from "<path>": <reason> (or config.schemaFile; there's no from part for an inline schema object). The original error is the cause. With SeedClientGate, it reaches onInitError. See Your first schema.

isClientReady and whenDbReady

Two functions tell code outside React whether the client can be used. Import them from @seedprotocol/sdk.

function isClientReady(): boolean
function isClientReadySnapshot(snapshot: { status: string; value: unknown }): boolean
function whenDbReady(timeoutMs?: number): Promise<any | undefined>

isClientReady() is true once client.init has finished and the database is open, and false before init, while it runs and after client.stop(). isClientReadySnapshot(snapshot) answers the same for a snapshot of the client's actor (client.getService().getSnapshot()): it's true when the actor is running and in the idle state.

whenDbReady(timeoutMs = 30000) resolves with the Drizzle database (what BaseDb.getAppDb() returns) as soon as init has opened it, before schemas load. It resolves with undefined if that doesn't happen within timeoutMs, such as when init isn't called or fails. After client.stop() it resolves with undefined at once, since the database is closed.

import { whenDbReady } from '@seedprotocol/sdk'

const db = await whenDbReady(10_000)
if (!db) throw new Error('The Seed database did not open within 10 seconds')

SeedConfig

The config object you pass to client.init. Every field is optional, and most apps set only schema.

filesDir and endpoints

In the browser, filesDir is a directory in the browser's private file system (OPFS), and the database lives at <filesDir>/db/seed.db inside it.

On Node, a relative filesDir resolves under a .seed directory in the current working directory, which the SDK creates when it opens the database:

The SDK also writes a copy of your schema ({id}_{name}_v{version}.json) into filesDir. dbConfig.dbUrl moves only the database file. dbConfig.outDir moves the migrations folder, and the database too (to <outDir>/seed.db) when dbUrl isn't set. The schema copies and stored files stay under filesDir.

With no filesDir and no endpoints.files, filesDir is '.seed': the OPFS directory .seed in the browser, <cwd>/.seed on Node. Using Seed in Node and Electron covers running the client on Node.

Storage

Both use Drizzle ORM and the same migrations, which the SDK runs at init. A database last opened by an SDK older than 0.7.7 is recreated instead. Init first copies it to seed.before-recreate-<ms>.db beside seed.db (in OPFS in the browser), then drops its tables before the migrations run, and logs a console warning that names the copy. Unpublished items are then gone from the database but stay in the copy, which the SDK never deletes; published ones come back through EAS sync, and files under filesDir stay. If the copy can't be made, or dbConfig.dbUrl is a remote libsql URL, init logs a warning and opens the database as it is. Migration says how to keep drafts. There are no other storage adapters. In the browser, Seed supports Chrome and Edge 102, Firefox 114 and Safari 26 or later; in an older browser init rejects with UnsupportedBrowserError. The browser database also needs a cross-origin isolated page; without one, init rejects with DatabaseNotPersistentError. Add Seed to your app has the headers to send.

The SDK decides which platform it's on when init runs. It's a browser when window and document exist and the page isn't running in Electron. Otherwise it's Node when process.versions.node exists. Electron renderers that can see Node's process count as Node.

UnsupportedBrowserError

In the browser, init first checks that the page has the file system and locking features Seed needs. If any is missing, it rejects with UnsupportedBrowserError before it loads or stores anything. Its code is 'BROWSER_UNSUPPORTED', and missing lists the absent features as BrowserFeature values:

The message names the missing features and the supported browsers:

This browser lacks features Seed needs (opfs-writable). Seed supports Chrome and Edge 102, Firefox 114 and Safari 26 or later.

Retrying init in the same browser fails the same way; ask the user to update it. With SeedClientGate, the error reaches onInitError.

To check before init and show your own message, call checkBrowserSupport(). It returns { supported, missing }, where missing is a BrowserFeature[] that includes 'cross-origin-isolation' when the page isn't isolated. Outside a browser, as on Node, the file system features are reported missing.

import { checkBrowserSupport, client } from '@seedprotocol/sdk'
import schema from '../seed.schema.json'

const { missing } = checkBrowserSupport()

if (missing.some((feature) => feature !== 'cross-origin-isolation')) {
  document.body.textContent = 'Update your browser to use this app.'
} else {
  await client.init({ config: { schema } })
}

checkBrowserSupport() can't see features that exist only inside workers: OPFS sync access handles, which set the Chrome and Edge 102 floor, and module workers, which set Firefox 114. Chrome 86 to 101 and Firefox 111 to 113 pass the check and fail later in init.

DatabaseNotPersistentError

In the browser, SQLite keeps the database in OPFS only when the page can use SharedArrayBuffer, which needs the Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless) response headers. Init checks for SharedArrayBuffer and Atomics before it starts the database worker, and checks that SQLite opened an OPFS database afterwards. If either check fails, init rejects with DatabaseNotPersistentError instead of running on an in-memory database that a reload would empty. Its code is 'DB_NOT_PERSISTENT'. On a page served without the headers, the message reads:

SQLite can't store the Seed database in the browser's private file system: the page is not cross-origin isolated, so SharedArrayBuffer is unavailable. Serve the app with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless). @seedprotocol/vite sets these on the Vite dev and preview servers; production hosting has to set them too.

Retrying init on the same page fails the same way; the fix is in how the page is served. With SeedClientGate, the error reaches onInitError. @seedprotocol/sdk/node doesn't export this class; import it from @seedprotocol/sdk.

Gateway settings

config.gateway controls how the SDK reaches Arweave. The defaults read from arweave.net, with other public gateways and then Seed's gateway (ar.seedprotocol.io) as fallbacks, and need no other configuration. An app that wants to read from Seed's gateway first sets arweaveDomain: 'ar.seedprotocol.io'. Arweave and gateways gives the fallback order.

With transport: 'hyper', init throws if the sidecar isn't reachable. Set probeSidecar: false to skip the reachability checks for the sidecar, and for the proxy too unless probeProxy is set; probeProxy turns the proxy's check on or off by itself. Arweave and gateways and Gateway Hyper explain the transports.

const config: SeedConfig = {
  schema,
  gateway: { proxyBaseUrl: '/api/seed-gateway' },
}

EAS settings

config.eas sets the chain the SDK reads attestations from when it syncs and looks up schemas. The default is OP Sepolia, the testnet Seed Protocol is deployed on.

The read chain has to match the publish chain. If config.eas.chainId and @seedprotocol/publish disagree, or the local database already holds data from another chain, the SDK throws rather than mixing chains.

Addresses

The SDK keeps two lists of wallet addresses. Owned addresses are wallets the user controls, and decide which items they can edit, publish and delete. Watched addresses are read-only: their published items can't be edited. The SDK syncs published items from EAS for both lists.

await client.setAddresses({ owned: [account], watched: [] })
const { owned, watched } = await client.getAddresses()

You can pass the same value as addresses to the first client.init. Addresses are stored lowercased in the local database. Both setAddresses and init emit addresses.persisted once they've saved them, but only when the addresses differ, ignoring case, order and duplicates, from the ones this tab last announced. client.stop() forgets the last announcement. Only setAddresses starts an EAS sync for the new addresses; for init, the start-up sync covers them.

A draft that has never had a publisher is owned whatever the owned addresses are: it's editable, and the next wallet to connect becomes its publisher (@seedprotocol/publish calls claimUnpublishedDrafts when a wallet connects).

A new draft takes its publisher from the getter registered with setGetPublisherForNewSeeds, if it answers within 3 seconds; @seedprotocol/publish registers one for the connected wallet. Without an answer, the draft gets the owned address when exactly one is set, and no publisher otherwise. With several owned addresses and no @seedprotocol/publish, as in a Node script, register a getter to give new drafts a publisher:

import { setGetPublisherForNewSeeds } from '@seedprotocol/sdk'

setGetPublisherForNewSeeds(async () => account)

Item: Ownership has the ownership checks, and Ownership and drafts explains the rules.

Offline retries

Two kinds of background work are retried when they fail: the EAS schema lookup at start-up, and the EAS syncs the SDK starts itself, such as the start-up sync and the one setAddresses starts. In a browser that reports itself offline, the retry waits for the online event. Otherwise, including on Node, it waits 15 seconds, then 30 seconds, 1, 2 and 5 minutes, and keeps retrying every 5 minutes. A success resets the delay. The timers don't keep a Node process running, and client.stop() cancels them.

A client.syncFromEas() call you make yourself isn't retried: it rejects, and retrying is up to you. Automatic syncs that were merged into its run are retried. Nothing syncs on reconnect after a sync that succeeded either. Syncing across devices shows how to sync on a schedule or on online.

Retries are off when NODE_ENV (or Vite's import.meta.env.MODE) is test. setRetriesWhenOnlineEnabled(enabled) overrides that: false turns them off, true on, and undefined restores the default. It returns the previous setting.

import { setRetriesWhenOnlineEnabled } from '@seedprotocol/sdk'

setRetriesWhenOnlineEnabled(false) // e.g. in tests that stub the network

Multiple tabs

In the browser, every tab of your app opens the same database. With multiTab: 'coordinate' (the default), the tabs elect one leader using the Web Locks API. Only the leader applies the outbox of item edits (other tabs' edits wait for it), prunes the outbox and the change feed's log, and runs automatic EAS syncs, bulk file downloads and the Arweave finalize worker. Other tabs forward requests to it. Some events reach every tab; Events: Across tabs lists them. With multiTab: 'off', every tab runs that work itself. On Node the client always acts as leader. A browser without Web Locks can't run the client: init rejects with UnsupportedBrowserError.

isLeaderTab() and whenLeaderTab() tell you whether this tab leads. client.syncFromEas() isn't limited to the leader; it runs in whichever tab calls it. Multi-tab covers this in depth.

import { isLeaderTab, whenLeaderTab } from '@seedprotocol/sdk'

if (!isLeaderTab()) await whenLeaderTab()

FileSystemLockedError

If another tab or worker is holding the app's OPFS files when init mounts the file system, the SDK retries for about two seconds and then rejects with FileSystemLockedError. Its code is 'OPFS_LOCKED', and its cause is the original browser error.

import { client, FileSystemLockedError } from '@seedprotocol/sdk'

try {
  await client.init(options)
} catch (error) {
  if (error instanceof FileSystemLockedError) {
    // Ask the user to close other tabs of the app, then retry
  }
  throw error
}

With SeedClientGate, the same error reaches the gate's onInitError prop.

Environment variables

The SDK reads a few environment variables from process.env. In a browser build they only take effect if your bundler defines them on process.env; the SDK doesn't read import.meta.env.

NODE_ENV=test turns off offline retries. Init and its errors are the same under it as in production.

Related

• Add Seed to your app: the browser setup this config runs in
• Types: SeedConfig, SeedConstructorOptions and the gateway types
• Using Seed in Node and Electron: running the client on Node and Electron
• Node entry point: what @seedprotocol/sdk/node exports
• React overview: SeedProvider and SeedClientGate
• Multi-tab and Local-first and offline
• Syncing across devices