@usegraft/sdk-react-router 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @usegraft/sdk-react-router
+
+> React Router v7 adapter: typed content reads and loader/action mounts over the same handlers every other surface serves.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator. For framework mode, which is where React Router runs loaders and actions on a server.
+
+## Install
+
+```bash
+npm i @usegraft/sdk-react-router
+```
+
+## Read content
+
+Build the handle once in a `.server.ts` module, then import it from loaders and actions.
+
+```ts
+// app/lib/graft.server.ts
+import { createDb } from "@usegraft/db";
+import { createGraft } from "@usegraft/sdk-react-router";
+import { collections } from "../../graft.config";
+
+export const graft = createGraft({ db: createDb(process.env.DATABASE_URL!).db, collections });
+```
+
+```ts
+// app/routes/docs.$slug.tsx
+import { graft } from "../lib/graft.server";
+import type { Route } from "./+types/docs.$slug";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  return { doc: await graft.getContent("docs", params.slug) };
+}
+```
+
+Return types come from your `defineCollection` schemas, so a renamed field is a build error rather than a runtime `undefined`.
+
+`loader` and `action` run on the server and React Router strips them from the browser bundle. The `.server.ts` name is belt and braces on top of that: it turns a stray client import into a build error rather than a database URL in a bundle.
+
+There is no request-level memo here, because `React.cache` covers React Server Components and framework mode is not one. Reads go straight to the index, which is the right default: a loader runs once per request and makes a handful of reads.
+
+To read content in the browser instead — a search box, an editor preview — use [`@usegraft/sdk-react`](https://www.npmjs.com/package/@usegraft/sdk-react), which reads the same content over HTTP and needs no database handle.
+
+## Read with no database
+
+Pass `index` instead of `db` and the same surface reads the SQLite artifact `graft compile` writes.
+
+```ts
+import { openStaticIndex } from "@usegraft/db";
+
+export const graft = createGraft({
+  index: await openStaticIndex(".graft/index.db"),
+  collections,
+});
+```
+
+## Mount the runtime
+
+`graftRoute` binds a Graft handler to a resource route — a route module with no default export, whose loader and action return raw Responses — so typed functions and MCP are served from your own app rather than a separate process.
+
+```ts
+// app/routes/api.fn.$name.ts
+import { createFunctionsHandler } from "@usegraft/core";
+import { graftRoute } from "@usegraft/sdk-react-router";
+
+const handler = createFunctionsHandler({ db, collections, functions });
+
+export const action = graftRoute(handler); // POST
+export const loader = graftRoute(handler); // GET, which 405s with Allow and a fix
+```
+
+```ts
+// app/routes/api.mcp.ts
+import { createGraftMcpHandler } from "@usegraft/mcp";
+import { graftRoute } from "@usegraft/sdk-react-router";
+
+export const action = graftRoute(createGraftMcpHandler({ db, collections, functions, actor }));
+```
+
+Register them the way you register any route:
+
+```ts
+// app/routes.ts
+import { route, type RouteConfig } from "@react-router/dev/routes";
+
+export default [
+  route("api/fn/:name", "routes/api.fn.$name.ts"),
+  route("api/mcp", "routes/api.mcp.ts"),
+] satisfies RouteConfig;
+```
+
+React Router splits a route by method into two exports rather than naming the method, so one handler is mounted twice. Exporting `loader` is not ceremony: it is what makes a GET to a function endpoint answer with Graft's 405 and its `Allow` header, instead of React Router's own "no loader" error, which teaches the caller nothing.
+
+The parameter is typed structurally as `{ request: Request }`, so this package needs no `react-router` dependency and every `LoaderFunctionArgs`, `ActionFunctionArgs` and generated `Route.LoaderArgs` satisfies it.
+
+## MDX
+
+Bodies come back as authored source. Render them with your own pipeline. The `MdxBody` in [`@usegraft/sdk-next`](https://www.npmjs.com/package/@usegraft/sdk-next) evaluates MDX in a Server Component, which framework mode does not have, so it is not re-exported here.
+
+## Cache invalidation
+
+React Router has no tag-based data cache, so the [`@usegraft/sdk-core`](https://www.npmjs.com/package/@usegraft/sdk-core) tag contract maps onto HTTP. Stamp `tagsFor(...)` into a CDN surrogate-key header from the route's `headers` export, and purge `tagsForChanges(branch, changeSet)` from your compile webhook.
+
+```ts
+export function headers() {
+  return { "Cache-Tag": tagsFor("main", "docs", slug).join(",") };
+}
+```
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/sdk-react-router/CHANGELOG.md)

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { AnyCollection, ReadOptions, Document, ListOptions, SearchOptions, SearchHit, GraftClient, ClientOptions } from '@usegraft/sdk-core';
+export { AnyCollection, ChangeSet, ClientOptions, Document, GraftClient, ListOptions, ReadOptions, SearchHit, SearchOptions, TAG_NAMESPACE, collectionTag, createClient, documentTag, tagsFor, tagsForChanges, toDocument } from '@usegraft/sdk-core';
+
+/**
+ * React Router v7 (framework mode) adapter over @usegraft/sdk-core — the same
+ * `getContent` / `listContent` / `searchContent` surface as
+ * @usegraft/sdk-next, so a schema types every read identically across
+ * frameworks.
+ *
+ * No request-level memo here (sdk-next's React.cache has no React Router
+ * equivalent): reads go straight to the index from `loader` and `action`,
+ * which is the right default — a route makes a handful of reads and its loader
+ * runs once per request.
+ *
+ * Server-only by nature (it holds a database handle). `loader` and `action`
+ * run on the server and React Router strips them from the browser bundle, but
+ * build the handle in a `.server.ts` module anyway: that turns a stray client
+ * import into a build error instead of a database URL in a bundle.
+ *
+ * Caching: React Router has no tag-based data cache, so the Phase 4 tag
+ * contract maps onto HTTP — stamp `tagsFor(...)` into a CDN surrogate-key
+ * header (`Cache-Tag` / `Surrogate-Key`) from the route's `headers` export,
+ * and purge `tagsForChanges(branch, changeSet)` from your compile webhook.
+ */
+
+interface Graft<TCollections extends Record<string, AnyCollection>> {
+    /** Typed getDocument. */
+    getContent<K extends keyof TCollections & string>(collection: K, slug: string, options?: ReadOptions): Promise<Document<TCollections[K]> | null>;
+    /** Typed listDocuments. */
+    listContent<K extends keyof TCollections & string>(collection: K, options?: ListOptions): Promise<Document<TCollections[K]>[]>;
+    /** Typed searchDocuments (full-text, best-ranked first). */
+    searchContent<K extends keyof TCollections & string>(collection: K, query: string, options?: SearchOptions): Promise<SearchHit<TCollections[K]>[]>;
+    /** The underlying sdk-core client, for anything the helpers don't cover. */
+    client: GraftClient<TCollections>;
+}
+declare function createGraft<TCollections extends Record<string, AnyCollection>>(options: ClientOptions<TCollections>): Graft<TCollections>;
+
+/**
+ * Mounting the Graft runtime in React Router v7 — a resource route (a route
+ * module with no default export) returns raw Responses, and its `loader` and
+ * `action` are already Web-standard, so the "adapter" is one property access:
+ * React Router hands them a `{ request, params, context }` object, the
+ * handlers want its `request`.
+ *
+ * ```ts
+ * // app/routes/api.fn.$name.ts
+ * import { createFunctionsHandler } from "@usegraft/core";
+ * import { graftRoute } from "@usegraft/sdk-react-router";
+ * const handler = createFunctionsHandler({ … });
+ * export const action = graftRoute(handler);   // POST
+ * export const loader = graftRoute(handler);   // GET → 405s with Allow + fix
+ *
+ * // app/routes/api.mcp.ts
+ * import { createGraftMcpHandler } from "@usegraft/mcp";
+ * export const action = graftRoute(createGraftMcpHandler({ … }));
+ * ```
+ *
+ * React Router splits a route by method into two exports rather than naming
+ * the method, so one handler is mounted twice: `action` takes POST and the
+ * other mutating verbs, `loader` takes GET. Mounting `loader` is not
+ * ceremony — it is what makes a GET to a function endpoint answer with Graft's
+ * 405 and its `Allow` header instead of React Router's own "no loader" error,
+ * which teaches the caller nothing.
+ *
+ * Typed structurally (`{ request: Request }`) so this package needs no
+ * react-router dependency — every LoaderFunctionArgs and ActionFunctionArgs
+ * satisfies it, including the per-route `Route.LoaderArgs` types React Router
+ * generates.
+ */
+type FetchHandler = (request: Request) => Promise<Response>;
+/** A React Router loader or action (or anything args-shaped) over a Graft handler. */
+declare function graftRoute(handler: FetchHandler): (args: {
+    request: Request;
+}) => Promise<Response>;
+
+export { type FetchHandler, type Graft, createGraft, graftRoute };

package/dist/index.js

@@ -0,0 +1,40 @@
+// src/graft.ts
+import {
+  createClient
+} from "@usegraft/sdk-core";
+function createGraft(options) {
+  const client = createClient(options);
+  return {
+    client,
+    getContent: (collection, slug, opts) => client.getDocument(collection, slug, opts),
+    listContent: (collection, opts) => client.listDocuments(collection, opts),
+    searchContent: (collection, query, opts) => client.searchDocuments(collection, query, opts)
+  };
+}
+
+// src/routes.ts
+function graftRoute(handler) {
+  return (args) => handler(args.request);
+}
+
+// src/index.ts
+import {
+  createClient as createClient2,
+  toDocument,
+  collectionTag,
+  documentTag,
+  tagsFor,
+  tagsForChanges,
+  TAG_NAMESPACE
+} from "@usegraft/sdk-core";
+export {
+  TAG_NAMESPACE,
+  collectionTag,
+  createClient2 as createClient,
+  createGraft,
+  documentTag,
+  graftRoute,
+  tagsFor,
+  tagsForChanges,
+  toDocument
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@usegraft/sdk-react-router",
+  "version": "0.2.0",
+  "description": "React Router v7 adapter: typed content reads and loader/action mounts over Graft's stateless handlers.",
+  "keywords": [
+    "agent",
+    "ai",
+    "cms",
+    "graft",
+    "headless-cms",
+    "mcp",
+    "react",
+    "react-router",
+    "remix",
+    "typescript"
+  ],
+  "homepage": "https://github.com/AndersonDesign1/graft#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonDesign1/graft.git",
+    "directory": "packages/sdk-react-router"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@usegraft/sdk-core": "0.2.0"
+  },
+  "devDependencies": {
+    "@usegraft/core": "0.2.0"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}