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

package/dist/index.cjs

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

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nextly-app",
-  "version": "0.0.2-alpha.73",
+  "version": "0.0.2-alpha.75",
   "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.73",
-    "@nextlyhq/module-specifiers": "0.0.2-alpha.73",
-    "@nextlyhq/telemetry": "0.0.2-alpha.73",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.73",
+    "@nextlyhq/eslint-plugin": "0.0.2-alpha.75",
+    "@nextlyhq/module-specifiers": "0.0.2-alpha.75",
+    "@nextlyhq/telemetry": "0.0.2-alpha.75",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.75",
     "@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.73
+  nextly-version: 0.0.2-alpha.75
 ---
 
 # 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.73
+  nextly-version: 0.0.2-alpha.75
 ---
 
 # Define a collection in Nextly

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.73
+  nextly-version: 0.0.2-alpha.75
 ---
 
 # Deploy a Nextly project

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.73
+  nextly-version: 0.0.2-alpha.75
 ---
 
 # Install Nextly into an existing Next.js app

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

@@ -1,11 +1,43 @@
 import { connection } from "next/server";
 import { Suspense } from "react";
-import { getBrandingCss } from "nextly/config";
+import {
+  ADMIN_BRANDING_ELEMENT_ID,
+  adminBrandingJson,
+  adminMetadataFor,
+  getBrandingCss,
+} from "nextly/config";
 
 import config from "../../../../nextly.config";
+import { registeredComponentPaths } from "../../../types/generated/plugin-admin-components.generated";
 
 const brandingCss = getBrandingCss(config.admin?.branding);
+// The configured logo, name and favicon, read by the admin before any request
+// answers, so they are right from the first paint.
+const brandingJson = adminBrandingJson(config.admin?.branding);
 
