create-syncular-app 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# create-syncular-app
+
+Scaffold a local-first [Syncular](https://syncular.dev) app in one command:
+
+```bash
+bunx create-syncular-app my-app
+# or
+npm create syncular-app@latest my-app
+pnpm create syncular-app my-app
+```
+
+Then:
+
+```bash
+cd my-app
+bun install
+bun dev
+```
+
+You get a minimal, working local-first todo app:
+
+- SQL schema in `migrations/`, mapped to subscriptions/scopes in
+  `syncular.app.ts`
+- a committed, pre-generated TypeScript client (`src/generated/`) — no extra
+  toolchain needed to run; regenerate with `npx syncular generate`
+- a Hono sync server on Bun + SQLite (`src/server/sync-server.ts`)
+- a React UI on `@syncular/client/react` with live queries and offline-queued
+  mutations (`src/app.tsx`)
+
+The scaffolded README explains the project layout and how to evolve the
+schema.
+
+## Links
+
+- Documentation: https://syncular.dev/docs
+- GitHub: https://github.com/syncular/syncular
+- Issues: https://github.com/syncular/syncular/issues
+
+> Status: Alpha. APIs and storage layouts may change between releases.

package/dist/cli.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import {
+  cpSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+var FALLBACK_SYNCULAR_VERSION_RANGE = "^0.1.0";
+function usage() {
+  return `usage: create-syncular-app <target-dir>
+
+Scaffolds a local-first Syncular starter app (tasks table, Hono sync server,
+React client) into <target-dir>.
+
+examples:
+  bunx create-syncular-app my-app
+  npm create syncular-app@latest my-app
+  pnpm create syncular-app my-app
+`;
+}
+function parseCreateCliArgs(argv) {
+  const options = { help: false };
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}
+
+${usage()}`);
+    }
+    if (options.targetDir !== undefined) {
+      throw new Error(`Unexpected extra argument: ${arg}
+
+${usage()}`);
+    }
+    options.targetDir = arg;
+  }
+  return options;
+}
+function packageNameFromDirectory(targetDir) {
+  const name = basename(resolve(targetDir)).toLowerCase().replace(/[^a-z0-9-_.~]+/g, "-").replace(/^[-._]+|[-._]+$/g, "");
+  return name.length > 0 ? name : "syncular-app";
+}
+function syncularDependencyRange(ownVersion) {
+  const version = ownVersion?.trim();
+  if (!version || version === "0.0.0") {
+    return FALLBACK_SYNCULAR_VERSION_RANGE;
+  }
+  return `^${version}`;
+}
+function isSyncularPackage(dependencyName) {
+  return dependencyName === "syncular" || dependencyName.startsWith("@syncular/");
+}
+function rewriteTemplatePackageJson(source, options) {
+  const pkg = JSON.parse(source);
+  pkg.name = options.packageName;
+  for (const section of [pkg.dependencies, pkg.devDependencies]) {
+    if (!section)
+      continue;
+    for (const [name, range] of Object.entries(section)) {
+      if (isSyncularPackage(name) && range.startsWith("workspace:")) {
+        section[name] = options.syncularRange;
+      }
+    }
+  }
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
+function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
+  if (!userAgent)
+    return "bun";
+  if (userAgent.startsWith("bun"))
+    return "bun";
+  if (userAgent.startsWith("pnpm"))
+    return "pnpm";
+  if (userAgent.startsWith("yarn"))
+    return "yarn";
+  if (userAgent.startsWith("npm"))
+    return "npm";
+  return "bun";
+}
+function nextStepsMessage(targetDir, packageManager) {
+  const install = packageManager === "yarn" ? "yarn" : `${packageManager} install`;
+  const dev = packageManager === "bun" ? "bun dev" : `${packageManager} run dev`;
+  return `
+Done. Next steps:
+
+  cd ${targetDir}
+  ${install}
+  ${dev}
+
+The dev script starts the sync server (http://127.0.0.1:4100/health) and the
+Vite client (http://127.0.0.1:5173). The app itself runs on Bun (the sync
+server uses Bun.serve + bun:sqlite); install it from https://bun.sh if needed.
+
+Read the generated README.md for the project layout and how to evolve the
+schema.
+`;
+}
+function readOwnVersion() {
+  try {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+  } catch {
+    return;
+  }
+}
+function templateDirectory() {
+  return fileURLToPath(new URL("../template", import.meta.url));
+}
+function directoryIsEmpty(path) {
+  return readdirSync(path).length === 0;
+}
+async function promptTargetDir() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question("Target directory (e.g. my-app): ");
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+function scaffoldApp(targetDirInput) {
+  const targetDir = resolve(targetDirInput);
+  const templateDir = templateDirectory();
+  if (!existsSync(templateDir)) {
+    throw new Error(`Bundled template not found at ${templateDir}`);
+  }
+  if (existsSync(targetDir) && !directoryIsEmpty(targetDir)) {
+    throw new Error(`Target directory is not empty: ${targetDir}`);
+  }
+  cpSync(templateDir, targetDir, { recursive: true });
+  const gitignorePlaceholder = join(targetDir, "_gitignore");
+  if (existsSync(gitignorePlaceholder)) {
+    renameSync(gitignorePlaceholder, join(targetDir, ".gitignore"));
+  }
+  const packageName = packageNameFromDirectory(targetDir);
+  const syncularRange = syncularDependencyRange(readOwnVersion());
+  const packageJsonPath = join(targetDir, "package.json");
+  writeFileSync(packageJsonPath, rewriteTemplatePackageJson(readFileSync(packageJsonPath, "utf8"), {
+    packageName,
+    syncularRange
+  }));
+  return { targetDir, packageName, syncularRange };
+}
+async function runCreateSyncularAppCli(argv = process.argv.slice(2)) {
+  try {
+    const options = parseCreateCliArgs(argv);
+    if (options.help) {
+      console.log(usage());
+      return 0;
+    }
+    let targetDirInput = options.targetDir;
+    if (!targetDirInput) {
+      targetDirInput = await promptTargetDir();
+    }
+    if (!targetDirInput) {
+      console.error("[create-syncular-app] A target directory is required.");
+      console.error(usage());
+      return 1;
+    }
+    const result = scaffoldApp(targetDirInput);
+    console.log(`[create-syncular-app] Scaffolded ${result.packageName} into ${result.targetDir} (Syncular packages at ${result.syncularRange}).`);
+    console.log(nextStepsMessage(targetDirInput, detectPackageManager()));
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[create-syncular-app] ${message}`);
+    return 1;
+  }
+}
+function isMainModule() {
+  const entrypoint = process.argv[1];
+  return entrypoint !== undefined && import.meta.url === pathToFileURL(entrypoint).href;
+}
+if (isMainModule()) {
+  process.exitCode = await runCreateSyncularAppCli();
+}
+export {
+  syncularDependencyRange,
+  scaffoldApp,
+  runCreateSyncularAppCli,
+  rewriteTemplatePackageJson,
+  parseCreateCliArgs,
+  packageNameFromDirectory,
+  nextStepsMessage,
+  detectPackageManager
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "create-syncular-app",
+  "version": "0.1.0",
+  "description": "Scaffold a local-first Syncular app (`bunx create-syncular-app my-app`)",
+  "license": "Apache-2.0",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/create-syncular-app"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "create",
+    "scaffold"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "create-syncular-app": "./dist/cli.js"
+  },
+  "scripts": {
+    "tsgo": "tsgo --noEmit",
+    "build": "rm -rf dist && bun run build:cli",
+    "build:cli": "bun build ./src/cli.ts --target=node --format=esm --outfile=./dist/cli.js",
+    "smoke": "bun scripts/smoke.ts",
+    "release": "bun run build:cli && syncular-publish"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "devDependencies": {
+    "@syncular/config": "workspace:*"
+  }
+}

