@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/next.md

@@ -1,189 +1,189 @@
----
-title: "Next.js adapter"
-description: "The @bettercms-ai/next client, draft and revalidation routes, rendering exports, pagination and 404 handling, and static export with the snapshot."
----
-
-# @bettercms-ai/next
-
-Read this when the repo has `next.config.*`. Shared rules (hosting modes, env map, tags, value
-shapes) are in [frameworks.md](frameworks.md).
-
-## Client
-
-`createBetterCMS<Schema>(config)` from `@bettercms-ai/next`, typed by the file
-`bettercms-codegen` writes. Config: `workspace` (slug), `apiKey` (delivery key), `revalidate`
-(ISR seconds, or `false`). Keep the key server-side: `BETTERCMS_API_KEY`, never
-`NEXT_PUBLIC_*`.
-
-## Draft preview (App Router, mounted by you)
-
-Nothing is mounted automatically. Add the routes:
-
-- `createDraftModeRoute({ apiUrl })` → export `GET` from the route your project's preview link
-  points at. It reads `?token=&redirect=`, has the backend validate the token, enables Next draft
-  mode, stores the token in the httpOnly `bcms-preview-token` cookie and redirects.
-- `createDisableDraftRoute()` → export `GET` from an exit route.
-- Read drafts with `getEntry(slug, { preview: true, previewToken })`. `preview: true` without a
-  token throws.
-
-## Revalidation route
-
-`createRevalidateRoute()` → export `POST`. It verifies `X-BetterCMS-Signature` against the raw
-body with `secret`, else `BCMS_REVALIDATE_SECRET` (the project's revalidation secret from the
-dashboard), then revalidates every tag (`revalidateTag(tag, "max")`) and every page path
-(`revalidatePath`) the publish changed. Tag your reads with the backend's tag strings
-([frameworks.md](frameworks.md) Revalidation).
-
-## Rendering
-
-| Export | Use |
-|---|---|
-| `BcmsBlocks` | Render a block tree; pass `components` from `readComponents()`. A block outside its `window` is not rendered, read against `now` (default: render time); `showScheduled` draws it marked `data-bcms-window`, for a draft preview |
-| `readComponents()` | Component definitions from `bcms-content.json` |
-| `BcmsField` | `path`, `kind` (`richtext`/`image`), `as`; server-safe; no wrapper around a single DOM element ([animation.md](animation.md) §10) |
-| `BcmsButton` | A `button` field: `path`, `value`, `className`; one `<a>` with `data-variant` / `data-size`. Style only the looks the site has ([components.md](components.md) §5); server-safe |
-| `BcmsSections`, `BcmsSection` (from `@bettercms-ai/next/sections`) | The page's own sections, drawn in the CMS page's order (below); a server component |
-| `sectionsFor(slug)`, `sectionsStaticProps(slug, own?)`, `sectionsServerSideProps(slug, own)` | The block list, components and forms `BcmsSections` takes, from the snapshot |
-| `sectionRootAttrs(block)` | Spread on a section root your own code renders: `data-bcms-block`, `data-bcms-style` and the block's style, plus `data-bcms-hide` when `style.hideOn` is set: ship `RESPONSIVE_CSS` (exported here) in your global CSS ([components.md](components.md) §5) |
-| `bind`, `bindProps` | Binding attributes; instance-aware inside components |
-| `BcmsForm` + `getForm(idOrName)` | Forms from the snapshot ([forms-and-interactions.md](forms-and-interactions.md)) |
-| `buildMetadata(page, siteDefaults, location?)` | Next `Metadata` from native SEO fields |
-| `llmsTxtRoute(config)` | An `llms.txt` route handler |
-| `imageUrlBuilder({ baseUrl })` | Resize URLs; same media-host rules as Astro |
-| `BcmsImage` | An image field as one `<img>`: `path`, `src` (the value), `sizes` or `width`; declares the field and keeps the value's alt, crop and focal point; server-safe |
-
-Rules:
-
-- Binding attributes are always rendered; they are inert for visitors. Do not gate them behind
-  draft mode.
-- Pass `location` `{ siteUrl, path }` to `buildMetadata`. Without it the site URL comes from
-  `BETTERCMS_SITE_URL` and the path from the page slug; an app that serves pages under a prefix
-  (`/docs/[slug]`) must pass `location.path` or its canonical is wrong.
-- The package ships no sitemap or robots helper. Write `app/sitemap.ts` and `app/robots.ts`
-  yourself from published content, and leave out pages marked noindex.
-
-## Sections in the CMS order
-
-A page whose sections are written in its own file follows the CMS page's block list through
-`<BcmsSections>`. `bettercms init` writes this wrap (`npx @bettercms-ai/convert --sections`);
-write it by hand for a page the codemod refused ([componentize.md](componentize.md) §5).
-
-App Router, in a server component:
-
-```tsx
-import { sectionsFor } from "@bettercms-ai/next";
-import { BcmsSections, BcmsSection } from "@bettercms-ai/next/sections";
-
-export default function Home() {
-  return (
-    <main>
-      <BcmsSections {...sectionsFor("home")}>
-        <BcmsSection bind="hero">{(root) => <Hero rootProps={root} />}</BcmsSection>
-        <BcmsSection bind="code:sec1"><LogoCloud /></BcmsSection>
-        <BcmsSection bind="features"><section className="features">…</section></BcmsSection>
-      </BcmsSections>
-    </main>
-  );
-}
-```
-
-Pages Router: the page also renders in the browser, so the list is a page prop.
-
-```tsx
-import { sectionsStaticProps, type SectionsData } from "@bettercms-ai/next";
-import { BcmsSections, BcmsSection } from "@bettercms-ai/next/sections";
-
-export default function Home({ bcmsSections }: { bcmsSections: SectionsData }) {
-  return <BcmsSections {...bcmsSections}>…</BcmsSections>;
-}
-export const getStaticProps = sectionsStaticProps("home");
-```
-
-A page with its own data function passes it in, and the list joins the props it answers:
-`export const getStaticProps = sectionsStaticProps("home", pageStaticProps)`, or
-`sectionsServerSideProps` for `getServerSideProps`. `--sections` writes this for you.
-
-A page that only returns a view (`return <HomeView locale="en" />`) has its sections in the
-view's file, and `--sections` wraps them there: it follows the import (relative, a `paths` alias
-of the repository's tsconfig or jsconfig, an index file or a barrel's re-export) up to three
-components down. One view often serves several pages (`/` and `/fr`), so the page reads its own
-list and hands it over, and the view takes it as an optional prop:
-
-```tsx
-// app/fr/page.tsx
-export default function Page() {
-  return <HomeView locale="fr" bcmsSections={sectionsFor("fr")} />;
-}
-
-// views/home-view.tsx: a server or a "use client" component, it only names the type
-export default function HomeView({ bcmsSections, locale }: Props & { bcmsSections?: SectionsData }) {
-  return (
-    <main>
-      <BcmsSections {...(bcmsSections ?? { page: "" })}>
-        <BcmsSection bind="hero"><Hero locale={locale} /></BcmsSection>
-        …
-      </BcmsSections>
-    </main>
-  );
-}
-```
-
-A render that was handed no list (a route the CMS has no page for) keeps the source order. In the
-Pages Router the page passes on the prop it got: `<HomeView bcmsSections={bcmsSections} />`.
-
-- A bind is the family of the section's first bound field (`features-title` → `features`): the
-  `bind` on the page's `component` block. A block bound to a section renders it at the block's
-  position; a section added in the editor (no bind) renders through `BcmsBlocks`.
-- The stamp goes on the section's own root. One DOM element (`<section>`) gets
-  `data-bcms-block`, `data-bcms-style` and the block's style cloned onto it. A COMPONENT child
-  cannot be handed unknown props, so write it as a function and spread `root` on the element the
-  component renders (`<section {...rootProps}>`). Without the function it is stamped on a box:
-  `display:contents` while its block has no style, one `display:flow-root` box carrying the
-  style once it has ([animation.md](animation.md) §10).
-- A section no block names: `code:<bind>` always renders where it is written. A bare `<bind>`
-  does too until the list names one of the page's sections; from then on it is a removed one.
-  Write a bind bare only when the page already places it (`get_page`), otherwise `code:`.
-- `blocks` null (no snapshot) renders every child in source order, untouched.
-- Never inside a `"use client"` file: it reads its children's own elements, which a client
-  component cannot do across the server boundary.
-
-## Lists, pagination and missing content
-
-- `listEntries(model, { page, perPage })`: `page` is 1-based; `perPage` defaults to 20 and the
-  API caps it at 100. The result carries `items`, `totalItems`, `totalPages`, `hasNextPage` and
-  `hasPreviousPage`: drive the pager from those, never from `items.length`. Pass `select` on list
-  pages so each card fetches only the keys it renders.
-- A page route (`/blog/page/[n]`) answers `notFound()` when `n` is past `totalPages`; page 1 of an
-  empty collection is a 200 with an empty state, not a 404. Prerender pages 1…`totalPages` from
-  `generateStaticParams`.
-- `getEntry(slug)` returns `null` on a 404: call `notFound()` on `null`, never render an empty
-  shell with a 200. Why: an empty 200 is indexed as a thin page, and a typo'd slug never reads as
-  missing.
-- `listEntries` THROWS `BetterCMSError` on a 404 (an unknown workspace or model), on purpose: an
-  empty list there would hide a wrong model slug. Let it fail the build; do not catch it into `[]`.
-
-## Static export (`output: "export"`)
-
-- Pull the content before `next build`, every build: `"build": "bettercms pull-content && next build"`
-  (what `bettercms init` writes; keyless, it reads the project's published content).
-  `bettercms-snapshot` (from `BETTERCMS_API_URL`, `BETTERCMS_API_KEY`, `BETTERCMS_WORKSPACE`) does the
-  same with a key. Either writes `bcms-content.json`, and `createBetterCMS()` with no arguments reads
-  its workspace and project from it (after `NEXT_PUBLIC_BCMS_*`).
-- Without the snapshot the reads throw `SNAPSHOT_MISSING`. Why it throws instead of fetching:
-  a live fetch would turn pages into dynamic routes, and a static export silently leaves them out
-  of `out/`.
-- A preview build that must read live sets `BETTERCMS_PREVIEW=1`.
-- On a BetterCMS build the platform's own `bcms-content.json` is already in the project root.
-  `bettercms-snapshot` keeps it and `getContent` reads it: one file feeds `getContent`, `readPages`,
-  `readForms` and `readComponents`.
-- Draft mode and the revalidation route need a server; a static export has neither. Content
-  changes reach a static site only by rebuilding it.
-
-## Traps
-
-| Symptom | Cause | Rule |
-|---|---|---|
-| Empty `out/` after `next build` | No snapshot | Run `bettercms pull-content` first |
-| Page never updates after publish | Read tags do not match backend tags | Use `bcms:{workspace}:…` tags |
-| Component instance renders nothing | `components` not passed | `readComponents()` into `BcmsBlocks` |
-| Canonical missing or wrong only on the self-hosted site | `buildMetadata` without `location`, and no `BETTERCMS_SITE_URL` or a prefixed route | Pass `{ siteUrl, path }` |
+---
+title: "Next.js adapter"
+description: "The @bettercms-ai/next client, draft and revalidation routes, rendering exports, pagination and 404 handling, and static export with the snapshot."
+---
+
+# @bettercms-ai/next
+
+Read this when the repo has `next.config.*`. Shared rules (hosting modes, env map, tags, value
+shapes) are in [frameworks.md](frameworks.md).
+
+## Client
+
+`createBetterCMS<Schema>(config)` from `@bettercms-ai/next`, typed by the file
+`bettercms-codegen` writes. Config: `workspace` (slug), `apiKey` (delivery key), `revalidate`
+(ISR seconds, or `false`). Keep the key server-side: `BETTERCMS_API_KEY`, never
+`NEXT_PUBLIC_*`.
+
+## Draft preview (App Router, mounted by you)
+
+Nothing is mounted automatically. Add the routes:
+
+- `createDraftModeRoute({ apiUrl })` → export `GET` from the route your project's preview link
+  points at. It reads `?token=&redirect=`, has the backend validate the token, enables Next draft
+  mode, stores the token in the httpOnly `bcms-preview-token` cookie and redirects.
+- `createDisableDraftRoute()` → export `GET` from an exit route.
+- Read drafts with `getEntry(slug, { preview: true, previewToken })`. `preview: true` without a
+  token throws.
+
+## Revalidation route
+
+`createRevalidateRoute()` → export `POST`. It verifies `X-BetterCMS-Signature` against the raw
+body with `secret`, else `BCMS_REVALIDATE_SECRET` (the project's revalidation secret from the
+dashboard), then revalidates every tag (`revalidateTag(tag, "max")`) and every page path
+(`revalidatePath`) the publish changed. Tag your reads with the backend's tag strings
+([frameworks.md](frameworks.md) Revalidation).
+
+## Rendering
+
+| Export | Use |
+|---|---|
+| `BcmsBlocks` | Render a block tree; pass `components` from `readComponents()`. A block outside its `window` is not rendered, read against `now` (default: render time); `showScheduled` draws it marked `data-bcms-window`, for a draft preview |
+| `readComponents()` | Component definitions from `bcms-content.json` |
+| `BcmsField` | `path`, `kind` (`richtext`/`image`), `as`; server-safe; no wrapper around a single DOM element ([animation.md](animation.md) §10) |
+| `BcmsButton` | A `button` field: `path`, `value`, `className`; one `<a>` with `data-variant` / `data-size`. Style only the looks the site has ([components.md](components.md) §5); server-safe |
+| `BcmsSections`, `BcmsSection` (from `@bettercms-ai/next/sections`) | The page's own sections, drawn in the CMS page's order (below); a server component |
+| `sectionsFor(slug)`, `sectionsStaticProps(slug, own?)`, `sectionsServerSideProps(slug, own)` | The block list, components and forms `BcmsSections` takes, from the snapshot |
+| `sectionRootAttrs(block)` | Spread on a section root your own code renders: `data-bcms-block`, `data-bcms-style` and the block's style, plus `data-bcms-hide` when `style.hideOn` is set: ship `RESPONSIVE_CSS` (exported here) in your global CSS ([components.md](components.md) §5) |
+| `bind`, `bindProps` | Binding attributes; instance-aware inside components |
+| `BcmsForm` + `getForm(idOrName)` | Forms from the snapshot ([forms-and-interactions.md](forms-and-interactions.md)) |
+| `buildMetadata(page, siteDefaults, location?)` | Next `Metadata` from native SEO fields |
+| `llmsTxtRoute(config)` | An `llms.txt` route handler |
+| `imageUrlBuilder({ baseUrl })` | Resize URLs; same media-host rules as Astro |
+| `BcmsImage` | An image field as one `<img>`: `path`, `src` (the value), `sizes` or `width`; declares the field and keeps the value's alt, crop and focal point; server-safe |
+
+Rules:
+
+- Binding attributes are always rendered; they are inert for visitors. Do not gate them behind
+  draft mode.
+- Pass `location` `{ siteUrl, path }` to `buildMetadata`. Without it the site URL comes from
+  `BETTERCMS_SITE_URL` and the path from the page slug; an app that serves pages under a prefix
+  (`/docs/[slug]`) must pass `location.path` or its canonical is wrong.
+- The package ships no sitemap or robots helper. Write `app/sitemap.ts` and `app/robots.ts`
+  yourself from published content, and leave out pages marked noindex.
+
+## Sections in the CMS order
+
+A page whose sections are written in its own file follows the CMS page's block list through
+`<BcmsSections>`. `bettercms init` writes this wrap (`npx @bettercms-ai/convert --sections`);
+write it by hand for a page the codemod refused ([componentize.md](componentize.md) §5).
+
+App Router, in a server component:
+
+```tsx
+import { sectionsFor } from "@bettercms-ai/next";
+import { BcmsSections, BcmsSection } from "@bettercms-ai/next/sections";
+
+export default function Home() {
+  return (
+    <main>
+      <BcmsSections {...sectionsFor("home")}>
+        <BcmsSection bind="hero">{(root) => <Hero rootProps={root} />}</BcmsSection>
+        <BcmsSection bind="code:sec1"><LogoCloud /></BcmsSection>
+        <BcmsSection bind="features"><section className="features">…</section></BcmsSection>
+      </BcmsSections>
+    </main>
+  );
+}
+```
+
+Pages Router: the page also renders in the browser, so the list is a page prop.
+
+```tsx
+import { sectionsStaticProps, type SectionsData } from "@bettercms-ai/next";
+import { BcmsSections, BcmsSection } from "@bettercms-ai/next/sections";
+
+export default function Home({ bcmsSections }: { bcmsSections: SectionsData }) {
+  return <BcmsSections {...bcmsSections}>…</BcmsSections>;
+}
+export const getStaticProps = sectionsStaticProps("home");
+```
+
+A page with its own data function passes it in, and the list joins the props it answers:
+`export const getStaticProps = sectionsStaticProps("home", pageStaticProps)`, or
+`sectionsServerSideProps` for `getServerSideProps`. `--sections` writes this for you.
+
+A page that only returns a view (`return <HomeView locale="en" />`) has its sections in the
+view's file, and `--sections` wraps them there: it follows the import (relative, a `paths` alias
+of the repository's tsconfig or jsconfig, an index file or a barrel's re-export) up to three
+components down. One view often serves several pages (`/` and `/fr`), so the page reads its own
+list and hands it over, and the view takes it as an optional prop:
+
+```tsx
+// app/fr/page.tsx
+export default function Page() {
+  return <HomeView locale="fr" bcmsSections={sectionsFor("fr")} />;
+}
+
+// views/home-view.tsx: a server or a "use client" component, it only names the type
+export default function HomeView({ bcmsSections, locale }: Props & { bcmsSections?: SectionsData }) {
+  return (
+    <main>
+      <BcmsSections {...(bcmsSections ?? { page: "" })}>
+        <BcmsSection bind="hero"><Hero locale={locale} /></BcmsSection>
+        …
+      </BcmsSections>
+    </main>
+  );
+}
+```
+
+A render that was handed no list (a route the CMS has no page for) keeps the source order. In the
+Pages Router the page passes on the prop it got: `<HomeView bcmsSections={bcmsSections} />`.
+
+- A bind is the family of the section's first bound field (`features-title` → `features`): the
+  `bind` on the page's `component` block. A block bound to a section renders it at the block's
+  position; a section added in the editor (no bind) renders through `BcmsBlocks`.
+- The stamp goes on the section's own root. One DOM element (`<section>`) gets
+  `data-bcms-block`, `data-bcms-style` and the block's style cloned onto it. A COMPONENT child
+  cannot be handed unknown props, so write it as a function and spread `root` on the element the
+  component renders (`<section {...rootProps}>`). Without the function it is stamped on a box:
+  `display:contents` while its block has no style, one `display:flow-root` box carrying the
+  style once it has ([animation.md](animation.md) §10).
+- A section no block names: `code:<bind>` always renders where it is written. A bare `<bind>`
+  does too until the list names one of the page's sections; from then on it is a removed one.
+  Write a bind bare only when the page already places it (`get_page`), otherwise `code:`.
+- `blocks` null (no snapshot) renders every child in source order, untouched.
+- Never inside a `"use client"` file: it reads its children's own elements, which a client
+  component cannot do across the server boundary.
+
+## Lists, pagination and missing content
+
+- `listEntries(model, { page, perPage })`: `page` is 1-based; `perPage` defaults to 20 and the
+  API caps it at 100. The result carries `items`, `totalItems`, `totalPages`, `hasNextPage` and
+  `hasPreviousPage`: drive the pager from those, never from `items.length`. Pass `select` on list
+  pages so each card fetches only the keys it renders.
+- A page route (`/blog/page/[n]`) answers `notFound()` when `n` is past `totalPages`; page 1 of an
+  empty collection is a 200 with an empty state, not a 404. Prerender pages 1…`totalPages` from
+  `generateStaticParams`.
+- `getEntry(slug)` returns `null` on a 404: call `notFound()` on `null`, never render an empty
+  shell with a 200. Why: an empty 200 is indexed as a thin page, and a typo'd slug never reads as
+  missing.
+- `listEntries` THROWS `BetterCMSError` on a 404 (an unknown workspace or model), on purpose: an
+  empty list there would hide a wrong model slug. Let it fail the build; do not catch it into `[]`.
+
+## Static export (`output: "export"`)
+
+- Pull the content before `next build`, every build: `"build": "bettercms pull-content && next build"`
+  (what `bettercms init` writes; keyless, it reads the project's published content).
+  `bettercms-snapshot` (from `BETTERCMS_API_URL`, `BETTERCMS_API_KEY`, `BETTERCMS_WORKSPACE`) does the
+  same with a key. Either writes `bcms-content.json`, and `createBetterCMS()` with no arguments reads
+  its workspace and project from it (after `NEXT_PUBLIC_BCMS_*`).
+- Without the snapshot the reads throw `SNAPSHOT_MISSING`. Why it throws instead of fetching:
+  a live fetch would turn pages into dynamic routes, and a static export silently leaves them out
+  of `out/`.
+- A preview build that must read live sets `BETTERCMS_PREVIEW=1`.
+- On a BetterCMS build the platform's own `bcms-content.json` is already in the project root.
+  `bettercms-snapshot` keeps it and `getContent` reads it: one file feeds `getContent`, `readPages`,
+  `readForms` and `readComponents`.
+- Draft mode and the revalidation route need a server; a static export has neither. Content
+  changes reach a static site only by rebuilding it.
+
+## Traps
+
+| Symptom | Cause | Rule |
+|---|---|---|
+| Empty `out/` after `next build` | No snapshot | Run `bettercms pull-content` first |
+| Page never updates after publish | Read tags do not match backend tags | Use `bcms:{workspace}:…` tags |
+| Component instance renders nothing | `components` not passed | `readComponents()` into `BcmsBlocks` |
+| Canonical missing or wrong only on the self-hosted site | `buildMetadata` without `location`, and no `BETTERCMS_SITE_URL` or a prefixed route | Pass `{ siteUrl, path }` |

package/dist/skills/bettercms/references/other-frameworks.md

@@ -1,85 +1,85 @@
----
-title: "Other frameworks"
-description: "Reading BetterCMS content from Nuxt, SvelteKit, React Router or Vite through the SDK createClient read core: options, 404 behaviour, env names, and what only the Astro and Next adapters provide."
----
-
-# Other frameworks
-
-Read this when the repo has neither `astro.config.*` nor `next.config.*`. React (Vite), SvelteKit
-and Nuxt have adapters (§0); anything else reads through the framework-agnostic core in
-`@bettercms-ai/sdk`, the same one every adapter wraps. Shared rules (hosting modes, value shapes,
-media host, revalidation tags) are in [frameworks.md](frameworks.md).
-
-## 0. The adapters
-
-| Repo has | Install | Settings | Sections | Drafts |
-|---|---|---|---|---|
-| `vite.config.*` + React | `@bettercms-ai/react` | `<BcmsProvider env={import.meta.env}>`, `VITE_BCMS_*` | `<BcmsBlocks blocks={page.blocks}>` (Next's markup) | the editor's `/api/draft` link, no server; the host rewrites it to the app |
-| `svelte.config.*` (SvelteKit) | `@bettercms-ai/sveltekit` | `createBcms({ env: { ...publicEnv, ...privateEnv } })`, `PUBLIC_BCMS_*` | `bcms.sections(slug, fetch)` in `load`, then `<div use:bcmsSections={data.sections}>{@html sectionsMarkup(data.sections)}</div>` | `src/routes/api/draft/+server.ts`: `GET = ({ request }) => bcms.draftEnable(request)`; `await bcms.client(request)` reads drafts |
-| `nuxt.config.*` | `@bettercms-ai/nuxt` | `createBcms({ env: process.env })` in `server/utils`, `NUXT_PUBLIC_BCMS_*` | a server route returning `bcms.sections(slug)`, then `<div v-bcms-sections v-html="sectionsMarkup(data)">` | `server/routes/api/draft.get.ts`: `bcms.draftEnable(toWebRequest(e))` |
-
-- SvelteKit and Nuxt sections are server-rendered by BetterCMS (the hosted renderer's markup, a
-  stylesheet scoped to `[data-bcms-rendered="platform"]`, and the form, slider and tab scripts):
-  never rebuild them as components, and never paste their HTML into the repo. Field copy outside
-  the sections is still read with the client and bound with `data-bcms-field`
-  ([bindings.md](bindings.md)).
-- The sections are the PUBLISHED page; draft mode switches the client, not the fragment.
-- Set `BCMS_PROJECT_ID` under the framework's prefix: sections and keyless reads are addressed to it.
-- `BCMS_DRAFT_SECRET` (server-only) signs the draft cookie on SvelteKit and Nuxt; a React SPA has none.
-
-## 1. The client
-
-```ts
-import { createClient } from "@bettercms-ai/sdk";
-
-export const bcms = createClient({
-  apiUrl: process.env.BCMS_API_URL!,     // the backend origin; the SDK adds /api/v1/delivery/<workspace>
-  workspace: process.env.BCMS_WORKSPACE!,
-  projectId: process.env.BCMS_PROJECT_ID, // scopes listForms
-});
-```
-
-Reading published content needs no key. The platform sets `BCMS_API_URL`, `BCMS_WORKSPACE` and
-`BCMS_PROJECT_ID` on every build and running server app, and again under each framework's public
-prefix (`NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`…); the table is in
-[external-content.md](external-content.md). On a site BetterCMS builds, never add them to `.env`.
-A headless front end on its own host sets them itself: in `.env` locally, and on the host by
-`npx @bettercms-ai/cli@latest deploy --to <host>`.
-
-| Option | Use |
-|---|---|
-| `perspective: "drafts"` | Draft reads; needs a `content:read:draft` key or a `previewToken`. Stega is on by default there ([bindings.md](bindings.md) §5) |
-| `cache: true` | Collapse identical GETs for the client's life. Only for a static build (one point-in-time dataset); never in dev, SSR or drafts |
-| `timeout` | Per-attempt ms, default 10000 |
-
-## 2. Methods and their 404s
-
-| Method | Returns | On a missing slug |
-|---|---|---|
-| `getPage(slug)` | the page (`blocks`, meta columns) | `null`, after scanning the page list |
-| `getEntry(slug, { depth, select })` | one entry | throws `BetterCMSError` with `status` 404 |
-| `listEntries({ model, page, perPage, depth, select })` | `{ items, page, perPage, totalItems, totalPages, hasNextPage, hasPreviousPage }` | a list 404 (unknown model or workspace) throws |
-| `listPages`, `listComponents`, `getLayout`, `listForms` | pages, component definitions, the Global Layout (`null` if none), forms (render only `status: "published"`) | |
-
-Catch the 404 on `getEntry` and answer the framework's not-found (a 404 status, never an empty
-200). Let a list 404 fail the build. Drive pagers from `totalPages`/`hasNextPage`.
-
-## 3. Where to call it
-
-Call the client only in code that runs on the server or at build time, so a key (drafts) never
-reaches the bundle: a Nuxt server route or `useAsyncData` on the server, a SvelteKit
-`+page.server.ts` `load`, a React Router `loader`. A browser-only Vite SPA reads published content
-with the public-prefixed variables and no key.
-
-## 4. What only the adapters give you
-
-No `BcmsBlocks`/`BcmsField` components, no `bind`/`bindProps` helpers, no draft routes and no
-snapshot bin exist for these frameworks. So:
-
-- Render component blocks yourself from `listComponents()` definitions, and write binding
-  attributes by hand per [bindings.md](bindings.md) (`data-bcms-field`, `data-bcms-block`).
-- Rich text: read it through the SDK's `plain`, `rich` or `portableText` helpers, which accept a
-  bare string or the `{ format, value, html }` envelope.
-- Images: `imageUrlBuilder` is re-exported from the SDK ([media-and-brand.md](media-and-brand.md)).
-- Meta: `resolveSeo` merges page over site defaults; write the result into `<head>` yourself.
-- Verify with the two-path smoke test in [frameworks.md](frameworks.md) Verify.
+---
+title: "Other frameworks"
+description: "Reading BetterCMS content from Nuxt, SvelteKit, React Router or Vite through the SDK createClient read core: options, 404 behaviour, env names, and what only the Astro and Next adapters provide."
+---
+
+# Other frameworks
+
+Read this when the repo has neither `astro.config.*` nor `next.config.*`. React (Vite), SvelteKit
+and Nuxt have adapters (§0); anything else reads through the framework-agnostic core in
+`@bettercms-ai/sdk`, the same one every adapter wraps. Shared rules (hosting modes, value shapes,
+media host, revalidation tags) are in [frameworks.md](frameworks.md).
+
+## 0. The adapters
+
+| Repo has | Install | Settings | Sections | Drafts |
+|---|---|---|---|---|
+| `vite.config.*` + React | `@bettercms-ai/react` | `<BcmsProvider env={import.meta.env}>`, `VITE_BCMS_*` | `<BcmsBlocks blocks={page.blocks}>` (Next's markup) | the editor's `/api/draft` link, no server; the host rewrites it to the app |
+| `svelte.config.*` (SvelteKit) | `@bettercms-ai/sveltekit` | `createBcms({ env: { ...publicEnv, ...privateEnv } })`, `PUBLIC_BCMS_*` | `bcms.sections(slug, fetch)` in `load`, then `<div use:bcmsSections={data.sections}>{@html sectionsMarkup(data.sections)}</div>` | `src/routes/api/draft/+server.ts`: `GET = ({ request }) => bcms.draftEnable(request)`; `await bcms.client(request)` reads drafts |
+| `nuxt.config.*` | `@bettercms-ai/nuxt` | `createBcms({ env: process.env })` in `server/utils`, `NUXT_PUBLIC_BCMS_*` | a server route returning `bcms.sections(slug)`, then `<div v-bcms-sections v-html="sectionsMarkup(data)">` | `server/routes/api/draft.get.ts`: `bcms.draftEnable(toWebRequest(e))` |
+
+- SvelteKit and Nuxt sections are server-rendered by BetterCMS (the hosted renderer's markup, a
+  stylesheet scoped to `[data-bcms-rendered="platform"]`, and the form, slider and tab scripts):
+  never rebuild them as components, and never paste their HTML into the repo. Field copy outside
+  the sections is still read with the client and bound with `data-bcms-field`
+  ([bindings.md](bindings.md)).
+- The sections are the PUBLISHED page; draft mode switches the client, not the fragment.
+- Set `BCMS_PROJECT_ID` under the framework's prefix: sections and keyless reads are addressed to it.
+- `BCMS_DRAFT_SECRET` (server-only) signs the draft cookie on SvelteKit and Nuxt; a React SPA has none.
+
+## 1. The client
+
+```ts
+import { createClient } from "@bettercms-ai/sdk";
+
+export const bcms = createClient({
+  apiUrl: process.env.BCMS_API_URL!,     // the backend origin; the SDK adds /api/v1/delivery/<workspace>
+  workspace: process.env.BCMS_WORKSPACE!,
+  projectId: process.env.BCMS_PROJECT_ID, // scopes listForms
+});
+```
+
+Reading published content needs no key. The platform sets `BCMS_API_URL`, `BCMS_WORKSPACE` and
+`BCMS_PROJECT_ID` on every build and running server app, and again under each framework's public
+prefix (`NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`…); the table is in
+[external-content.md](external-content.md). On a site BetterCMS builds, never add them to `.env`.
+A headless front end on its own host sets them itself: in `.env` locally, and on the host by
+`npx @bettercms-ai/cli@latest deploy --to <host>`.
+
+| Option | Use |
+|---|---|
+| `perspective: "drafts"` | Draft reads; needs a `content:read:draft` key or a `previewToken`. Stega is on by default there ([bindings.md](bindings.md) §5) |
+| `cache: true` | Collapse identical GETs for the client's life. Only for a static build (one point-in-time dataset); never in dev, SSR or drafts |
+| `timeout` | Per-attempt ms, default 10000 |
+
+## 2. Methods and their 404s
+
+| Method | Returns | On a missing slug |
+|---|---|---|
+| `getPage(slug)` | the page (`blocks`, meta columns) | `null`, after scanning the page list |
+| `getEntry(slug, { depth, select })` | one entry | throws `BetterCMSError` with `status` 404 |
+| `listEntries({ model, page, perPage, depth, select })` | `{ items, page, perPage, totalItems, totalPages, hasNextPage, hasPreviousPage }` | a list 404 (unknown model or workspace) throws |
+| `listPages`, `listComponents`, `getLayout`, `listForms` | pages, component definitions, the Global Layout (`null` if none), forms (render only `status: "published"`) | |
+
+Catch the 404 on `getEntry` and answer the framework's not-found (a 404 status, never an empty
+200). Let a list 404 fail the build. Drive pagers from `totalPages`/`hasNextPage`.
+
+## 3. Where to call it
+
+Call the client only in code that runs on the server or at build time, so a key (drafts) never
+reaches the bundle: a Nuxt server route or `useAsyncData` on the server, a SvelteKit
+`+page.server.ts` `load`, a React Router `loader`. A browser-only Vite SPA reads published content
+with the public-prefixed variables and no key.
+
+## 4. What only the adapters give you
+
+No `BcmsBlocks`/`BcmsField` components, no `bind`/`bindProps` helpers, no draft routes and no
+snapshot bin exist for these frameworks. So:
+
+- Render component blocks yourself from `listComponents()` definitions, and write binding
+  attributes by hand per [bindings.md](bindings.md) (`data-bcms-field`, `data-bcms-block`).
+- Rich text: read it through the SDK's `plain`, `rich` or `portableText` helpers, which accept a
+  bare string or the `{ format, value, html }` envelope.
+- Images: `imageUrlBuilder` is re-exported from the SDK ([media-and-brand.md](media-and-brand.md)).
+- Meta: `resolveSeo` merges page over site defaults; write the result into `<head>` yourself.
+- Verify with the two-path smoke test in [frameworks.md](frameworks.md) Verify.