create-nextly-app 0.0.2-alpha.65 → 0.0.2-alpha.67

package/skills/nextly-deploy/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: nextly-deploy
+description: >-
+  Use when deploying a Nextly project to production, on Vercel or a Node.js
+  server: choosing the production database, creating and committing
+  migrations, running them on deploy, the environment variables Nextly
+  requires, media storage that survives restarts, and checking the live site.
+  Also use when a deployed Nextly app has missing tables, refuses to start,
+  or loses uploaded files.
+metadata:
+  nextly-version: 0.0.2-alpha.67
+---
+
+# Deploy a Nextly project
+
+A Nextly app is a Next.js app, so it deploys wherever Next.js does. What
+Nextly adds: a production database, migrations applied before the new code
+serves traffic, a few environment variables, and media storage that is not
+the local disk on serverless hosts.
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4 and PostgreSQL 17:
+the steps below were run end to end, from an empty database to a published
+post in a production build. Run `npx nextly --version`; if it prints a newer
+version, prefer <https://nextlyhq.com/docs/guides/deployment> where it
+disagrees with this skill.
+
+## 1. Pick the production database, and develop on the same kind
+
+Use PostgreSQL (recommended) or MySQL in production; on Vercel, a managed one
+such as Neon, Supabase or Vercel Postgres. SQLite does not survive on
+serverless hosts.
+
+Develop against the same kind of database, and switch **before** creating the
+first migration. `migrate:create` writes SQL in the dialect of the database
+configured when you run it, so migrations made on SQLite will not run on
+PostgreSQL. If SQLite migrations already exist and nothing has been deployed,
+delete `src/db/migrations/` (the `.sql` files and `meta/`) after switching and
+run `migrate:create` again. A live SQLite installation needs its data moved,
+which this skill does not cover.
+
+To switch a project from SQLite to PostgreSQL:
+
+Nextly's packages are released together, so install each `@nextlyhq/*`
+package at exactly the version of `nextly` the project runs, which `npx nextly
+--version` prints:
+
+```bash
+npm install "@nextlyhq/adapter-postgres@$(npx nextly --version)" pg   # pnpm add / yarn add / bun add
+npm ls nextly @nextlyhq/adapter-postgres     # or pnpm ls / yarn why; both at the same version
+```
+
+Use the project's own package manager throughout, so its lockfile stays the
+one that is deployed.
+
+Then, in `.env`, set `DB_DIALECT=postgresql` and `DATABASE_URL` to a local
+PostgreSQL database, and add `"@nextlyhq/adapter-postgres"` and `"pg"` to
+`serverExternalPackages` in `next.config.ts`. Restart `next dev`.
+
+## 2. Create the migrations and commit them
+
+In development, schema changes apply directly. Production only applies
+migration files. Whenever collections change, before deploying:
+
+```bash
+npx nextly migrate:create <what_changed>
+```
+
+It writes `src/db/migrations/<timestamp>_<name>.sql` and a snapshot in
+`src/db/migrations/meta/`. Commit both. Migrations only move forward: to undo
+one, add a new one.
+
+## 3. Run migrations on every deploy
+
+In `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "nextly migrate && next build"
+  }
+}
+```
+
+`nextly migrate` first creates or updates Nextly's own tables (users, roles,
+media and the rest), then applies your pending migrations, against the
+database in `DATABASE_URL`. On an empty database this is all that is needed
+before the first start.
+
+With several developers or preview deploys pointing at one database, run
+`npx nextly migrate` as its own CI step before the deploy instead, and keep
+`build` as `next build`.
+
+## 4. Environment variables
+
+| Variable                 | Value                                                                                                       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `DB_DIALECT`             | `postgresql` or `mysql`                                                                                     |
+| `DATABASE_URL`           | the production database                                                                                     |
+| `NEXTLY_SECRET`          | at least 32 characters, new for production: `openssl rand -base64 32`                                       |
+| `NEXT_PUBLIC_APP_URL`    | the public URL, such as `https://example.com`                                                               |
+| `NEXTLY_ALLOWED_ORIGINS` | only if browsers reach the app on an origin it does not see itself, such as behind a proxy; comma-separated |
+
+`NEXT_PUBLIC_APP_URL` is built into the client bundle, so set it before the
+build. Never commit `.env` files.
+
+## 5. Media storage
+
+Uploads go to `./public/uploads` by default. That is lost on every deploy or
+cold start on Vercel and other serverless hosts. Use a storage adapter,
+installed at the same version as `nextly` as above:
+
+```ts
+// nextly.config.ts, on Vercel: npm install @nextlyhq/storage-vercel-blob@<nextly version>
+import { defineConfig } from "nextly/config";
+import { vercelBlobStorage } from "@nextlyhq/storage-vercel-blob";
+
+export default defineConfig({
+  storage: [
+    vercelBlobStorage({
+      token: process.env.BLOB_READ_WRITE_TOKEN!,
+      collections: { media: true },
+    }),
+  ],
+  // collections, typescript, ...
+});
+```
+
+Vercel sets `BLOB_READ_WRITE_TOKEN` when Blob storage is added to the project.
+For AWS S3, use `@nextlyhq/storage-s3` with
+`s3Storage({ bucket, region, accessKeyId, secretAccessKey, collections: { media: true } })`.
+Other S3-compatible providers also need their `endpoint`, and a `publicUrl`
+when files are served from another address. For Cloudflare R2:
+
+```ts
+s3Storage({
+  bucket: process.env.R2_BUCKET!,
+  region: "auto",
+  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+  publicUrl: process.env.R2_PUBLIC_URL,
+  collections: { media: true },
+});
+```
+
+For other providers, use the settings in the adapter's README. A Node.js
+server with a persistent disk can keep the default.
+
+On Vercel, uploads from the admin pass through a Vercel Function, which
+refuses request bodies over 4.5 MB (`413 FUNCTION_PAYLOAD_TOO_LARGE`). With
+this setup, files above that size cannot be uploaded through the admin; a
+Node.js server has no such limit.
+
+## 6. Create the first admin before the site is public
+
+A new production database has no admin. Until it has one, whoever opens
+`/admin/setup` first becomes Super Admin, so create that account before anyone
+else can reach the site. Setup then closes for good: a later attempt is
+refused with `SETUP_COMPLETE`.
+
+The simplest way is a production build on your own machine, pointed at the
+production database:
+
+```bash
+export DATABASE_URL="<the production database>"
+npm run build         # runs nextly migrate against it, then next build
+npm start             # next start, on http://localhost:3000
+```
+
+Export every other variable the config reads as well. With Vercel Blob,
+`BLOB_READ_WRITE_TOKEN` is needed to load `nextly.config.ts` at all, and the
+build stops without it. With S3, the bucket and region are needed to load
+it; the keys can come from the AWS credential chain instead (an IAM role, a
+profile), so a build that succeeds says nothing about them. Where a value
+exists only in the host's settings and cannot be brought to your machine, use
+the protected-host path below instead.
+
+Open `http://localhost:3000/admin/setup`, create the account, stop the
+server, then deploy. If you cannot reach the production database from your
+machine, keep the deployment private until setup is done, behind your host's
+access protection.
+
+Never run `next dev` against the production database. Development mode
+applies schema changes directly to whatever database it points at.
+
+## 7. Deploy
+
+- **Vercel:** import the repository; Next.js is detected. Add the variables
+  above for Production (and Preview, with its own database), then deploy.
+  The `build` script migrates the database during the build.
+- **Node.js server:** install from the lockfile (`npm ci`, `pnpm install
+--frozen-lockfile`, `yarn install --immutable` on Yarn 2+, `yarn install --frozen-lockfile` on
+  Yarn 1, or `bun install --frozen-lockfile`), run the `build` script, then `next start` under a
+  process manager such as systemd, pm2 or Docker. Put a reverse proxy in
+  front that terminates TLS and forwards `Host`, `X-Forwarded-Proto` and
+  `X-Forwarded-For`.
+
+### Behind a proxy, including Vercel
+
+Nextly ignores `X-Forwarded-For` unless told to trust it, and then it cannot
+tell clients apart: every sign-in, registration and password-reset request
+shares one rate-limit bucket, 30 an hour by default, and everyone gets 429
+after that. When every request reaches the app through a proxy that sets
+`X-Forwarded-For` (Vercel does; configure nginx or Caddy to), trust it:
+
+```ts
+// nextly.config.ts
+import { defineConfig } from "nextly/config";
+
+export default defineConfig({
+  security: { trustProxy: true },
+  // collections, typescript, ...
+});
+```
+
+When requests pass through more than one proxy, list the proxies' addresses
+in `TRUSTED_PROXY_IPS` (comma-separated CIDRs), so the client is read from the
+right hop. Do not turn this on for an app clients can reach directly: they
+could then pick their own address.
+
+## 8. Check the live site
+
+- `npx nextly migrate:status`, run against the production `DATABASE_URL`,
+  shows nothing pending.
+- `/admin/setup` says setup is already complete, and `/admin` signs in with
+  the account created before the deploy.
+- Publish an entry and open a page that lists it: it appears.
+- Upload an image in the admin, redeploy, and check it still loads.
+- Do not use `/api/health` as an uptime probe on serverless hosts. It reports
+  503 until Nextly has started in that same process, which a fresh instance
+  that only receives probes never does. Probe a page that reads content
+  instead.
+
+## If something fails
+
+- **Tables missing, or `relation "dc_..." does not exist`:** the migrations
+  were not committed, or `nextly migrate` did not run against this database.
+- **The admin and its API answer 500 in production:** check the server log.
+  `NEXTLY_SECRET of at least 32 characters is required` means the secret is
+  missing or too short, and `NEXT_PUBLIC_APP_URL is required` that the URL is
+  not set.
+- **Sign-in fails with `CSRF_FAILED` behind a proxy:** add the public origin
+  to `NEXTLY_ALLOWED_ORIGINS`.
+- **`next build` fails on a page reading content:** in an app with
+  `cacheComponents: true`, wrap the read in `cachedFind` (the
+  `nextly-collections` skill) or render it inside `<Suspense>`.

