create-nextly-app 0.0.2-alpha.66 → 0.0.2-alpha.68

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

@@ -112,6 +112,8 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
   collection or on any of its fields?**
 
   ```ts
+  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
@@ -184,6 +186,35 @@ 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
 
 - Server components read content directly; do not build an API route to fetch

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)();
+}

package/templates/plugin/AGENTS.md.template

@@ -40,10 +40,10 @@ working on an app.
 
 - **Plugin APIs come from `@nextlyhq/plugin-sdk`; schema APIs come from
   `nextly/config`.** The SDK is the stability boundary for everything a plugin
-  does AS a plugin: `definePlugin`, `registerComponents` and
-  `registerKnownPlugin` from `@nextlyhq/plugin-sdk/admin`, `createTestNextly`
-  from `@nextlyhq/plugin-sdk/testing`, field factories, `pluginField`,
-  `NextlyError`. Collections and singles are defined the same way an app defines
+  does AS a plugin: `definePlugin`, field factories, `pluginField` and
+  `NextlyError` from `@nextlyhq/plugin-sdk`; `registerComponents` and
+  `registerKnownPlugin` from `@nextlyhq/plugin-sdk/admin`; `createTestNextly`
+  from `@nextlyhq/plugin-sdk/testing`. Collections and singles are defined the same way an app defines
   them, with `defineCollection` from `nextly/config` — which is what
   `src/collections/example.ts` does.
 
@@ -73,6 +73,8 @@ in-memory SQLite with your plugin registered, so a test exercises the same
 lifecycle a host would run:
 
 ```ts
+import { createTestNextly } from "@nextlyhq/plugin-sdk/testing";
+
 const t = await createTestNextly({ plugins: [myPlugin()] });
 ```
 

package/templates/plugin/README.md

@@ -13,6 +13,10 @@ Your plugin lives in `src/`. The `dev/` folder is a minimal Nextly app on SQLite
 that registers this plugin so you can exercise it in a real admin with hot-reload.
 Editing files under `src/` reloads the playground. **`dev/` is never published.**
 
+The playground signs you in automatically as `dev@nextly.local` (password
+`DevPassword123!`). That user is created on the first `pnpm dev`, and only
+under `next dev`; production builds ignore the auto-login setting.
+
 ## Test
 
 ```bash

package/templates/plugin/dev/.env.example

@@ -1,6 +1,9 @@
-# Dev playground env. Copy to dev/.env and run `pnpm dev`.
+# Dev playground env. create-nextly-app writes dev/.env from this file;
+# copy it again to start over.
 DB_DIALECT=sqlite
-DATABASE_URL=file:./nextly-dev.db
+# Relative to the plugin root, where `pnpm dev` runs (`next dev dev` keeps
+# that working directory), so the database lands in dev/.
+DATABASE_URL=file:./dev/nextly-dev.db
 
 # Any non-empty secret works for local dev (sign/verify session cookies).
 NEXTLY_SECRET=dev-secret-change-me

package/templates/plugin/dev/src/app/admin/[[...params]]/page.tsx

@@ -1,9 +1,21 @@
 "use client";
 
 import "@nextlyhq/admin/style.css";
-import { RootLayout } from "@nextlyhq/admin";
+import { ErrorBoundary, QueryProvider, RootLayout } from "@nextlyhq/admin";
 
 // Mounts the Nextly admin shell. Your plugin's menu/pages/settings appear here.
+// The admin's data hooks read their client from QueryProvider, so RootLayout
+// renders only inside it, as in an app scaffold.
 export default function AdminPage() {
-  return <RootLayout />;
+  return (
+    <ErrorBoundary
+      onError={(error, errorInfo) => {
+        console.error("Admin error:", error, errorInfo);
+      }}
+    >
+      <QueryProvider>
+        <RootLayout />
+      </QueryProvider>
+    </ErrorBoundary>
+  );
 }