# Next.js

How Smoodly plugs into a Next.js app: the one route file, the server seam, the admin route group, and what happens on a request. The installer writes all of it; this page is for reading it.

## The route file

One file under `app/(site)` serves every CMS URL, and it needs no editing:

File: `app/(site)/[[...path]]/page.tsx`

```tsx
import { renderSmoodlyPath, smoodlyMetadata } from "@/smoodly/server";
// …
export function generateStaticParams() {
  return [];
}
// …
export default async function Page({ params, searchParams }: { params: Params; searchParams: SearchParams }) {
  return renderSmoodlyPath((await params).path ?? [], { searchParams });
}
```

`renderSmoodlyPath` resolves the URL path to a page, a path in the tree or an entry, and renders it with its page type or entry page; no segments is the home. A page or entry that does not exist, or is not published, is a 404. A multilingual site has the same file under `app/[locale]` and passes the language along.

`generateStaticParams` returning nothing is what makes the page cacheable: Next builds no page ahead, renders each address on its first visit and keeps the result until a publish expires it ([What happens on a request](#what-happens-on-a-request)). Keep the export; without it Next renders the route on every request.

A route file of your own beside this one, `app/(site)/pricing/page.tsx`, wins for that exact URL by Next's precedence; deeper URLs still reach the catch-all. A page an editor creates at `/pricing` saves and publishes, but visitors see your route instead. The page editor says so: when its canvas cannot show the page, a warning names the cause, with a line starting "For your developer:" that says what to change. A home of your own is the same file: return your component when `path` is empty.

A page under this route may not read cookies, headers or search params, and neither may a section or the layout above it: Next decided the page is static, so a dynamic API inside the render answers a 500 in production, and `next dev` does not show it. A page that needs them is its own route file, which renders on every request. The same goes for `connection()`: a snippet from before 0.0.50 that awaits it in `smoodly/server.ts` turns every page into that 500. The file passes `searchParams` on to `renderSmoodlyPath`, which reads them inside draft mode only: the canvas asks for the page with a `smoodly-editor` parameter, and without it the page renders with no editor bridge, so nothing in the canvas can be selected. The page editor names that case too.

## The server seam

`smoodly/server.ts` builds everything the routes and the admin share, once per server, and only when first used, so a build with no environment still succeeds:

File: `smoodly/server.ts`

```ts
  const site = createSmoodlyApi({ ...apiEnv(), config });
  // …
  const renderer = createPageRenderer({ site, ...views(), href });
  // …
  const q = createSmoodlyQueries({ site, collections, globals });
```

`createSmoodlyApi` reads your content over Smoodly's API, one call per read, and computes everything else the renderer needs from the config, so the two cannot disagree. Your site opens no database. `views()` hands the renderer your components from `smoodly/views.ts`, checked against the config's schemas the first time the site renders.

The live site reads two variables: `SMOODLY_SPACE_ID`, the space your content lives in, and `SMOODLY_SECRET_KEY`. The admin needs the same two: it learns where editors sign in from Smoodly's API. `SITE_URL` is the address the build pushes to the space with the schema (`prebuild: "smoodly push"` in `package.json`). [Keys](https://smoodly.io/docs/getting-started/keys.md) explains them. It exports the two functions the routes call, `q` for [queries](https://smoodly.io/docs/collections/queries.md), and `href`, the one seam that turns a language-relative path into a site URL.

The file also builds `content()`, which scripts write content through ([Content from code](https://smoodly.io/docs/getting-started/content-from-code.md)). It takes it from `smoodly/admin` and posts to the same API with the secret key:

File: `smoodly/server.ts`

```ts
  return createSmoodlyContent({ config, href, transport: apiTransport(apiEnv()) });
```

## The admin

The admin is one route. The `smoodly` package ships it prebuilt, so your app compiles none of it:

File: `app/(smoodly)/admin/[[...segments]]/route.ts`

```ts
import { createAdminRoute } from "smoodly/next";
import { config } from "@/smoodly/config";
import { adminDeps, presence } from "@/smoodly/server";

export const { GET, POST } = createAdminRoute(() => ({ config, ...adminDeps(), presence }));
```

`GET` serves the admin's page and the script and fonts it loads. The admin's operations run in Smoodly's API, which accepts them from the addresses your builds pushed and checks the editor's session against the space's members; the browser never holds a write key. `POST` takes two calls only: the API's call after a publish naming the cache tags to expire, which must be signed with the API's own key and less than a minute old, and the editor's browser turning on draft mode with a grant the API signed, accepted from the site's own address only.

`presence` is where the browser opens the editing-presence connection (Smoodly's API and your space), public values read from `smoodly/server.ts` per request; where editors sign in, the page asks Smoodly's API. Leave `presence` out and the admin works the same, minus [who is editing what](https://smoodly.io/docs/getting-started/working-together.md).

The route folder under `app/(smoodly)` must match `admin.path` in the config; [The admin](https://smoodly.io/docs/getting-started/admin) covers moving it. The admin's page has no layout, so the site's layout never wraps it.

## Content in the browser

The publishable key is public and reads published content only, so a component that runs in the browser could read with it. The starter's way is a route in your own app that reads through `q` on the server: the browser holds no key, and the route decides what leaves. A component that needs entries, a search box or a "load more" button, asks that route:

File: `app/api/articles/route.ts`

```ts
import { q } from "@/smoodly/server";

export async function GET(request: Request) {
  const locale = new URL(request.url).searchParams.get("locale") ?? undefined;
  const items = await q().getEntries("articles", { locale, limit: 12 });
  return Response.json(items.map((item) => ({ id: item.id, path: item.path, title: item.fields.title })));
}
```

Return only what the browser should see: the route decides, not the service. Published content only leaves the route, because a request outside the editor's draft mode reads published rows.

## What happens on a request

A CMS route is never built ahead: `next build` reads nothing from the service and needs no keys. Each address renders on its first visit, outside draft mode, and Next keeps the page in its route cache, which Vercel serves from its CDN without running your function. The render reads under tags that name the page or entry by id, the layout's global items by name, and, for a 404, a redirect or a code-owned page, one tag for every address. Publishing, unpublishing, renaming or deleting expires exactly those tags at once; the next visit renders fresh. Nothing expires on a timer. One consequence: a renamed page's old address answers its permanent redirect without the request's query string, since the cached answer cannot read it.

Draft mode is Next's way of rendering unpublished content for one browser. The editor turns it on for the editor's browser by posting a grant from Smoodly's API to the admin route, then loads the site's real URL in the canvas with `/~editor` after it, which mounts the bridge the canvas talks to. In draft mode every read returns the live draft rows, and *History* renders an old version at the page's URL followed by `/~version~` and the version's id. The flags ride the path, not the query, because Vercel passes a cached route only its own parameters, even in draft mode. The public site honors neither: outside draft mode such an address is not found.

## Preview mode

Opening the page editor turns on draft mode for that browser. Every page Smoodly renders then shows a floating pill, outside the editor's canvas: *Preview · unpublished changes*, with *Exit preview*. Editors can drag it to the left, center or right, move it with the arrow keys, or hide it until the next reload. Outside draft mode the page's HTML has no trace of it, and no page loads Smoodly's editor code.

Exit goes to `/api/preview?disable`, the route every starter ships:

File: `app/api/preview/route.ts`

```ts
export { previewRoute as GET } from "smoodly/next";
```

If you moved that route, tell the renderer with the `previewRoute` option of `createPageRenderer`, like `previewRoute: "/my/preview"`.

A page you render yourself, without `renderSmoodlyPath`, can show the pill too:

File: `app/pricing/page.tsx`

```tsx
import { draftMode } from "next/headers";
import { previewPill } from "smoodly/next";

export default async function Pricing() {
  const { isEnabled } = await draftMode();
  return <main>{isEnabled && previewPill()}</main>;
}
```

The pill loads as a small script of its own, in preview only.

## Cache Components

Leave `cacheComponents` off in `next.config.ts`. Next 16's Cache Components mode brings the `"use cache"` directive and partial prerendering for every route: a static shell goes out first and the rest streams in. Smoodly's catch-all serves paths that are unknown at build time, so under that mode it is always sent from a shell that has already committed status 200. A page that doesn't exist then answers 200 with a `noindex` tag instead of 404, and a redirect answers 200 instead of 308, both of which search engines treat worse. No route can opt out of the mode, so Smoodly does not support it.

You keep `unstable_cache` and `revalidateTag`, and every page and entry is already cached under its own tag. What you give up is `"use cache"` in your own code.

If the mode is on, the server log says so once, at the first page render:

```text
smoodly: Next's cacheComponents is on, and Smoodly does not support it — …
```

## Images

`SmoodlyImage` from `smoodly/image` renders an `f.image()` value as a plain `<img>`, or a `<picture>` for named crops, over cuts from Smoodly's media host in AVIF or WebP. It does not use `next/image`, so `next.config.ts` holds no `images` setting and Vercel's image optimization is never billed. The component calls React's `preconnect` for the media host, which React places in the head. [Images and crops](https://smoodly.io/docs/media/images-and-crops.md) has the rest.

Next, [Upgrading](https://smoodly.io/docs/reference/upgrading.md) says what a new version asks of your code.
