Overview and install
What @seedprotocol/sdk contains, how to install it, which entry point to import from, and where each part of its API is documented.
@seedprotocol/sdk is the core of Seed Protocol. It runs the client, keeps a local SQLite database and file store, and gives you the Schema, Model, Item and property classes you read and write content with. Everything works offline. Publishing to Arweave and EAS is added by @seedprotocol/publish, and the React hooks live in @seedprotocol/react.
import { client, Item, Model, Schema } from '@seedprotocol/sdk'To upgrade from an earlier release, see Migration.
Install
For a browser app, install the SDK and the Vite plugin, which sends the cross-origin isolation headers the browser database needs and sets up Vite's workers and dependency pre-bundling for the SDK:
npm install @seedprotocol/sdk
npm install --save-dev @seedprotocol/viteXState, Drizzle and ZenFS are dependencies of the SDK and install with it. TanStack Query doesn't: React apps get @tanstack/react-query as a peer of @seedprotocol/react. To query the SDK's tables, import Drizzle's operators (eq, and, like, sql and the rest) from @seedprotocol/sdk/drizzle, which re-exports the SDK's own copy of drizzle-orm, so your app doesn't install Drizzle or match its version.
The SDK needs Node.js 20.19 or a later 20.x release, or 22.12 through 24 (its engines field is ^20.19.0 || >=22.12.0 <=24). Node 21 and the early 20.x and 22.x releases are outside that range. In the browser it supports Chrome and Edge 102, Firefox 114 and Safari 26 or later; in an older browser client.init rejects with UnsupportedBrowserError. React apps also install @seedprotocol/react, which requires the exact same SDK version. Add Seed to your app has the commands for pnpm and bun and the full Vite + React setup, including the headers to send in production.
A Node script only needs npm install @seedprotocol/sdk. See Using Seed in Node and Electron.
Entry points
The package has six entry points. Most apps import from the main one, and from ./drizzle when they query the database.
| Import path | Use it for | Runs in |
|---|---|---|
@seedprotocol/sdk | Everything an app uses: client, Schema, Model, ModelProperty, Item, ItemProperty, BaseDb, events, errors and types | Browser and Node (import or require). The client picks the browser or Node storage at client.init |
@seedprotocol/sdk/drizzle | Drizzle's query operators and sql, re-exported from the copy of drizzle-orm the SDK queries with. See Querying | Browser and Node |
@seedprotocol/sdk/node | Node-only helpers: Property builders, NodeFileManager and NodeDb. See Node entry point | Node only. Importing it configures the Node platform as a side effect |
@seedprotocol/sdk/node-eas-lodash | A Node module loader hook, used as node --import @seedprotocol/sdk/node-eas-lodash. The SDK doesn't need it; a Node process that also loads @seedprotocol/publish does. It exports nothing | Node only |
@seedprotocol/sdk/platform | createPlatformServices(), which builds the browser or Node storage services. client.init already does this, so apps don't need it | Browser or Node, picked by the browser / node export conditions |
@seedprotocol/sdk/vite | A re-export of seedVitePlugin from @seedprotocol/vite, kept for older projects. @seedprotocol/vite is an optional peer of the SDK, so this works only when your app installs it; otherwise the import fails with ERR_MODULE_NOT_FOUND. Import from @seedprotocol/vite instead | Vite config (build time) |
ESM is the package's own format, and import is the usual way in. require('@seedprotocol/sdk') and require('@seedprotocol/sdk/node') also work, on the Node versions in engines: Node loads the same ES module build through require(), so code that mixes require and import shares one client. See Using Seed in Node and Electron.
The type declarations resolve under "moduleResolution": "bundler", "nodenext" and "node16". Keep skipLibCheck on: without it, TypeScript reports errors inside drizzle-orm, which the SDK depends on.
What's in the main entry
The main entry exports a lot, because @seedprotocol/react and @seedprotocol/publish build on its lower-level pieces. These are the parts app code uses, and where each is documented:
| Area | Main exports | Reference |
|---|---|---|
| Client and setup | client, getClient, isClientReady, whenDbReady, INIT_CONFIG_CONFLICT_MESSAGE, ClientNotInitializedError, ResetLocalDataBrowserOnlyError, checkBrowserSupport, UnsupportedBrowserError, DatabaseNotPersistentError, FileSystemLockedError, isLeaderTab, whenLeaderTab, setRetriesWhenOnlineEnabled | Client and configuration |
| Schemas | Schema, ConflictError, ModelPropertyDataTypes, importJsonSchema, syncSchemaFromSource | Schema |
| Models | Model, AmbiguousModelError | Model |
| Model properties | ModelProperty | ModelProperty |
| Items | Item, ItemCreateError, ItemCreateValidationError, UnknownModelError, EntityUnloadedError, entityLoadError, PUBLISH_NOT_CONFIGURED_MESSAGE, exportArchive, ArchiveExportError | Item, Export a published item |
| Ownership | isItemOwned, assertItemOwned, OwnershipError | Item: ownership |
| Item properties | ItemProperty, ItemPropertySaveValidationError, ClearNotSupportedError | ItemProperty |
| Querying | BaseDb (getAppDb, liveQuery, transaction), the Drizzle tables, getPublishedSeedRecord, getPublishGraph, getPublishModels, summarizePublishUploads, and the change-feed functions watchEntityChanges, watchEntityRows and isChangeFeedRunning (the feed runs in the browser only) | Querying |
| Events | eventEmitter and the event name constants | Events |
| Arweave links | rehostArweaveLinksInHtml, nextArweaveGatewayUrl, mapUrlAttribute, parseArweaveTransactionLink, and the types ArweaveTransactionLink and HtmlArweaveRefs, re-exported from @seedprotocol/arweave | Arweave: Links in Html |
| Types | SeedConfig, SeedConstructorOptions, SchemaFileInput, SchemaFileFormat, SchemaNameMatch, IItem, ItemData and others | Types |
The rest of the main entry is lower level: the raw XState machines, database read and write helpers, publish payload builders, ownership SQL helpers, and re-exports from @seedprotocol/eas and @seedprotocol/arweave. A comment in the SDK's source marks many of these as exports for @seedprotocol/react. You can import them, but they aren't covered in this reference and may change between releases.
Packages built on the SDK
- @seedprotocol/react wraps the client in
SeedProviderandSeedClientGateand adds hooks such asuseItemsanduseCreateItem. The SDK has no hooks of its own. - @seedprotocol/publish connects a wallet, uploads files to Arweave and writes EAS attestations. It registers the executors behind
item.publish()anditem.unpublish(). Without it, both throw:item.publish()withPUBLISH_NOT_CONFIGURED_MESSAGE("Publishing is not configured…").
The Seed toolkit shows how all the packages fit together.
Related
- Add Seed to your app: full setup for a Vite + React app
- Create and read items: write and read your first item
- Your first schema: the schema file format
- How Seed Protocol works: what the local database, signing and publishing do
- Using Seed in Node and Electron
The Seed toolkit
Every Seed Protocol package by layer: what it does, when to reach for it, and how it fits your stack.
Client and configuration
The client singleton, client.init, the readiness helpers and every SeedConfig option, plus storage, gateway and EAS settings, environment variables and the multi-tab lock.