package/skills/nextly-install/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: nextly-install
+description: >-
+  Use when adding Nextly, the open-source CMS that runs inside a Next.js app,
+  to an existing Next.js App Router project: installing its packages,
+  creating nextly.config.ts, mounting the admin panel at /admin, choosing a
+  database, and creating the first admin account. Also use when an existing
+  Nextly install shows no collections, fails to load nextly.config.ts, or its
+  admin panel misbehaves after setup.
+metadata:
+  nextly-version: 0.0.2-alpha.67
+---
+
+# Install Nextly into an existing Next.js app
+
+Nextly runs inside the app: same server, same database, no separate service.
+The project generator detects an existing Next.js app and installs Nextly into
+it, including the build approvals, `esbuild` and the routes the admin needs.
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4. Run
+`npx nextly --version` after installing; if it prints a newer version, prefer
+<https://nextlyhq.com/docs> where it disagrees with this skill.
+
+## Before you start
+
+- Next.js 14, 15 or 16 with the App Router (`app/` or `src/app/`). On
+  Next.js 14 the generator leaves the Next config alone and prints the
+  `experimental` block to add instead (`serverComponentsExternalPackages` and
+  `instrumentationHook`).
+- Node.js `^20.19.0 || ^22.12.0 || >=24.0.0`. Node 23 is not supported.
+- A clean git working tree, so every change below is visible in one diff.
+
+## 1. Run the generator in the project root
+
+```bash
+npx create-nextly-app@alpha          # npm
+pnpm dlx create-nextly-app@alpha     # pnpm
+yarn dlx create-nextly-app@alpha     # yarn 2 and later
+yarn create nextly-app               # yarn 1 (Classic): no tag; installs `latest`, the current release
+bunx create-nextly-app@alpha         # bun
+```
+
+It finds `next` in `package.json`, asks "Install Nextly in this project?", then
+asks which database and, for PostgreSQL or MySQL, its connection string. `-y`
+skips the questions and uses SQLite at `./data/nextly.db`. `--database
+postgresql` or `--database mysql` picks another; with `-y` as well, `.env` gets
+a placeholder `DATABASE_URL` to replace before starting.
+
+It installs with the app's own package manager (inside a monorepo, the
+workspace's), adding the packages to the app's own `package.json`. On pnpm 10
+and later it approves the native build scripts Nextly needs (`better-sqlite3`,
+`esbuild`, `sharp`) in the setting that pnpm version reads: `pnpm-workspace.yaml`
+from pnpm 10.6, `package.json` before it. In a monorepo the approvals go at the
+workspace root.
+
+Develop on the database you will run in production. Migrations are written in
+the dialect of the database you develop against (the `nextly-deploy` skill),
+and SQLite is not suitable for serverless hosting.
+
+What it changes. It edits `package.json`, the Next config and pnpm's settings
+in place, and adds to `.env` and `.env.example` only the keys they lack. A file
+it would create that the app already has (`nextly.config.ts`,
+`instrumentation.ts`, the admin's files and the routes) is kept as it is and
+reported as skipped, with what Nextly needs in it. Read its report, then review
+the rest in `git diff`:
+
+| File                                           | What                                                                                                                                                 |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `package.json`                                 | `nextly`, `@nextlyhq/admin`, `@nextlyhq/ui`, the database adapter and driver, `@tanstack/react-query`, `lucide-react`; `esbuild` as a dev dependency |
+| `nextly.config.ts`                             | the config the CMS boots from, with empty `collections` and `singles`                                                                                |
+| `next.config.ts`                               | Nextly, the adapter and the driver added to `serverExternalPackages`                                                                                 |
+| `src/instrumentation.ts`                       | starts Nextly when the server starts                                                                                                                 |
+| `src/app/admin/[[...params]]/`                 | the admin panel page and layout                                                                                                                      |
+| `src/app/admin/api/[[...params]]/route.ts`     | the admin API                                                                                                                                        |
+| `src/app/admin/api/media/[[...path]]/route.ts` | the admin's media route, where it uploads and edits media (signed-in only)                                                                           |
+| `src/app/api/media/[[...path]]/route.ts`       | public, read-only media routes                                                                                                                       |
+| `src/app/api/health/route.ts`                  | a health check                                                                                                                                       |
+| `src/types/generated/`                         | where generated types go                                                                                                                             |
+| `.env`, `.env.example`                         | `DB_DIALECT`, `DATABASE_URL`, `NEXTLY_SECRET`, `NEXT_PUBLIC_APP_URL`, for the keys missing                                                           |
+
+Without a `src/` folder the same files go under `app/`, and `instrumentation.ts`
+sits at the project root.
+
+If it reports that it left the Next config alone (a config it cannot change
+safely, or Next.js 14), add what it prints. The list it needs holds `nextly`,
+`@nextlyhq/adapter-drizzle`, `drizzle-orm`, `drizzle-kit`, `bcryptjs`,
+`sharp`, `esbuild`, and your adapter and driver: `@nextlyhq/adapter-sqlite`
+and `better-sqlite3`, `@nextlyhq/adapter-postgres` and `pg`, or
+`@nextlyhq/adapter-mysql` and `mysql2`.
+
+## 2. Start it and create the first admin
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:3000/admin/setup` and create the first account; it gets
+the Super Admin role. Nextly creates its own tables when the server starts,
+from `instrumentation.ts`; without that hook, on the first request. Then sign in
+at `/admin`. Keep to one address for the admin: a form posted from an origin
+other than the one serving the request is refused, unless that origin is listed
+in `NEXTLY_ALLOWED_ORIGINS`.
+
+## Check it worked
+
+- `/admin` shows the dashboard after signing in.
+- `npx nextly --version` prints the installed version.
+- The dev server log has no `esbuild` error, and `/api/health` answers.
+
+## Doing it by hand
+
+If the generator cannot be used, the manual steps are at
+<https://nextlyhq.com/docs/getting-started/installation> (option B). They
+include the pnpm build approvals, `esbuild` and the admin's media route, which
+the generator otherwise adds for you.
+
+## Next
+
+- Define content: the `nextly-collections` skill.
+- Who can sign in and what they can do: the `nextly-authentication` skill.
+- Going live: the `nextly-deploy` skill.
+- Every docs page, for agents: <https://nextlyhq.com/llms.txt>.

package/templates/base/.env.example

@@ -5,9 +5,9 @@
 DB_DIALECT={{databaseDialect}}
 DATABASE_URL={{databaseUrl}}
 
-# Authentication (REQUIRED)
-# Generate with: openssl rand -base64 32
-NEXTLY_SECRET=change-me-generate-a-secure-secret
+# Authentication (REQUIRED): a random secret of at least 32 characters, for
+# example from `openssl rand -base64 32`. The real one goes in .env, never here.
+NEXTLY_SECRET=
 
 # Where the Nextly app itself lives: the admin, the API, and the origin its
 # emails and preview links point at.
@@ -29,5 +29,3 @@ NEXT_PUBLIC_APP_URL=http://localhost:3000
 # file would be true in exactly that case, which is the one it guards against.
 # NEXTLY_DEV_DIAGNOSTICS=1
 
-# Storage Configuration
-{{storageEnvVars}}

package/templates/base/AGENTS.md.template

@@ -84,9 +84,9 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
 
   **`keyParts` is a security boundary, not a performance detail.** Two callers
   whose `keyParts` match share one cache entry. So if the read applies any
-  per-caller rule — owner-only scoping, role-based visibility, an API key's
-  narrowed scope — the caller's identity has to be IN the key, or one user's
-  rows get served to another:
+  per-caller rule — a code-defined `access.read` that reads the caller's
+  roles or permissions, an API key's narrowed scope — the caller's identity
+  has to be IN the key, or one user's rows get served to another:
 
   **A shared cache entry is only safe if the read is public for EVERY reader.**
   Two independent things can make it not so, and each needs its own answer:
@@ -94,16 +94,28 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
   - **drafts** — `find()` defaults to `overrideAccess: true`, a trusted server
     read, so a slug filter alone can return an unpublished row. `status:
     "published"` is enforced even on a trusted read and fixes this one.
-  - **per-row access rules** — owner-only scoping, role-based visibility, an API
-    key's narrowed scope. `status` does NOT evaluate these; it is a
-    draft/published lifecycle filter and nothing more. A published row that only
-    its owner may read is still returned by the query above.
-
-  So the decision is: **does this collection carry read-access rules?**
+  - **access rules** — a code-defined `access.read` on the collection that
+    decides on the caller (their roles, their permissions, whether they are
+    signed in at all), or an API key's narrowed scope. `status` does NOT
+    evaluate these; it is a draft/published lifecycle filter and nothing more.
+    A published row that only some readers may see is still returned by the
+    query above.
+
+  - **field-level read rules** — a field can carry its own `access.read` even
+    when the collection declares none. The shared branch below reads with the
+    Direct API's default `overrideAccess: true`, which bypasses field rules
+    too, so the cached row holds every field and the entry serves fields the
+    schema meant to redact. A collection with ANY field-level read rule takes
+    the per-caller branch — or selects only fields known to be public.
+
+  So the decision is: **does this collection declare a read rule, on the
+  collection or on any of its fields?**
 
   ```ts
-  // NO access rules — the result is identical for every reader, so one shared
-  // entry is correct and gets the full ISR benefit.
+  import { cachedFind, nextlyTags } from "nextly/runtime";
+
+  // NO read rule, on the collection OR its fields — the result is identical for
+  // every reader, so one shared entry is correct and gets the full ISR benefit.
   // `find()` always returns the list envelope `{ items, meta }`, so a detail route takes the
   // first item — and caches THAT, not the envelope around it.
   cachedFind(
@@ -119,8 +131,8 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
     { tags: nextlyTags("posts"), keyParts: ["posts", slug] }
   );
 
-  // ACCESS RULES — evaluate them as the caller, and key by EVERY dimension the
-  // rules read, not just who the caller is.
+  // A READ RULE — evaluate it as the caller, and key by EVERY dimension the
+  // rule reads, not just who the caller is.
   //
   // Both role fields are optional and Nextly reads BOTH: the many-to-many
   // `roles` unioned with the singular `role`. Deduped and sorted, so one role
@@ -144,8 +156,64 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
   on CONTENT changes, and a permission change is not one. Include whatever the
   rules actually read: the role set, the claim, the key's scope.
 
-  If you are unsure whether a collection has read rules, do not cache it. A
-  missing cache is slow; a shared one leaks.
+  If you are unsure whether a collection or any of its fields declares a read
+  rule, do not cache it. A missing cache is slow; a shared one leaks.
+
+## Which Nextly this is, and where its docs are
+
+An agent working here will otherwise answer from whatever it remembers of some
+other version. Ask the project instead:
+
+```bash
+{{execCommand}} nextly --version      # the running core version
+```
+
+That is the same version the plugin resolver validates a plugin's `nextly`
+range against, so a compatibility answer and a reported version cannot
+disagree. The dependency range this project pins is in `package.json` under
+`nextly`; the resolved version is what the command above prints.
+
+**The authoritative documentation is <https://nextlyhq.com/docs>.** Two files
+are published for machine readers and are the ones to fetch:
+
+| file | what it is |
+| ---- | ---------- |
+| <https://nextlyhq.com/llms.txt> | the index — every documentation page, with a one-line summary |
+| <https://nextlyhq.com/llms-full.txt> | the same documentation as one file |
+
+Both are generated from the pages the site publishes, so they cannot describe a
+page that does not exist. Neither is version-stamped: they describe the CURRENT
+release, so check the version above before trusting a detail against an older
+pin.
+
+## Skills for Nextly tasks
+
+If this project has `.agents/skills/`, it holds skills for common Nextly
+tasks, and `.claude/skills/` holds the same files for Claude Code. Load the
+one that matches a task before starting it. They were written for the Nextly
+release this project was created with.
+
+Each skill names the Nextly release it was checked against in its
+frontmatter, as `metadata.nextly-version`. The command below installs skills
+written for `{{skillsVersion}}`. Restore them as they were released only when
+`.agents/skills/nextly-install/SKILL.md` exists, its `metadata.nextly-version`
+is exactly `{{skillsVersion}}`, and `{{execCommand}} nextly --version` prints
+exactly `{{skillsVersion}}`:
+
+```bash
+npx skills add 'nextlyhq/nextly#v{{skillsTag}}' --skill '*' --agent claude-code codex cursor --copy -y
+```
+
+It rewrites both folders, so edits made to a skill there are replaced.
+`{{skillsTag}}` is the release of `create-nextly-app` that made this project,
+whose tag publishes these skills. Releases up to 0.0.2-alpha.66 publish no
+skills for building apps: installing from one of those tags brings the skills
+Nextly's own contributors use, so never put an older version in its place.
+
+Otherwise, with no skills or with skills for a different release than this
+project runs, do not run the command above: it would install skills written
+for another release. See <https://nextlyhq.com/docs/guides/coding-agents> for
+skills that match.
 
 ## Conventions worth keeping
 

package/templates/base/src/types/generated/nextly-types.ts

@@ -1,12 +1,14 @@
 /**
  * Nextly Generated Types
  *
- * This file will be auto-generated when you run:
- *   npx nextly dev
- *   npx nextly generate:types
+ * This file is generated by `nextly generate:types`, which this project runs
+ * as its `types:generate` script. Run it after every change to the schema in
+ * nextly.config.ts. It reads only that file, so collections built in the
+ * Schema Builder get types once they are moved into code
+ * (`nextly db:sync --promote <slug>`).
  *
  * Do not edit this file manually - it will be overwritten.
  */
 
-// Types will be generated here after running nextly dev
+// Types are generated here by `nextly generate:types`.
 export {};

package/templates/blank/src/app/(frontend)/components/ThemeToggle.tsx

@@ -1,36 +1,67 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useSyncExternalStore } from "react";
 
 type Theme = "light" | "dark" | "system";
 
