@strata-sync/next 0.1.0

package/AGENTS.md

@@ -0,0 +1,24 @@
+# @strata-sync/next
+
+Next.js integration helpers for App Router and Server Components.
+
+## Commands
+
+- `npm run build` — compile TypeScript (`tsc`)
+- `npm run dev` — watch mode (`tsc --watch`)
+- `npm run test` — run tests (`vitest run`)
+- `npm run lint` — lint with Biome
+- `npm run check-types` — type check without emitting
+
+## Gotchas
+
+- Next.js 14 and 15 are both supported as peer dependencies — test compatibility when changing exports
+- Package has separate entry points: default (client), `./client`, and `./server` — check `exports` in package.json
+- Server exports must not import client-only code (React hooks, browser APIs)
+- Client exports must include `"use client"` directive when using React hooks
+
+## Conventions
+
+- Server utilities go in `src/server/`, client utilities in `src/client/`
+- Use Next.js App Router patterns — no Pages Router support
+- Metadata helpers should use the App Router metadata API, not `next/head`

package/README.md

@@ -0,0 +1,57 @@
+# @strata-sync/next
+
+Next.js integration helpers for the Strata Sync with App Router support.
+
+## Overview
+
+sync-next bridges the sync engine with Next.js App Router patterns:
+
+- **Server utilities** — server-side setup and initialization
+- **Client utilities** — hooks and providers for client components
+- **Metadata helpers** — integration with Next.js metadata API
+
+## Installation
+
+```bash
+npm install @strata-sync/next
+```
+
+Peer dependencies: `next` ^14.0.0 || ^15.0.0, `react` ^18.0.0 || ^19.0.0
+
+## Exports
+
+The package has separate entry points for server and client code:
+
+```typescript
+// Client components
+import { /* client utilities */ } from "@strata-sync/next/client";
+
+// Server components / route handlers
+import { /* server utilities */ } from "@strata-sync/next/server";
+
+// Default export (client-side)
+import { /* default exports */ } from "@strata-sync/next";
+```
+
+## Usage
+
+Use Server Components for initial data loading and Client Components for interactive sync features:
+
+```tsx
+// Server Component — fetch initial data
+import { initSync } from "@strata-sync/next/server";
+
+export default async function Page() {
+  const initialData = await initSync();
+  return <ClientApp initialData={initialData} />;
+}
+
+// Client Component — use sync hooks
+"use client";
+import { useSyncClient } from "@strata-sync/next/client";
+
+function ClientApp({ initialData }) {
+  const client = useSyncClient({ initialData });
+  // ...
+}
+```

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@strata-sync/next",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/client.js",
+  "types": "./dist/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "browser": "./dist/client.js",
+      "node": "./dist/server.js",
+      "default": "./dist/client.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "biome lint .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@strata-sync/core": "*",
+    "@strata-sync/client": "*",
+    "@strata-sync/react": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.9.3",
+    "@biomejs/biome": "^2.3.12",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "next": "^14.0.0 || ^15.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}