Add Seed to your app

These steps add the SDK to a Vite + React app you already have. When they're done, the Seed client starts when your app loads and your components can use the Seed hooks. To start from an empty project instead, follow the tutorial.

The SDK keeps a SQLite database and your files in the browser's private file system (OPFS). That needs a cross-origin isolated page and a few build settings. The @seedprotocol/vite plugin sets them up for the Vite dev and preview servers; in production, your host sends the headers.

Requirements

• Node.js 20.19 or a later 20.x release, or 22.12 through 24. The SDK's engines field is ^20.19.0 || >=22.12.0 <=24.
• Vite 8 or later. @seedprotocol/vite declares vite >= 8.0.0 as a peer dependency, and @vitejs/plugin-react 6 is the matching React plugin. For a Next.js app, see @seedprotocol/next instead.
• react and react-dom 18 or 19.
• npm, pnpm or bun. These docs don't cover Yarn.
• For your users: Chrome or Edge 102, Firefox 114, or Safari 26 or later. In an older browser, client.init rejects with UnsupportedBrowserError.

npm install @seedprotocol/sdk @seedprotocol/react
npm install --save-dev @seedprotocol/vite

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { seedVitePlugin } from '@seedprotocol/vite'

export default defineConfig({
  plugins: [react(), ...seedVitePlugin()], 
})

{
  "$schema": "https://seedprotocol.io/schemas/data-model/v1",
  "version": 1,
  "metadata": {
    "name": "blog",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "models": {
    "Post": {
      "properties": {
        "title": { "type": "Text" }
      }
    }
  },
  "enums": {},
  "migrations": []
}

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

export const config: SeedConfig = {
  schema,
}

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { SeedProvider, SeedClientGate } from '@seedprotocol/react'
import { config } from './seed'
import App from './App'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <SeedProvider>
      <SeedClientGate initConfig={{ config }}>
        <App />
      </SeedClientGate>
    </SeedProvider>
  </StrictMode>,
)

npm run dev

If you already use React Query

Pass your own client to SeedProvider so Seed and the rest of your app share one cache. Build it with Seed's defaults:

import { SeedProvider, createSeedQueryClient } from '@seedprotocol/react'
import App from './App'

const queryClient = createSeedQueryClient()

export function Root() {
  return (
    <SeedProvider queryClient={queryClient}>
      <App />
    </SeedProvider>
  )
}

SeedProvider renders a QueryClientProvider with that client for everything inside it, so where it wraps your whole app it can replace your own QueryClientProvider. To start from your own defaults instead, pass them through mergeSeedQueryDefaults(), where your options win over Seed's:

import { QueryClient } from '@tanstack/react-query'
import { mergeSeedQueryDefaults } from '@seedprotocol/react'

const queryClient = new QueryClient({
  defaultOptions: mergeSeedQueryDefaults({ queries: { gcTime: 1000 * 60 * 60 } }),
})

Don't swap SeedProvider for a bare QueryClientProvider. The list hooks would run, but nothing would refresh them after saves, syncs or address changes.

What cross-origin isolation changes in an existing app

The SQLite database runs in a worker on top of OPFS, which needs the page to be cross-origin isolated. On a page without the headers, client.init rejects with DatabaseNotPersistentError and SeedClientGate stays on its loading screen. The plugin sets the headers on vite and vite preview only. In production your host has to send Cross-Origin-Opener-Policy, Cross-Origin-Embedder-Policy and Cross-Origin-Resource-Policy on the HTML page; Headers in production has the values and host examples.

The headers apply to every page that loads Seed, so check the features your app already has before you ship:

• Popups to other sites. With Cross-Origin-Opener-Policy: same-origin, a window your page opens on another origin can't reach back through window.opener. Sign-in or payment flows that return their result that way stop working.
• Embedded pages. With Cross-Origin-Embedder-Policy: credentialless, a cross-origin <iframe> loads only if the embedded page sends a Cross-Origin-Embedder-Policy header of its own.
• Cross-origin images, scripts and fetches. Requests made without CORS are sent without cookies, so a resource on another origin that needs the user's cookies won't load as before.

If a feature breaks and you can't change it, keep it on pages that don't load Seed, and send the headers only on the pages that do.

Without React

SeedClientGate calls client.init for you. In code outside React, call it yourself and wait for it before using Item, Model or the other SDK APIs:

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

await client.init({ config })

Calls made while init is in progress share the same promise, and once the client is ready a call with the same config resolves straight away. A call with a different config throws; await client.stop() first, and init then starts the client again with the new config. See Client and configuration.

TypeScript

The packages ship their own type definitions, so you don't need any @types packages. If your tsconfig.json rejects import schema from '../seed.schema.json', turn on "resolveJsonModule": true. With verbatimModuleSyntax, import types with import type, as src/seed.ts does.

Troubleshooting

• npm error ERESOLVE with Could not resolve dependency: peer @seedprotocol/sdk@"<version>" from @seedprotocol/react. Your @seedprotocol/* packages are on different versions. Install them all at the same version.
• The client never gets past "Loading...". Open the browser console. SeedClientGate logs [SeedClientGate] client init failed with the cause when you haven't passed onInitError. If the cause is DatabaseNotPersistentError, the page isn't cross-origin isolated: check that your own server.headers don't replace the plugin's with other values, that you haven't set isolationHeaders: false, and in production, your host's headers.
• UnsupportedBrowserError / "This browser lacks features Seed needs". The browser is older than the ones in Requirements, and retrying won't help. Show the user a message asking them to update it: check for code === 'BROWSER_UNSUPPORTED' in onInitError, or call checkBrowserSupport() before init. UnsupportedBrowserError has a sample.
• FileSystemLockedError / "The browser file system is in use by another tab or worker". Another tab or worker has the app's storage open. Close the other tabs and retry, or handle it in onInitError.
• File reads fail or come back empty, or OPFS gets remounted unexpectedly. You probably have two copies of ZenFS. The @seedprotocol/vite troubleshooting list has the check and the fix.
• Buffer is not defined, process is not defined, or a module "has been externalized for browser compatibility". A dependency of your app expects Node. See the @seedprotocol/vite troubleshooting list.