+/**
+ * The admin is never a page for search results: `noindex, nofollow` in the
+ * head of the first HTML the server sends, whatever plugins the site runs,
+ * and the configured favicon's link beside it.
+ */
+export const metadata = adminMetadataFor(config.admin?.branding);
+
+/**
+ * `/admin` itself is built ahead, so it is served from the build's files. The
+ * admin's other paths are drawn by the same page in the browser, and are
+ * served the same prebuilt shell.
+ */
+export function generateStaticParams(): { params: string[] }[] {
+  return [{ params: [] }];
+}
+
+/**
+ * Prebuilt in production: the same page for every visitor, built once, with
+ * no request-time work and nothing read from the database. Everything about
+ * the person comes from the admin's own requests once it loads, so a CDN or
+ * the browser may keep the page, and it is served while the server is still
+ * starting.
+ */
 export default function AdminLayout({
   children,
 }: {
@@ -16,19 +48,39 @@ export default function AdminLayout({
       {brandingCss && (
         <style dangerouslySetInnerHTML={{ __html: brandingCss }} />
       )}
-      <Suspense fallback={null}>
-        <ForThisRequest>{children}</ForThisRequest>
-      </Suspense>
+      {brandingJson && (
+        <script
+          type="application/json"
+          id={ADMIN_BRANDING_ELEMENT_ID}
+          dangerouslySetInnerHTML={{ __html: brandingJson }}
+        />
+      )}
+      {process.env.NODE_ENV === "development" ? (
+        <Suspense fallback={null}>
+          <ComponentMapKeptCurrent>{children}</ComponentMapKeptCurrent>
+        </Suspense>
+      ) : (
+        children
+      )}
     </>
   );
 }
 
 /**
- * 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.
+ * Development only: before any admin page, the generated component map is
+ * written again when it falls behind the config. A production build serves
+ * the map it was built with, so it drops this, and the page with it is
+ * prebuilt. Beneath a Suspense boundary, as request work outside one fails a
+ * Cache Components build, in development too. The check is loaded here, so a
+ * production page never loads the runtime it lives in.
  */
-async function ForThisRequest({ children }: { children: React.ReactNode }) {
+async function ComponentMapKeptCurrent({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
   await connection();
+  const { checkAdminComponents } = await import("nextly/runtime");
+  await checkAdminComponents({ config, registeredComponentPaths });
   return children;
 }

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/base/src/types/generated/plugin-admin-imports.generated.ts

@@ -3,6 +3,7 @@
  * string (pages, settings, views, slots, field-type editors) so they load
  * without manual host imports. */
 
+import { registerComponentMap } from "@nextlyhq/admin";
 import { registeredComponentPaths as listed } from "./plugin-admin-components.generated";
 
 const registered = {};
@@ -29,4 +30,5 @@ if (
   );
 }
 
+registerComponentMap(registered);
 export const registeredComponentPaths = listed;

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

@@ -26,8 +26,11 @@ export async function register(): Promise<void> {
   // Next.js writes its Cache Components setting into this file as it builds
   // 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.
+  // "use cache" read function says so. The same holds for the build's newest
+  // migration, which withNextly sets: a production start compares it with
+  // the database's schema version and warns when the database is behind.
   await createRegister(config, {
     cacheComponents: process.env.__NEXT_CACHE_COMPONENTS,
+    buildSchemaVersion: process.env.NEXTLY_BUILD_SCHEMA_VERSION,
   })();
 }

package/templates/plugin/AGENTS.md.template

@@ -41,8 +41,8 @@ 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`, field factories, `pluginField` and
-  `NextlyError` from `@nextlyhq/plugin-sdk`; `registerComponents` and
-  `registerKnownPlugin` from `@nextlyhq/plugin-sdk/admin`; `createTestNextly`
+  `NextlyError` from `@nextlyhq/plugin-sdk`; `registerComponents` 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.

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

@@ -10,9 +10,12 @@ export async function register(): Promise<void> {
   // Next.js writes its Cache Components setting into this file as it builds
   // 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.
+  // "use cache" read function says so. The same holds for the build's newest
+  // migration, which withNextly sets: a production start compares it with
+  // the database's schema version and warns when the database is behind.
   await createRegister(config, {
     cacheComponents: process.env.__NEXT_CACHE_COMPONENTS,
+    buildSchemaVersion: process.env.NEXTLY_BUILD_SCHEMA_VERSION,
   })();
 
   // Create the user admin.devAutoLogin signs in as (see seed-dev-user.ts).

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

package/templates/plugin/dev/src/types/generated/plugin-admin-imports.generated.ts

@@ -3,7 +3,7 @@
  * string (pages, settings, views, slots, field-type editors) so they load
  * without manual host imports. */
 
-import { registerComponents } from "@nextlyhq/admin";
+import { registerComponentMap } from "@nextlyhq/admin";
 import * as _p0 from "{{pluginName}}/admin";
 import { registeredComponentPaths as listed } from "./plugin-admin-components.generated";
 
@@ -33,5 +33,5 @@ if (
   );
 }
 
-registerComponents(registered);
+registerComponentMap(registered);
 export const registeredComponentPaths = listed;

package/templates/plugin/src/admin/index.ts

@@ -1,24 +1,14 @@
 /**
- * Admin component registration (D19/D60). Importing this module registers the
- * React components referenced by `contributes.admin` string paths so the host
- * admin can resolve them. The host's generated import map imports this for you;
- * the eager + lazy registration below is the fallback.
+ * Admin component registration. Importing this module registers the React
+ * components referenced by `contributes.admin` string paths so the host admin
+ * can resolve them. The host's generated component map imports it for you.
  */
-import {
-  registerComponents,
-  registerKnownPlugin,
-} from "@nextlyhq/plugin-sdk/admin";
+import { registerComponents } from "@nextlyhq/plugin-sdk/admin";
 
 import { SettingsPage } from "./SettingsPage";
 
 const SETTINGS_PATH = "{{pluginName}}/admin#SettingsPage";
 
-// Eager: register on module load.
 registerComponents({ [SETTINGS_PATH]: SettingsPage });
 
-// Lazy fallback: the host can trigger registration on demand by package prefix.
-registerKnownPlugin("{{pluginName}}", async () => {
-  registerComponents({ [SETTINGS_PATH]: SettingsPage });
-});
-
 export { SettingsPage };

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

@@ -1,24 +0,0 @@
-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;
-}