create-nextly-app 0.0.2-alpha.71 → 0.0.2-alpha.73

package/dist/index.cjs

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

package/dist/index.mjs

@@ -1 +1 @@
-export { t as createNextly } from "./create-nextly-5wiGMVI6.mjs";
+export { t as createNextly } from "./create-nextly-CuWn_ITx.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nextly-app",
-  "version": "0.0.2-alpha.71",
+  "version": "0.0.2-alpha.73",
   "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.71",
-    "@nextlyhq/module-specifiers": "0.0.2-alpha.71",
-    "@nextlyhq/telemetry": "0.0.2-alpha.71",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.71",
+    "@nextlyhq/eslint-plugin": "0.0.2-alpha.73",
+    "@nextlyhq/module-specifiers": "0.0.2-alpha.73",
+    "@nextlyhq/telemetry": "0.0.2-alpha.73",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.73",
     "@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.71
+  nextly-version: 0.0.2-alpha.73
 ---
 
 # Authentication and access in Nextly
@@ -150,10 +150,10 @@ export async function GET(request: Request) {
 
 - The route must live under `/admin`, or the browser never sends the session
   cookie to it.
-- `session.user.roleIds` holds role **IDs**, not role slugs, so
-  `hasRole(user, "editor")` from `nextly/auth` does not match by slug in this
-  release. Use `isSuperAdmin(user.id)`, or put role decisions in collection
-  access rules, where `roles` are slugs.
+- `session.user.roleIds` holds role **IDs**, not role slugs, and `nextly/auth`
+  has no role checks. Use `isSuperAdmin(user.id)`, check a permission with
+  `nextly.access.check`, or put role decisions in collection access rules,
+  where `roles` are slugs.
 
 ## Extra fields on users
 

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.71
+  nextly-version: 0.0.2-alpha.73
 ---
 
 # 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.71
+  nextly-version: 0.0.2-alpha.73
 ---
 
 # 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.71
+  nextly-version: 0.0.2-alpha.73
 ---
 
 # 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,3 +1,5 @@
+import { connection } from "next/server";
+import { Suspense } from "react";
 import { getBrandingCss } from "nextly/config";
 
 import config from "../../../../nextly.config";
@@ -14,7 +16,19 @@ 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.
+ */
+async function ForThisRequest({ children }: { children: React.ReactNode }) {
+  await connection();
+  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/uploads/[...path]/route.ts

@@ -0,0 +1,21 @@
+/**
+ * Local uploads, served at the URLs Nextly gives them.
+ *
+ * Nextly's default storage writes uploads to `public/uploads` and links them
+ * as `/uploads/...`. `next start` serves only the files `public/` held when
+ * it started, so without this route a file uploaded since answers 404 until
+ * the server restarts. Next.js serves the files it has first; this answers
+ * the rest, at the same URLs, and answers 404 when media is kept in cloud
+ * storage instead.
+ *
+ * If you set `baseUrl` on local storage, move this folder to match it.
+ */
+
+import { createUploadsHandlers } from "nextly/api/uploads";
+
+import config from "@nextly-config";
+
+const handlers = createUploadsHandlers({ config });
+
+export const GET = handlers.GET;
+export const HEAD = handlers.HEAD;

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