-export function ThemeToggle() {
-  const [theme, setTheme] = useState<Theme>("system");
-
-  useEffect(() => {
-    const savedTheme = localStorage.getItem("theme") as Theme | null;
-    if (savedTheme) {
-      setTheme(savedTheme);
-      applyTheme(savedTheme);
-    } else {
-      applyTheme("system");
-    }
-  }, []);
+const STORAGE_KEY = "theme";
+const THEMES: readonly Theme[] = ["light", "dark", "system"];
+const DARK_QUERY = "(prefers-color-scheme: dark)";
 
-  const applyTheme = (newTheme: Theme) => {
-    const isDark =
-      newTheme === "dark" ||
-      (newTheme === "system" &&
-        window.matchMedia("(prefers-color-scheme: dark)").matches);
+/**
+ * Everything showing the theme in this tab. The browser's `storage` event
+ * only reaches other tabs, so a change made here is announced here by hand.
+ */
+const listeners = new Set<() => void>();
 
-    document.documentElement.classList.toggle("dark", isDark);
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  window.addEventListener("storage", listener);
+  return () => {
+    listeners.delete(listener);
+    window.removeEventListener("storage", listener);
   };
+}
 
-  const handleThemeChange = (newTheme: Theme) => {
-    setTheme(newTheme);
-    localStorage.setItem("theme", newTheme);
-    applyTheme(newTheme);
-  };
+/** The saved choice, or "system" when there is none or it is not one of the three. */
+function readTheme(): Theme {
+  const saved = localStorage.getItem(STORAGE_KEY);
+  return THEMES.find(theme => theme === saved) ?? "system";
+}
+
+function saveTheme(theme: Theme) {
+  localStorage.setItem(STORAGE_KEY, theme);
+  for (const listener of listeners) listener();
+}
+
+function applyTheme(theme: Theme) {
+  const isDark =
+    theme === "dark" ||
+    (theme === "system" && window.matchMedia(DARK_QUERY).matches);
+  document.documentElement.classList.toggle("dark", isDark);
+}
+
+export function ThemeToggle() {
+  // Read from storage rather than copied into state by an effect. The server
+  // renders "system"; after hydration React swaps in the saved choice.
+  const theme = useSyncExternalStore<Theme>(
+    subscribe,
+    readTheme,
+    () => "system"
+  );
+
+  // Keep the page's colours in step with the choice, and with the system's
+  // setting for as long as "system" is the choice.
+  useEffect(() => {
+    applyTheme(theme);
+    if (theme !== "system") return;
+    const query = window.matchMedia(DARK_QUERY);
+    const follow = () => applyTheme("system");
+    query.addEventListener("change", follow);
+    return () => query.removeEventListener("change", follow);
+  }, [theme]);
+
+  const handleThemeChange = (newTheme: Theme) => saveTheme(newTheme);
 
   return (
     <div className="fixed top-6 right-6 flex items-center border border-foreground/10 bg-background p-1 z-50">

package/templates/blank/src/instrumentation.ts

@@ -0,0 +1,27 @@
+/**
+ * Starts Nextly when the server starts, before it serves a request.
+ *
+ * Next.js runs `register()` once per server instance and finishes it before
+ * the instance handles traffic, in every serverless function as well as the
+ * admin's. Without it, Nextly starts on the first request that happens to
+ * need it, so a route that cannot start it alone, such as `/api/health`,
+ * answers as if the server could not serve until some other request has.
+ *
+ * It also registers Nextly's Next.js cache adapter here, so a Direct API write
+ * from any function flushes the cache tags it touches.
+ *
+ * Guarded to the Node.js runtime and imported dynamically inside the guard:
+ * Nextly needs Node-only packages that the Edge runtime cannot bundle. Next.js
+ * skips `register()` during `next build`, so this never opens a database
+ * connection at build time.
+ */
+export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+
+  const { registerNextCacheRevalidator } = await import("nextly/runtime");
+  registerNextCacheRevalidator();
+
+  const { createRegister } = await import("nextly");
+  const { default: config } = await import("../nextly.config");
+  await createRegister(config)();
+}