The Seed toolkit
Every Seed Protocol package by layer: what it does, when to reach for it, and how it fits your stack.
Seed Protocol ships as a set of npm packages under @seedprotocol/. You don't need all of them. Most apps start with three (the SDK, the React bindings, and the Vite plugin or the Next.js config helper) and add others for publishing, feeds or reading published data.
Keep every @seedprotocol/* package on the same version, installed once: the packages pin each other exactly, @seedprotocol/react and @seedprotocol/publish declare the exact SDK version as a peer (npm refuses a mismatch with ERESOLVE), and @seedprotocol/query throws DuplicateEasModuleError when it finds a second copy of eas or arweave in use. See the changelog and upgrading guide.
Jump to a package
@seedprotocol/sdk
Schemas, models, items and the local database
@seedprotocol/react
SeedProvider, SeedClientGate and React hooks
@seedprotocol/vite
The Vite plugin for browser builds
@seedprotocol/next
The Next.js config helper for browser builds
@seedprotocol/publish
Wallets, Arweave uploads and EAS attestations
@seedprotocol/feed
RSS, Atom and JSON Feed from published Seeds, plus Hyper distribution
@seedprotocol/mapping
Map Markdown or RSS fields onto model properties
@seedprotocol/query
Read published Seeds as JSON without the full client
@seedprotocol/eas
Low-level EAS attestation reads and the chain table
@seedprotocol/arweave
Low-level Arweave gateway client and failover
How the packages fit together
The packages fall into four layers. The core layer runs in your app and works on its own, offline. Publishing writes to public networks, and the reading layer reads back what anyone has published. Feeds and import sit at the edges, turning published data into feeds or bringing outside content in.
Solid arrows are package dependencies (A depends on B). Dotted arrows are network calls. For readability, the diagram leaves out the direct eas and arweave dependencies that sdk and feed also have, publish's on eas, feed-hyper's on arweave, and the SDK's dependency on @seedprotocol/archive, which packages items as archive bags; the tables below list every dependency.
The SDK never depends on publish, feed or mapping, so a local-only app doesn't pull in wallet or feed code. eas and arweave have no Seed dependencies; everything that reads or writes public data builds on them. mapping and gateway-hyper stand alone: neither depends on another Seed package, and no Seed package imports them. vite and next configure your app's build and have no Seed dependencies. The SDK lists vite as an optional peer for its @seedprotocol/sdk/vite entry, which works only if your app installs @seedprotocol/vite.
Core
The local-first part of Seed: define a schema, create and edit items, and query them reactively. Data lives on the user's device until they publish it.
| Package | What it does | Reach for it when… | Runs in | Depends on |
|---|---|---|---|---|
@seedprotocol/sdk | The client, the local SQLite database and files, and the Schema, Model and Item classes. Prepares items for publishing and syncs published data back from EAS | You're building anything with Seed. Every app needs it | Both: browser (OPFS) and Node 20.19+ or 22.12 to 24 (@seedprotocol/sdk/node) | eas, arweave, query, archive; optional peer vite |
@seedprotocol/react | SeedProvider, SeedClientGate and hooks such as useItems, useItem and useLiveQuery | Your UI is React | Browser | sdk (peer, same version); peers react, react-dom, @tanstack/react-query |
@seedprotocol/vite | Vite plugin: cross-origin isolation headers on the dev and preview servers, ES module workers, one copy of each Seed package, and opt-in Node polyfills and ZenFS fs aliases | Your app is built with Vite (including Electron renderers) | Node, at build time | None; peer vite >= 8; optional peers @zenfs/core, @zenfs/dom |
@seedprotocol/next | Next.js config helper: withSeed points the SDK at its browser builds, adds cross-origin isolation headers, and can alias fs to ZenFS in browser builds | Your app is built with Next.js 15.5 or later | Node, at build time | None; peer next >= 15.5 |
Publishing
Writing to public networks: uploading files to Arweave and recording Seeds, Versions and properties as EAS attestations from the user's account.
| Package | What it does | Reach for it when… | Runs in | Depends on |
|---|---|---|---|---|
@seedprotocol/publish | The publish flow: wallet adapters (EOA, EIP-1193, viem, Privy, EIP-7702, Thirdweb), Arweave uploads, EAS attestations, cost estimates, revocation, and React provider, hooks and buttons. Also writes the DomainOwnership, PublishAuthorization and PublishedBy attestations | Users publish content from your app, or a server publishes on their behalf | Both: browser (React UI) and Node (servers and automation) | eas; peers sdk and @seedprotocol/react (same version), react, react-dom, @tanstack/react-query; optional peer thirdweb (for Thirdweb wallets and @seedprotocol/publish/thirdweb) |
The SDK on its own doesn't publish. item.publish() hands the item to @seedprotocol/publish, which must be initialized with initPublish().
Feeds & import
Moving content between Seed and the rest of the web: serving published Seeds as feeds, and mapping outside content into Seed models.
| Package | What it does | Reach for it when… | Runs in | Depends on |
|---|---|---|---|---|
@seedprotocol/feed | Generates RSS 2.0, Atom and JSON Feed from the published Seeds of a schema, with paging, month archives and ready-made HTTP handlers. Also parses incoming RSS | You want an RSS, Atom or JSON feed of published content, for example a /posts/rss route | Node 20.18.1+ or Bun (server) | query, eas, arweave |
@seedprotocol/feed-hyper | Publishes generated feeds to a Hyperdrive, replicates other feeds peer to peer, and serves them over localhost HTTP. Ships the seed-feed command | You want to distribute or mirror a feed without a server hostname | Node 20.18.1+ only | feed, arweave |
@seedprotocol/mapping | Maps fields from Markdown (with frontmatter) or RSS/Atom items onto model properties. Headless API plus a FieldMapper React component (@seedprotocol/mapping/react) | You're importing content into Seed models and want saved, editable field maps | Both (the React UI needs react and react-dom) | None; optional peers react, react-dom |
Reading published data
Reading what's already been published, by anyone, without running the full authoring client.
| Package | What it does | Reach for it when… | Runs in | Depends on |
|---|---|---|---|---|
@seedprotocol/query | Reads published Seeds as canonical JSON with getSeed and queryBySchema: latest Version, newest property values, expanded relations and Arweave-hosted rich text. Includes a cache and a changelog | You're showing published content in a static site, an SSR page, an API or another app | Both (Node 20.18.1+; adds a disk cache in Node) | eas, arweave |
@seedprotocol/eas | Low-level reads from the EAS GraphQL indexer: Seed, Version and property attestations, schema lookups, change detection, tool attestation checks, and the EAS chain table | You need raw attestations, want to verify a PublishedBy or PublishAuthorization claim, or point reads at your own indexer | Both (Node 20.18.1+) | None |
@seedprotocol/arweave | Low-level Arweave gateway client: the default gateway list, read failover with health checks, upload status, and gateway transport selection (HTTP, proxy or Hyper) | You need to change gateways, check whether an upload is anchored, or read Arweave data directly | Both (@seedprotocol/arweave/node for Node) | None |
@seedprotocol/sdk re-exports most of arweave, but from eas only the chain table and a few name, UID and attestation helpers. An SDK app imports eas directly for raw attestation reads, tool attestation checks and change detection.
Protocol
These aren't app-level packages, but they're what the packages above talk to. They're documented in the Protocol tab.
- Seed contracts. Seeds, Versions and properties are EAS attestations made by the user's smart account through Seed's contracts.
@seedprotocol/publishwrites through them, andeas,queryand the SDK's sync read the resulting attestations from an EAS indexer. - Gateway Hyper (
@seedprotocol/gateway-hyper,seed-gatewaycommand). Tunnels an upload API and Arweave gateway over HyperDHT, for operators who don't want a public hostname. It runs in Node 20+ only. Apps reach it over HTTP, through a localhost sidecar or an app-server proxy, by setting the gateway transport in the SDK or publish config; no package imports it.
Common stacks
A local-first React app. sdk + react + vite (or next in a Next.js app). Users create and edit content on their device, with live queries and offline support. Nothing leaves the device. Add Seed to your app sets this up.
Add publishing. + publish. Users connect a wallet and publish items to Arweave and EAS. publish brings eas with it, and the SDK already brings arweave.
Show published content on a website or API. query on its own. Read Seeds by UID or by schema from a server, a static site build or another app, without the local database. Add eas if you need raw attestations.
Serve a feed of published content. feed (which brings query), on a Node or Bun server. Add feed-hyper to distribute the same feed over Hyperdrive.
Import content from RSS or Markdown. mapping to turn source fields into a property bag, plus sdk (and react for the FieldMapper UI) to save the results as items. feed's RSS parser is an option for reading the source feed on a server.
A Node service or script. sdk from @seedprotocol/sdk/node, and publish if it publishes. Skip react and vite.
Maturity
Seed Protocol is early. Things to know before you build on it:
- Testnet only. The Seed contracts are deployed on OP Sepolia (chain 11155420), an Optimism testnet, and that's the default chain for the SDK,
publishandeas. There's no mainnet deployment yet. See Deployments. - No official Hyper feed or gateway key.
DEFAULT_SEED_FEED_HYPER_KEYandDEFAULT_SEED_GATEWAY_HYPER_KEYare empty strings, sofeed-hyperandgateway-hyperwork only with keys you generate or get from an operator. See Hyper distribution and Gateway Hyper. - Some
mappingoptions are deprecated.FieldMapper'swireslayout andunstyledtheme still work; use the defaultrowslayout and thenonetheme instead. See Deprecated props.
Related
- What is Seed Protocol?
- How it works: what the local database, signing and publishing do
- Add Seed to your app