package/template/README.md

@@ -0,0 +1,122 @@
+# Syncular starter app
+
+A minimal local-first todo app built with [Syncular](https://syncular.dev):
+the client writes to its own SQLite database (persisted in IndexedDB) and
+syncs with a Hono server over HTTP + WebSocket realtime. It works offline and
+reconciles when the connection returns.
+
+## Run it
+
+```sh
+bun install
+bun dev
+```
+
+This starts:
+
+- the sync server on `http://127.0.0.1:4100` (health check at `/health`,
+  sync routes under `/sync`, data persisted in `data/sync.sqlite`)
+- Vite on `http://127.0.0.1:5173`
+
+Open the app in two browser windows and watch edits replicate. Stop the dev
+server while the page stays open: edits queue locally and sync when the
+server is back.
+
+> **Why Bun?** The dev script and sync server run on Bun (`Bun.serve`,
+> `bun:sqlite` via `@syncular/server/bun-sqlite`) because Bun runs
+> TypeScript directly and ships SQLite with zero native build steps — one
+> runtime for the server, scripts and tooling. The browser client and the
+> Vite build are runtime-agnostic. If you need a Node server instead, swap
+> the dialect for `@syncular/server/better-sqlite3` and serve the Hono app
+> with `@hono/node-server` + `@hono/node-ws`.
+
+## Project structure
+
+```
+migrations/            SQL schema, one folder per migration (up.sql/down.sql)
+syncular.app.ts        App contract: tables -> subscriptions + scopes
+generated/             Codegen handoff (syncular.codegen.json, Rust/Swift/Kotlin)
+src/generated/         Generated TypeScript client + server modules (committed)
+src/server/            Hono sync server (auth, handlers, server-side tables)
+src/client/syncular.ts Client wiring: local DB, sync lifecycle, managed client
+src/app.tsx            React UI built on @syncular/client/react hooks
+scripts/dev.ts         Runs sync server + Vite together
+```
+
+How a change flows: `useMutations().tasks.insert(...)` writes to the local
+SQLite database and queues an outbox entry → the sync engine pushes it to
+`/sync` → the server handler authorizes it against your scopes and assigns a
+`server_version` → other subscribed clients receive it over the WebSocket and
+`useSyncQuery` re-renders.
+
+## Regenerating the client (`bun run codegen`)
+
+`src/generated/` is **committed**, so the app installs and runs without any
+extra toolchain. Regenerate it after changing `migrations/` or
+`syncular.app.ts`:
+
+```sh
+bun run codegen         # npx syncular generate
+bun run codegen:check   # CI: verify committed output is current
+```
+
+`syncular generate` needs two tools:
+
+- **Bun** — runs the TypeScript manifest step (`syncular-typegen`).
+- **Rust (cargo)** — the generator itself is the `syncular-codegen` crate.
+  On first run the CLI installs it automatically with
+  `cargo install syncular-codegen --locked` into a local cache (get Rust from
+  https://rustup.rs). No Rust is needed to run the app itself.
+
+## Next steps
+
+### Add a table
+
+1. Add a migration, e.g. `migrations/0002_projects/up.sql`:
+
+   ```sql
+   CREATE TABLE IF NOT EXISTS projects (
+     id TEXT PRIMARY KEY,
+     name TEXT NOT NULL,
+     user_id TEXT NOT NULL,
+     server_version BIGINT NOT NULL DEFAULT 0
+   ) WITHOUT ROWID;
+   ```
+
+   (plus a `down.sql` with `DROP TABLE IF EXISTS projects;`)
+
+2. Register it in `syncular.app.ts`:
+
+   ```ts
+   projects: syncedTable({
+     table: 'projects',
+     subscriptionId: 'sub-projects',
+     scopes: [scope('user_id', { source: 'actorId', required: true })],
+     serverVersion: 'server_version',
+     sqliteWithoutRowid: true,
+   }),
+   ```
+
+3. Run `bun run codegen`, then mirror the table on the server: add a
+   `createServerHandler` for `projects` in `src/server/sync-server.ts` and a
+   matching `createTable` in `ensureAppTables`. Subscribe the client by
+   adding `projectSubscription({ actorId })` in `src/client/syncular.ts`.
+
+### Change scopes
+
+Scopes decide which rows each user receives. `scope('user_id', { source:
+'actorId' })` means "sync rows whose `user_id` equals the signed-in actor".
+For shared data, scope by a different column (e.g. `team_id`) and return the
+user's teams from `resolveScopes` on the server.
+
+### Real auth
+
+The starter authenticates every request as one demo user with a static
+token. Replace `authenticate` in `src/server/sync-server.ts` with your
+session/JWT validation, and have `src/client/syncular.ts` send your real
+token and the signed-in user's id as `actorId`.
+
+## Learn more
+
+- Docs: https://syncular.dev/docs
+- CLI reference: https://syncular.dev/docs/reference/cli

package/template/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+data
+*.log
+.DS_Store