Syncore Best Practices

Build Syncore applications around the current source of truth in this repository: local runtimes, generated typed APIs, thin app bindings, and platform-specific bootstrap layers.

Documentation Sources

Read these first:

README.md
docs/architecture.md
docs/development.md
docs/guides/syncore-vs-convex.md
examples/AGENTS.md
packages/core/AGENTS.md
packages/cli/AGENTS.md
packages/react/AGENTS.md

Instructions

Project Shape

The intended app layout is:

syncore/
  schema.ts
  functions/
    tasks.ts
  migrations/
  _generated/
syncore.config.ts

Keep concerns separated:

syncore/schema.ts defines tables, indexes, and search indexes
syncore/functions/**/*.ts defines query, mutation, and action
syncore/_generated/* is CLI output
app code imports typed references from syncore/_generated/api
backend files import helpers from syncore/_generated/server

Prefer The Current Happy Path

Inside an app, the main local loop is:

npx syncorejs dev

syncorejs dev can scaffold a missing Syncore project, keep generated files fresh, check schema drift, apply local migrations, and run the local hub.

Use npx syncorejs init --template <template> when you want explicit scaffolding instead of auto-detection.

Generated Files Are Outputs

Treat these as generated artifacts:

syncore/_generated/api.ts
syncore/_generated/functions.ts
syncore/_generated/server.ts

Do not hand-edit them. If they are wrong, fix:

source functions
schema validators
CLI codegen
runtime, React, Svelte, or adapter inference

Prefer Public Entry Points In App Code

User-facing code should normally import from public syncorejs/* entrypoints such as:

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

Reach for @syncore/* package names mainly when editing monorepo internals.

Optimize For DX At The Type Source

Syncore's DX depends on types flowing from source definitions into generated references and hooks.

Prefer this:

const tasks = useQuery(api.tasks.list) ?? [];
const createTask = useMutation(api.tasks.create);

Be suspicious of this:

const tasks = useQuery<{ _id: string; text: string }[]>(api.tasks.list) ?? [];
const createTask = useMutation<string>(api.tasks.create);

If manual generics become necessary in app code, investigate core, codegen, or adapter typing before normalizing the workaround.

Let Examples Stay Small

Examples are integration fixtures, not product apps.

keep them minimal
keep them representative of public APIs
do not hide DX bugs with one-off local annotations when the real fix belongs in shared packages

Use Built-In Local Data Workflows

For local sample data, prefer CLI workflows over ad hoc SQL or edited generated artifacts:

npx syncorejs import --table <table> <file> for explicit JSONL imports
npx syncorejs seed --table <table> for conventional seed files under syncore/seed
npx syncorejs seed --table <table> --file <file> when the fixture lives elsewhere

Validate Cross-Package Changes Together

DX changes often span:

packages/core
packages/schema
packages/cli
packages/react
packages/svelte
platform adapters
examples

When you change a type boundary, verify all affected layers together.

If you intentionally change public exports, refresh the API Extractor baselines with bun run api:update and confirm bun run api:check passes.

Examples

Recommended Function File

import { mutation, query, v } from "../_generated/server";

export const list = query({
  args: {},
  handler: async (ctx) =>
    ctx.db.query("tasks").withIndex("by_done").order("desc").collect()
});

export const create = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) =>
    ctx.db.insert("tasks", { text: args.text, done: false })
});

export const toggleDone = mutation({
  args: { id: v.id("tasks"), done: v.boolean() },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.patch("tasks", args.id, { done: args.done });
    return null;
  }
});

Recommended React Usage

import { useMutation, useQuery } from "syncorejs/react";
import { api } from "../syncore/_generated/api";

function Tasks() {
  const tasks = useQuery(api.tasks.list) ?? [];
  const createTask = useMutation(api.tasks.create);

  return (
    <button onClick={() => void createTask({ text: "Work offline" })}>
      Add task
    </button>
  );
}

Best Practices

Keep user code under syncore/ and generated code under syncore/_generated/
Import server helpers from ../_generated/server inside function files
Import typed references from syncore/_generated/api in app code
Prefer fixing inference in shared packages rather than adding manual generics in examples
Treat npx syncorejs dev as the main local development loop
Use examples as fixtures to confirm intended DX, not as a place to patch over shared regressions

Common Pitfalls

Editing generated files directly instead of fixing codegen or source definitions
Solving type regressions with app-level casts instead of shared fixes
Forgetting that examples are smoke fixtures and must stay deterministic
Importing internal @syncore/* packages in app docs when the public syncorejs/* surface is the intended API
Assuming Convex conventions apply unchanged when Syncore's local runtime differs

References

README.md
docs/development.md
docs/guides/syncore-vs-convex.md
examples/AGENTS.md
packages/core/AGENTS.md
packages/cli/AGENTS.md
packages/react/AGENTS.md

syncore-best-practices