Syncore Platform Adapters

Use this skill when wiring Syncore into a concrete runtime environment or debugging adapter-specific DX and transport behavior.

Documentation Sources

Read these first:

docs/quickstarts/node-script.md
docs/quickstarts/electron.md
docs/quickstarts/react-web.md
docs/quickstarts/expo.md
docs/quickstarts/next-pwa.md
docs/guides/syncore-vs-convex.md
packages/platform-node/AGENTS.md
packages/platform-web/AGENTS.md
packages/platform-expo/src/index.ts
packages/platform-expo/src/react.tsx
packages/platform-node/src/index.ts
packages/platform-node/src/ipc-react.tsx
packages/platform-web/src/react.tsx
packages/platform-web/src/worker.ts
packages/next/src/index.tsx
packages/next/src/config.ts
packages/svelte/src/index.ts
examples/browser-esm/main.ts
examples/electron/src/renderer/App.tsx
examples/expo/lib/syncore.ts
examples/next-pwa/app/page.tsx
examples/sveltekit/package.json

Instructions

Core Rule

The Syncore runtime stays local. Adapters only provide environment-specific IO:

SQLite access
filesystem or storage APIs
transport to UI layers
timers and lifecycle hooks

Keep user functions portable and adapter setup specific.

Prefer Public Entry Points In App Docs

For app-facing setup, prefer the public syncorejs/* surface:

syncorejs/node
syncorejs/node/ipc
syncorejs/node/ipc/react
syncorejs/browser
syncorejs/browser/react
syncorejs/expo
syncorejs/expo/react
syncorejs/next
syncorejs/next/config
syncorejs/svelte

Use @syncore/* packages mainly when editing the monorepo internals themselves.

Monorepo Caveat

Some workspace fixtures import built paths directly, such as the Next example config, to keep workspace builds deterministic. Document public app usage with syncorejs/* unless the task is specifically about monorepo internals.

Node Script

For local scripts without a UI shell, use withNodeSyncoreClient:

import path from "node:path";
import { withNodeSyncoreClient } from "syncorejs/node";
import { api } from "./syncore/_generated/api.ts";
import schema from "./syncore/schema.ts";
import { functions } from "./syncore/_generated/functions.ts";

await withNodeSyncoreClient(
  {
    databasePath: path.join(process.cwd(), ".syncore", "syncore.db"),
    storageDirectory: path.join(process.cwd(), ".syncore", "storage"),
    schema,
    functions
  },
  async (client) => {
    console.log(await client.query(api.tasks.list));
  }
);

Electron

Run Syncore in the main process and expose a narrow bridge to the renderer.

import path from "node:path";
import { app } from "electron";
import { createNodeSyncoreRuntime } from "syncorejs/node";
import schema from "../syncore/schema.js";
import { functions } from "../syncore/_generated/functions.js";

const runtime = createNodeSyncoreRuntime({
  databasePath: path.join(app.getPath("userData"), "syncore.db"),
  storageDirectory: path.join(app.getPath("userData"), "storage"),
  schema,
  functions,
  platform: "electron-main"
});

In the renderer, use SyncoreElectronProvider from syncorejs/node/ipc/react. Keep the preload bridge narrow with installSyncoreWindowBridge().

Do not put SQLite in the renderer process.

Web Worker

For the web target, host Syncore inside a dedicated worker and talk to it through the managed client.

/// <reference lib="webworker" />

import { createBrowserWorkerRuntime } from "syncorejs/browser";
import schema from "../syncore/schema";
import { functions } from "../syncore/_generated/functions";

void createBrowserWorkerRuntime({
  endpoint: self,
  schema,
  functions,
  databaseName: "my-syncore-app",
  persistenceMode: "opfs"
});

import { SyncoreBrowserProvider } from "syncorejs/browser/react";

<SyncoreBrowserProvider
  workerUrl={new URL("./syncore.worker.ts", import.meta.url)}
>
  {children}
</SyncoreBrowserProvider>;

Expo

Use the bootstrap helper and mount SyncoreExpoProvider with a fallback while the local runtime starts.

import { createExpoSyncoreBootstrap } from "syncorejs/expo";
import schema from "../syncore/schema";
import { functions } from "../syncore/_generated/functions";

export const syncore = createExpoSyncoreBootstrap({
  schema,
  functions,
  databaseName: "syncore.db",
  storageDirectoryName: "syncore-storage"
});

Next PWA

Use the Next helpers to integrate the worker and serve the SQL.js wasm asset.

Configure next.config.ts with withSyncoreNext:

import { withSyncoreNext } from "syncorejs/next/config";

export default withSyncoreNext({
  output: "export"
});

Then wire the provider:

"use client";

import { SyncoreNextProvider } from "syncorejs/next";

const createWorker = () =>
  new Worker(new URL("./syncore.worker", import.meta.url), {
    type: "module"
  });

export function AppSyncoreProvider({
  children
}: {
  children: React.ReactNode;
}) {
  return (
    <SyncoreNextProvider createWorker={createWorker}>
      {children}
    </SyncoreNextProvider>
  );
}

Remember the current Next flow also expects sql-wasm.wasm in public/, plus service worker wiring when you want installable offline behavior.

Browser ESM And Svelte

The repo also demonstrates lower-level browser ESM usage through createBrowserWorkerClient(...) and Svelte bindings via syncorejs/svelte.

Reach for those patterns when React is not the UI layer.

Examples

Pick The Right Adapter

Node script -> syncorejs/node with withNodeSyncoreClient
Electron desktop app -> syncorejs/node plus IPC bridge and syncorejs/node/ipc/react
Browser app with worker isolation -> syncorejs/browser plus syncorejs/browser/react
Expo app with local SQLite -> syncorejs/expo plus syncorejs/expo/react
Next installable offline app -> syncorejs/next plus syncorejs/next/config
Svelte or SvelteKit app -> syncorejs/browser plus syncorejs/svelte
Browser ESM sample -> syncorejs/browser plus explicit function references

Best Practices

Keep the runtime in the environment best suited for local storage and lifecycle control
Preserve typed references across transports and clients
Use the official quickstarts and examples for target-specific wiring
Keep adapter code thin and user functions portable
Prefer wrapper providers in UI shells instead of hand-rolling provider setup each time
Validate both runtime behavior and declaration output when touching adapter types

Common Pitfalls

Running Electron storage or SQLite directly in the renderer
Breaking worker or IPC type boundaries by overconstraining transport types
Forgetting environment-specific assets such as sql-wasm.wasm, Next config wiring, or service worker setup
Solving adapter typing issues with app-level casts instead of shared fixes
Documenting internal @syncore/* imports where public syncorejs/* entrypoints are the intended app API

References

docs/quickstarts/node-script.md
docs/quickstarts/electron.md
docs/quickstarts/react-web.md
docs/quickstarts/expo.md
docs/quickstarts/next-pwa.md
packages/platform-node/AGENTS.md
packages/platform-web/AGENTS.md
packages/next/src/config.ts
packages/svelte/src/index.ts

syncore-platform-adapters