create-nextly-app 0.0.2-alpha.72 → 0.0.2-alpha.74

package/dist/index.cjs

@@ -1,3 +1,3 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_nextly = require("./create-nextly-BGu1tXYs.cjs");
+const require_create_nextly = require("./create-nextly-Decg8dye.cjs");
 exports.createNextly = require_create_nextly.createNextly;

package/dist/index.mjs

@@ -1 +1 @@
-export { t as createNextly } from "./create-nextly-CyI8XgVc.mjs";
+export { t as createNextly } from "./create-nextly-ChHdzG83.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nextly-app",
-  "version": "0.0.2-alpha.72",
+  "version": "0.0.2-alpha.74",
   "description": "CLI to scaffold Nextly in your Next.js project",
   "license": "MIT",
   "type": "module",
@@ -37,10 +37,10 @@
   },
   "devDependencies": {
     "@babel/types": "^7.29.7",
-    "@nextlyhq/eslint-plugin": "0.0.2-alpha.72",
-    "@nextlyhq/module-specifiers": "0.0.2-alpha.72",
-    "@nextlyhq/telemetry": "0.0.2-alpha.72",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.72",
+    "@nextlyhq/eslint-plugin": "0.0.2-alpha.74",
+    "@nextlyhq/module-specifiers": "0.0.2-alpha.74",
+    "@nextlyhq/telemetry": "0.0.2-alpha.74",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.74",
     "@testing-library/react": "^16.3.0",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^22.20.5",

package/skills/nextly-authentication/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   code, and extra fields on users. Also use when asked to add login or
   sign-up to a Nextly site, so the answer matches what Nextly provides.
 metadata:
-  nextly-version: 0.0.2-alpha.72
+  nextly-version: 0.0.2-alpha.74
 ---
 
 # Authentication and access in Nextly

package/skills/nextly-collections/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   not appear in the admin, a field change does not reach the database, or a
   page reading content fails to build.
 metadata:
-  nextly-version: 0.0.2-alpha.72
+  nextly-version: 0.0.2-alpha.74
 ---
 
 # Define a collection in Nextly
@@ -176,9 +176,15 @@ export default async function PostsPage() {
 - `status: "published"` keeps drafts off the page. Without it a trusted
   server read returns drafts too.
 - `cachedFind` with `nextlyTags("posts")` caches the result and clears it when
-  a post is saved, so the page updates on publish. It also lets the page build
-  in an app with `cacheComponents: true`, where an uncached database read
-  outside `<Suspense>` fails `next build`.
+  a post is saved, so the page updates on publish. It also lets the page
+  build: a Nextly app runs with `cacheComponents: true`, where an uncached
+  database read outside `<Suspense>` fails `next build`. There the read goes
+  through the app's own `"use cache"` function, `src/nextly/cached-read.ts`
+  (`nextly/cached-read.ts` without a `src/` folder): import it in the module
+  that reads, `import "@/nextly/cached-read";` with `src/`, or by a relative
+  path without one. A blog ships it; for another app, copy it from the caching
+  guide
+  (<https://nextlyhq.com/docs/guides/isr-caching#cache-components>).
 - `keyParts` names the cache entry, and everyone whose read uses the same key
   gets the same rows. Cache only reads that are the same for every reader:
   published content of a collection with no read rule, on the collection or

package/skills/nextly-deploy/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   Also use when a deployed Nextly app has missing tables, refuses to start,
   or loses uploaded files.
 metadata:
-  nextly-version: 0.0.2-alpha.72
+  nextly-version: 0.0.2-alpha.74
 ---
 
 # Deploy a Nextly project
@@ -244,5 +244,7 @@ could then pick their own address.
 - **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>`.
+  `cacheComponents: true`, the Nextly default, wrap the read in `cachedFind`
+  (the `nextly-collections` skill) or render it inside `<Suspense>`. An app
+  made by an earlier release may have it off: check `next.config` first, and
+  turn it on as the installation guide describes.

package/skills/nextly-install/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   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.72
+  nextly-version: 0.0.2-alpha.74
 ---
 
 # Install Nextly into an existing Next.js app
@@ -23,9 +23,10 @@ Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4. Run
 
 ## Before you start
 
-- Next.js 16.4.1 or later, or 15.5.28 or later on the 15 line, with the App
-  Router (`app/` or `src/app/`). Earlier versions carry the October 2026
-  security advisories these releases fix.
+- Next.js `^16.4.1` and React `^19.3.0` (16.4.1 or later within 16.x, 19.3.0
+  or later within 19.x), with the App Router (`app/` or `src/app/`). The
+  [supported versions](https://nextlyhq.com/docs/getting-started/installation#requirements)
+  are kept current there.
 - Node.js `^22.12.0 || >=24.0.0`. Node 20 and Node 23 are not supported.
 - A clean git working tree, so every change below is visible in one diff.
 

package/templates/base/src/app/admin/[[...params]]/layout.tsx

@@ -1,6 +1,10 @@
+import { connection } from "next/server";
+import { Suspense } from "react";
 import { getBrandingCss } from "nextly/config";
+import { checkAdminComponents } from "nextly/runtime";
 
 import config from "../../../../nextly.config";
+import { registeredComponentPaths } from "../../../types/generated/plugin-admin-components.generated";
 
 const brandingCss = getBrandingCss(config.admin?.branding);
 
@@ -14,7 +18,25 @@ export default function AdminLayout({
       {brandingCss && (
         <style dangerouslySetInnerHTML={{ __html: brandingCss }} />
       )}
-      {children}
+      <Suspense fallback={null}>
+        <ForThisRequest>{children}</ForThisRequest>
+      </Suspense>
     </>
   );
 }
+
+/**
+ * The admin renders for each request, never from a cache another user's
+ * request filled. Beneath the layout's Suspense boundary, so under Cache
+ * Components the shell above it still prerenders: request work outside a
+ * boundary fails the build, in development too, where `checkAdminComponents`
+ * boots nextly.
+ */
+async function ForThisRequest({ children }: { children: React.ReactNode }) {
+  await connection();
+  // In development, the generated component map is written again when it
+  // falls behind the config, so a plugin added while `next dev` runs draws
+  // its components without a command. In production it does nothing.
+  await checkAdminComponents({ config, registeredComponentPaths });
+  return children;
+}

package/templates/base/src/app/globals.css

@@ -47,8 +47,19 @@ body {
 
 /* Visible focus ring for keyboard users. `:focus-visible` only fires
    on keyboard / programmatic focus, so clicking a button doesn't
-   show the ring but tabbing to it does. */
-*:focus-visible {
+   show the ring but tabbing to it does.
+
+   Weighed as two element names, the pseudo-class inside `:where()` counting
+   for nothing. That is enough to keep the ring over a reset added later, such
+   as `button { outline: none }`, and on this site's pages it draws as
+   `*:focus-visible` did, since no other rule here sets these properties on a
+   focused element. The admin at /admin renders in this same document and
+   reverts a site's rules made of element names only; with the pseudo-class
+   counted, this rule would outweigh that and redraw every focused control in
+   the admin with this ring and corner. The trade: a class-based reset, such as
+   `.btn { outline: none }`, outweighs this ring wherever it is written; give
+   such a rule a `:focus-visible` style of its own. */
+html body :where(:focus-visible) {
   outline: 2px solid currentColor;
   outline-offset: 2px;
   border-radius: 2px;

package/templates/base/src/app/layout.tsx

@@ -3,6 +3,11 @@ import "@fontsource-variable/geist";
 import "@fontsource-variable/geist-mono";
 import "./globals.css";
 import { SITE_URL } from "@/lib/site-url";
+// Registers the app's "use cache" read function, and how Nextly starts when a
+// read finds it not started, for every route before any of them reads,
+// during `next build` too: under Cache Components Nextly's cached reads go
+// through that function, and `<SiteCode>` refuses to read without it.
+import "@/nextly/cached-read";
 
 /**
  * The faces are imported as STYLESHEETS from packages in `node_modules`, rather

package/templates/base/src/nextly/cached-read.ts

@@ -0,0 +1,52 @@
+/**
+ * Nextly's cached reads under Cache Components.
+ *
+ * Next.js caches non-fetch reads with `"use cache"` and `cacheTag` once Cache
+ * Components is on, and the directive works only in code Next.js compiles, so
+ * Nextly reads through this function of the app's own. It receives the read's
+ * key, its tags and its lifetime, and runs the reader Nextly registered for
+ * that key. The root layout imports this file, so it is registered on every
+ * route before anything is read: `<SiteCode>` refuses to read without it.
+ *
+ * The same import also tells Nextly how to start with the app's config when a
+ * read finds it not started, so the root layout's import both registers the
+ * cached read and covers a read made before any page starts Nextly, during
+ * `next build` too.
+ *
+ * It works with `cacheComponents: true` and Nextly's cache handlers in
+ * `next.config.ts`, as this app ships:
+ * https://nextlyhq.com/docs/guides/isr-caching#cache-components
+ */
+import { cacheLife, cacheTag } from "next/cache";
+import { getNextly, registerNextlyStart } from "nextly";
+import { registerCachedRead, runRegisteredRead } from "nextly/runtime";
+
+import config from "@nextly-config";
+
+export async function cachedRead(
+  key: string,
+  tags: string[],
+  revalidate: number | false
+): Promise<unknown> {
+  "use cache";
+  cacheTag(...tags);
+  // `revalidate: false` is tag-only, as everywhere in Nextly: only a write
+  // expires the entry, never time. Next.js's "max" profile revalidates monthly.
+  if (revalidate === false) {
+    cacheLife({ revalidate: Infinity, expire: Infinity });
+  } else {
+    // Expired at twice the revalidate, and never within 5 minutes: Next.js
+    // leaves an entry that expires sooner out of a static prerender.
+    cacheLife({ revalidate, expire: Math.max(revalidate * 2, 300) });
+  }
+  return runRegisteredRead(key);
+}
+
+registerCachedRead(cachedRead, process.env.__NEXT_CACHE_COMPONENTS);
+
+// Tells Nextly how this app starts it, for a read that finds it not started,
+// such as the root layout's `<SiteCode>` on `/_not-found` while `next build`
+// prerenders, where nothing else starts it. Nothing starts here: a page that
+// calls `getNextly` first is the start that counts. An app that passes
+// `getNextly` more than its config passes the same options here.
+registerNextlyStart(() => getNextly({ config }));

package/templates/blank/src/app/(frontend)/page.tsx

@@ -1,4 +1,5 @@
 import Link from "next/link";
+import { Suspense } from "react";
 
 import { ThemeToggle } from "@/components/ThemeToggle";
 import { SITE_URL } from "@/lib/site-url";
@@ -12,6 +13,10 @@ import { SITE_URL } from "@/lib/site-url";
  * primary button label flips between "Set up admin" (no super-admin
  * yet) and "Open admin" (super-admin exists).
  *
+ * The app runs with Cache Components on, so the page is prerendered as a
+ * static shell and the setup-status read, made per request, sits inside a
+ * `<Suspense>` boundary: the shell shows "Open admin" until it resolves.
+ *
  * If the auth API fails for any reason (DB not migrated, network),
  * the button defaults to "Open admin" / /admin since /admin already
  * redirects to /admin/setup when no super-admin exists — the link
@@ -37,12 +42,42 @@ async function fetchSetupStatus(): Promise<SetupStatus | null> {
   }
 }
 
-export default async function HomePage() {
+/** The primary button, linking to the admin with the label and target it needs. */
+function AdminButton({ label, href }: { label: string; href: string }) {
+  return (
+    <Link href={href} className="btn-primary">
+      <span>{label}</span>
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="18"
+        height="18"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        className="lucide lucide-arrow-right"
+      >
+        <path d="M5 12h14" />
+        <path d="m12 5 7 7-7 7" />
+      </svg>
+    </Link>
+  );
+}
+
+/** The button once setup-status answers: "Set up admin" while there is no super-admin. */
+async function SetupAwareAdminButton() {
   const status = await fetchSetupStatus();
   const needsSetup = status?.requiresInitialUser ?? false;
-  const adminLabel = needsSetup ? "Set up admin" : "Open admin";
-  const adminHref = needsSetup ? "/admin/setup" : "/admin";
+  return needsSetup ? (
+    <AdminButton label="Set up admin" href="/admin/setup" />
+  ) : (
+    <AdminButton label="Open admin" href="/admin" />
+  );
+}
 
+export default function HomePage() {
   return (
     <main className="relative min-h-screen flex flex-col items-center justify-center p-6 bg-background text-foreground font-display selection:bg-foreground/10">
       <ThemeToggle />
@@ -85,24 +120,11 @@ export default async function HomePage() {
         </p>
 
         <div className="mt-10 flex flex-wrap items-center justify-center gap-4">
-          <Link href={adminHref} className="btn-primary">
-            <span>{adminLabel}</span>
-            <svg
-              xmlns="http://www.w3.org/2000/svg"
-              width="18"
-              height="18"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth="2"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              className="lucide lucide-arrow-right"
-            >
-              <path d="M5 12h14" />
-              <path d="m12 5 7 7-7 7" />
-            </svg>
-          </Link>
+          {/* "/admin" redirects to setup while there is no super-admin, so the
+              fallback link works before the read answers. */}
+          <Suspense fallback={<AdminButton label="Open admin" href="/admin" />}>
+            <SetupAwareAdminButton />
+          </Suspense>
           <Link href="https://nextlyhq.com/docs" className="btn-secondary">
             <span>Read documentation</span>
             <svg

package/templates/blank/src/app/layout.tsx

@@ -4,6 +4,11 @@ import "@fontsource-variable/jetbrains-mono";
 
 import "./globals.css";
 import { SITE_URL } from "@/lib/site-url";
+// Registers the app's "use cache" read function, and how Nextly starts when a
+// read finds it not started, for every route before any of them reads,
+// during `next build` too: under Cache Components Nextly's cached reads go
+// through that function, and `<SiteCode>` refuses to read without it.
+import "@/nextly/cached-read";
 
 /**
  * The faces are imported as STYLESHEETS from packages in `node_modules`, rather

package/templates/blank/src/instrumentation.ts

@@ -24,8 +24,9 @@ export async function register(): Promise<void> {
   const { createRegister } = await import("nextly");
   const { default: config } = await import("../nextly.config");
   // Next.js writes its Cache Components setting into this file as it builds
-  // it. Nextly, loaded from node_modules, cannot read that for itself, and
-  // warns when Cache Components is on, which it does not support yet.
+  // it. Nextly, loaded from node_modules, cannot read that for itself. With
+  // it off, Nextly warns at start; with it on, a cached read that finds no
+  // "use cache" read function says so.
   await createRegister(config, {
     cacheComponents: process.env.__NEXT_CACHE_COMPONENTS,
   })();

package/templates/plugin/dev/next.config.ts

@@ -6,8 +6,14 @@ import type { NextConfig } from "next";
 // external (Turbopack can't bundle them).
 const nextConfig: NextConfig = {
   typescript: { ignoreBuildErrors: true },
-  // Nextly does not support Cache Components yet; see the installation guide.
-  cacheComponents: false,
+  // Nextly runs with Cache Components and Partial Prefetching on. Its cache
+  // handlers make the first read after a write show the new version:
+  // https://nextlyhq.com/docs/getting-started/installation#cache-components
+  cacheComponents: true,
+  partialPrefetching: true,
+  cacheHandler: require.resolve("nextly/cache-handler"),
+  cacheMaxMemorySize: 0,
+  cacheHandlers: { default: require.resolve("nextly/cache-handlers") },
   // Transpile the aliased plugin source so HMR fires on src/ edits.
   transpilePackages: ["{{pluginName}}"],
   serverExternalPackages: [

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

@@ -0,0 +1,24 @@
+import { connection } from "next/server";
+import { Suspense } from "react";
+
+export default function AdminLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <Suspense fallback={null}>
+      <ForThisRequest>{children}</ForThisRequest>
+    </Suspense>
+  );
+}
+
+/**
+ * The admin renders for each request, never from a cache another user's
+ * request filled. Beneath the layout's Suspense boundary, so under Cache
+ * Components the rest of the page still prerenders.
+ */
+async function ForThisRequest({ children }: { children: React.ReactNode }) {
+  await connection();
+  return children;
+}

package/templates/plugin/dev/src/app/layout.tsx

@@ -1,5 +1,11 @@
 import type { ReactNode } from "react";
 
+// Registers the dev app's "use cache" read function, and how Nextly starts
+// when a read finds it not started, for every route before any of them
+// reads, during `next build` too: under Cache Components Nextly's cached
+// reads go through that function, and `<SiteCode>` refuses to read without it.
+import "../nextly/cached-read";
+
 export const metadata = {
   title: "{{pluginName}} — dev playground",
 };

package/templates/plugin/dev/src/instrumentation.ts

@@ -8,8 +8,9 @@ export async function register(): Promise<void> {
   const { createRegister, getService } = await import("nextly");
   const { default: config } = await import("../nextly.config");
   // Next.js writes its Cache Components setting into this file as it builds
-  // it. Nextly, loaded from node_modules, cannot read that for itself, and
-  // warns when Cache Components is on, which it does not support yet.
+  // it. Nextly, loaded from node_modules, cannot read that for itself. With
+  // it off, Nextly warns at start; with it on, a cached read that finds no
+  // "use cache" read function says so.
   await createRegister(config, {
     cacheComponents: process.env.__NEXT_CACHE_COMPONENTS,
   })();

package/templates/plugin/dev/src/nextly/cached-read.ts

@@ -0,0 +1,52 @@
+/**
+ * Nextly's cached reads under Cache Components, for the plugin's dev app.
+ *
+ * Next.js caches non-fetch reads with `"use cache"` and `cacheTag` once Cache
+ * Components is on, and the directive works only in code Next.js compiles, so
+ * Nextly reads through this function of the app's own. It receives the read's
+ * key, its tags and its lifetime, and runs the reader Nextly registered for
+ * that key. The root layout imports this file, so it is registered on every
+ * route before anything is read, as in an app `create-nextly-app` makes.
+ *
+ * The same import also tells Nextly how to start with the app's config when a
+ * read finds it not started, so the root layout's import both registers the
+ * cached read and covers a read made before any page starts Nextly, during
+ * `next build` too.
+ *
+ * It works with `cacheComponents: true` and Nextly's cache handlers in
+ * `next.config.ts`, as this dev app ships:
+ * https://nextlyhq.com/docs/guides/isr-caching#cache-components
+ */
+import { cacheLife, cacheTag } from "next/cache";
+import { getNextly, registerNextlyStart } from "nextly";
+import { registerCachedRead, runRegisteredRead } from "nextly/runtime";
+
+import config from "../../nextly.config";
+
+export async function cachedRead(
+  key: string,
+  tags: string[],
+  revalidate: number | false
+): Promise<unknown> {
+  "use cache";
+  cacheTag(...tags);
+  // `revalidate: false` is tag-only, as everywhere in Nextly: only a write
+  // expires the entry, never time. Next.js's "max" profile revalidates monthly.
+  if (revalidate === false) {
+    cacheLife({ revalidate: Infinity, expire: Infinity });
+  } else {
+    // Expired at twice the revalidate, and never within 5 minutes: Next.js
+    // leaves an entry that expires sooner out of a static prerender.
+    cacheLife({ revalidate, expire: Math.max(revalidate * 2, 300) });
+  }
+  return runRegisteredRead(key);
+}
+
+registerCachedRead(cachedRead, process.env.__NEXT_CACHE_COMPONENTS);
+
+// Tells Nextly how this app starts it, for a read that finds it not started,
+// such as the root layout's `<SiteCode>` on `/_not-found` while `next build`
+// prerenders, where nothing else starts it. Nothing starts here: a page that
+// calls `getNextly` first is the start that counts. An app that passes
+// `getNextly` more than its config passes the same options here.
+registerNextlyStart(() => getNextly({ config }));