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

package/templates/base/next.config.ts

@@ -1,21 +1,15 @@
 import type { NextConfig } from "next";
 
-const nextConfig: NextConfig = {
-  serverExternalPackages: [
-    "nextly",
-    "@nextlyhq/adapter-drizzle",
-    "@nextlyhq/adapter-postgres",
-    "@nextlyhq/adapter-mysql",
-    "@nextlyhq/adapter-sqlite",
-    "drizzle-orm",
-    "drizzle-kit",
-    "pg",
-    "mysql2",
-    "better-sqlite3",
-    "bcryptjs",
-    "sharp",
-    "esbuild",
-  ],
-};
+/**
+ * Minimal base `next.config.ts` for bundled templates.
+ *
+ * This file is intentionally left minimal (no adapter whitelist). The
+ * scaffolder will generate or patch a database-specific `next.config.ts`
+ * that includes only the selected adapter and driver in
+ * `serverExternalPackages`. Keeping the base file minimal avoids
+ * advertising adapters the user didn't choose and prevents misleading
+ * generated projects.
+ */
+const nextConfig: NextConfig = {};
 
 export default nextConfig;

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

@@ -1,6 +1,9 @@
 "use client";
 
 import "@nextlyhq/admin/style.css";
+// Registers every plugin admin component the app's config declares. Generated
+// by `nextly generate:types`; run it again after adding or changing a plugin.
+import "../../../types/generated/plugin-admin-imports.generated";
 import { RootLayout, QueryProvider, ErrorBoundary } from "@nextlyhq/admin";
 
 export default function AdminPage() {

package/templates/base/src/app/admin/api/media/[[...path]]/route.ts

@@ -0,0 +1,26 @@
+/**
+ * Admin Media API — permission-gated management surface.
+ *
+ * The admin's session cookie is scoped to `/admin`, so it reaches here but not
+ * the public `/api/media`. Every operation is checked against a media
+ * permission (read/create/update/delete-media) and the acting identity is
+ * taken from the session/API key, never a request field. This is the only
+ * place media can be uploaded, edited, moved or deleted.
+ *
+ * Supported (all gated):
+ * - GET/POST/PATCH/DELETE /admin/api/media/*  (files, folders, bulk delete)
+ */
+
+import { createMediaHandlers } from "nextly/api/media-handlers";
+
+import config from "@nextly-config";
+
+const handlers = createMediaHandlers({
+  config,
+  requireAuth: true,
+});
+
+export const GET = handlers.GET;
+export const POST = handlers.POST;
+export const PATCH = handlers.PATCH;
+export const DELETE = handlers.DELETE;

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

@@ -1,5 +1,15 @@
 @import "tailwindcss";
 
+/* The families the imported font stylesheets declare, bound to the variables the rules
+   below read. Named here rather than by `next/font`, which used to inject them: the faces
+   now arrive as ordinary stylesheets, so the binding has to be written down somewhere, and
+   the name is load-bearing — the admin theme reads `--font-geist`. Quoted family names, so
+   the two-word values stay one identifier. */
+:root {
+  --font-geist: "Geist Variable";
+  --font-geist-mono: "Geist Mono Variable";
+}
+
 :root {
   --background: #ffffff;
   --foreground: #171717;
@@ -8,8 +18,11 @@
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
-  --font-sans: var(--font-geist-sans);
-  --font-mono: var(--font-geist-mono);
+  /* Fallback arguments, not a trailing family list: an unresolved var() with no
+     fallback invalidates the whole declaration rather than falling through to
+     what comes after the closing paren. */
+  --font-sans: var(--font-geist, ui-sans-serif), system-ui, sans-serif;
+  --font-mono: var(--font-geist-mono, ui-monospace), monospace;
 }
 
 @media (prefers-color-scheme: dark) {

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

@@ -1,16 +1,32 @@
 import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import "./globals.css";
+import { SITE_URL } from "@/lib/site-url";
 
-const geistSans = Geist({
-  variable: "--font-geist-sans",
-  subsets: ["latin"],
-});
-
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});
+/**
+ * The faces are imported as STYLESHEETS from packages in `node_modules`, rather
+ * than fetched from fonts.googleapis.com by `next/font/google` while
+ * `next build` runs — which made every build depend on reaching a third party
+ * and fail behind a proxy, on a locked-down runner, or offline.
+ *
+ * A bare package import rather than `next/font/local` pointing INTO
+ * `node_modules`: a literal path asserts where the package physically lives,
+ * and that assertion is false under Yarn's Plug'n'Play linker (no
+ * `node_modules` at all), under npm/Yarn workspace hoisting (the package moves
+ * to the workspace root), and under pnpm's own symlinked store. An import asks
+ * the resolver instead, which is correct under every layout.
+ *
+ * The trade is `next/font`'s metric-adjusted fallback, so text can shift
+ * slightly as the face arrives. The families are bound to this app's `--font-*`
+ * variables in `globals.css`, which is what every rule downstream reads. *
+ * Importing the package root ships every subset the face offers — Latin, Latin
+ * Extended, Cyrillic, Vietnamese — but each `@font-face` carries a
+ * `unicode-range`, so a browser downloads only the subsets the page actually
+ * uses. The deployed bundle is larger than a single hand-picked file; what a
+ * reader fetches is not, and a page in Cyrillic now gets its face instead of a
+ * fallback.
+ */
 
 /**
  * `metadataBase` tells Next.js how to resolve relative URLs in OpenGraph
@@ -19,9 +35,7 @@ const geistMono = Geist_Mono({
  * `https://yourblog.com`). The localhost fallback keeps dev working.
  */
 export const metadata: Metadata = {
-  metadataBase: new URL(
-    process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000"
-  ),
+  metadataBase: new URL(SITE_URL),
   title: { default: "Nextly", template: "%s — Nextly" },
   description: "A site built with Nextly.",
 };
@@ -32,12 +46,12 @@ export default function RootLayout({
   children: React.ReactNode;
 }>) {
   return (
+    // The font variables belong on <html>: the admin theme declares --font-sans
+    // in a non-inline @theme, which emits it into :root and resolves the
+    // reference THERE. A variable exposed lower down, on <body>, is invisible to
+    // that declaration however it is spelled.
     <html lang="en" suppressHydrationWarning>
-      <body
-        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
-      >
-        {children}
-      </body>
+      <body className="antialiased">{children}</body>
     </html>
   );
 }

package/templates/base/src/lib/site-url.ts

@@ -0,0 +1,55 @@
+/**
+ * The origin this site's absolute URLs are built from.
+ *
+ * Absolute URLs are needed in places that leave the browser's context —
+ * `metadataBase`, canonical links, Open Graph tags, the sitemap, RSS and
+ * JSON-LD. A relative path is meaningless in all of them, so something has to
+ * name the origin.
+ *
+ * ## Why two variables, in this order
+ *
+ * `NEXT_PUBLIC_SITE_URL` is where READERS find the site. `NEXT_PUBLIC_APP_URL`
+ * is where the Nextly app itself lives — the admin, the API, the origin its
+ * emails and preview links point at. They are usually the same host and are
+ * not the same question: a headless setup serves its public pages from one
+ * origin and runs the admin on another.
+ *
+ * So the public one wins when it is set, and the app's own origin is used when
+ * it is not. That second step matters more than it looks: the generated `.env`
+ * sets `NEXT_PUBLIC_APP_URL`, so without it a project that configured the only
+ * URL it was given would still publish `localhost` canonicals and OG tags to
+ * production — silently, because nothing about a wrong absolute URL fails at
+ * build time.
+ *
+ * ## The development fallback reads the port it is actually served on
+ *
+ * Not a hardcoded 3000. Next assigns `process.env.PORT` to the port it ends up
+ * listening on — after its own "port in use, using available port instead"
+ * fallback — so this follows `next dev -p 4000`, and follows Next onto a
+ * different port when 3000 is taken. A literal cannot do either, and the
+ * failure is quiet: pages render while every absolute URL points somewhere
+ * nothing is listening.
+ *
+ * `PORT` is a server-side value and is not inlined into client bundles, so a
+ * client component importing this reads the plain default. That is the same
+ * answer it would have had anyway, and client code should prefer
+ * `window.location.origin`, which is exact.
+ */
+const DEV_PORT = process.env.PORT ?? "3000";
+
+export const SITE_URL =
+  process.env.NEXT_PUBLIC_SITE_URL ??
+  process.env.NEXT_PUBLIC_APP_URL ??
+  `http://localhost:${DEV_PORT}`;
+
+/**
+ * Join a path onto {@link SITE_URL} without duplicating slashes.
+ *
+ * @param path - A root-relative path; a leading slash is optional
+ * @returns The absolute URL
+ */
+export function absoluteUrl(path = "/"): string {
+  const base = SITE_URL.replace(/\/$/, "");
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${p}`;
+}

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

@@ -0,0 +1,6 @@
+/* AUTO-GENERATED by `nextly generate:types` — DO NOT EDIT.
+ * The component paths `plugin-admin-imports.generated.ts` registers, as
+ * plain strings, so server code can read what the admin's map holds
+ * without importing the components. Regenerated with it. */
+
+export const registeredComponentPaths = [] as const;

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

@@ -0,0 +1,32 @@
+/* AUTO-GENERATED by `nextly generate:types` — DO NOT EDIT.
+ * Statically registers the plugin admin components the admin resolves by
+ * string (pages, settings, views, slots, field-type editors) so they load
+ * without manual host imports. */
+
+import { registeredComponentPaths as listed } from "./plugin-admin-components.generated";
+
+const registered = {};
+
+type Registered = keyof typeof registered;
+type Listed = (typeof listed)[number];
+/** `true` only while this map registers exactly the paths its list names. */
+type Agrees = [Registered] extends [Listed]
+  ? [Listed] extends [Registered]
+    ? true
+    : "component map and its list disagree: run npx nextly generate:types"
+  : "component map and its list disagree: run npx nextly generate:types";
+export const componentMapAgreesWithList: Agrees = true;
+
+if (
+  JSON.stringify(Object.keys(registered).sort()) !==
+  JSON.stringify([...listed].sort())
+) {
+  throw Object.assign(
+    new Error(
+      "The admin's component map and its list disagree: run npx nextly generate:types."
+    ),
+    { code: "NEXTLY_ADMIN_COMPONENT_MAP_MISMATCH" }
+  );
+}
+
+export const registeredComponentPaths = listed;

package/templates/base/tsconfig.json

@@ -20,7 +20,14 @@
     ],
     "paths": {
       "@/*": ["./src/*"],
-      "@nextly-config": ["./nextly.config.ts"]
+      "@/components/*": ["./src/app/(frontend)/components/*"],
+      "@nextly-config": ["./nextly.config.ts"],
+      // Pagefind's browser bundle is generated into public/ at build time, so it
+      // is imported by URL and cannot be resolved on disk while type-checking.
+      // A `declare module` cannot describe it either: TypeScript treats a rooted
+      // specifier as relative and rejects the declaration (TS2436). Templates
+      // without a search page simply never import it, leaving this mapping inert.
+      "/pagefind/pagefind.js": ["./src/types/pagefind.d.ts"]
     }
   },
   "include": [

package/templates/blank/src/{components → 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/app/(frontend)/page.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 
 import { ThemeToggle } from "@/components/ThemeToggle";
+import { SITE_URL } from "@/lib/site-url";
 
 /**
  * Blank-template landing page (public route via the (frontend) route group).
@@ -26,8 +27,7 @@ interface SetupStatus {
 
 async function fetchSetupStatus(): Promise<SetupStatus | null> {
   try {
-    const baseUrl = process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000";
-    const res = await fetch(`${baseUrl}/api/auth/setup-status`, {
+    const res = await fetch(`${SITE_URL}/api/auth/setup-status`, {
       cache: "no-store",
     });
     if (!res.ok) return null;

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

@@ -1,5 +1,25 @@
 @import "tailwindcss";
 
+/* The families the imported font stylesheets declare, bound to the variables the rules
+   below read. Named here rather than by `next/font`, which used to inject them: the faces
+   now arrive as ordinary stylesheets, so the binding has to be written down somewhere, and
+   the name is load-bearing — the admin theme reads `--font-geist`. Quoted family names, so
+   the two-word values stay one identifier. */
+:root {
+  /* `--font-geist` and `--font-geist-mono` are the names the ADMIN theme reads
+     (`--font-sans: var(--font-geist, Geist), ...` in a non-inline `@theme`, so
+     it resolves at `:root`). A template that loads a different face still has to
+     expose it under these names or the admin renders in a system fallback while
+     the app's own pages render correctly. */
+  --font-geist: "Inter Variable";
+  --font-geist-mono: "JetBrains Mono Variable";
+  /* This template's own display face, read by `.font-display` below. NOT named
+     `--font-mono` for its mono face: that is the theme's OWN token, declared at
+     `:root`, and redefining it here replaces the theme's whole fallback chain
+     rather than feeding it. */
+  --font-display: "Inter Variable";
+}
+
 /**
  * Blank-template global styles.
  *
@@ -28,6 +48,18 @@
   --color-foreground: #f9fafb;
 }
 
+/* `@theme inline` on purpose, and it is the whole point of this block. An inline theme
+   SUBSTITUTES the value where the utility is used; a plain `@theme` emits the variable into
+   `:root`, which is where `@nextlyhq/admin` declares its own `--font-mono` — redefining it there
+   would replace the admin's entire fallback chain with this one family.
+   
+   Needed because the frontend routes do not load the admin stylesheet, so nothing else binds the
+   `font-mono` utility this template uses on its badge and file-path text; without it they fall
+   back to Tailwind's default mono rather than the face the template loads. */
+@theme inline {
+  --font-mono: var(--font-geist-mono, ui-monospace), monospace;
+}
+
 @theme {
   --color-background: var(--color-background);
   --color-foreground: var(--color-foreground);
@@ -67,7 +99,11 @@ body {
 }
 
 .font-display {
-  font-family: var(--font-display), ui-sans-serif, system-ui, sans-serif;
+  /* The generic families are the var()'s fallback argument rather than a list
+     after it: an unresolved var() with no fallback invalidates the whole
+     declaration, so the element would inherit its parent's face instead of
+     falling through to these. */
+  font-family: var(--font-display, ui-sans-serif), system-ui, sans-serif;
 }
 
 .btn-primary {

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

@@ -1,19 +1,33 @@
 import type { Metadata } from "next";
-import { Inter, JetBrains_Mono } from "next/font/google";
+import "@fontsource-variable/inter";
+import "@fontsource-variable/jetbrains-mono";
 
 import "./globals.css";
+import { SITE_URL } from "@/lib/site-url";
 
-const display = Inter({
-  variable: "--font-display",
-  subsets: ["latin"],
-  display: "swap",
-});
-
-const mono = JetBrains_Mono({
-  variable: "--font-mono",
-  subsets: ["latin"],
-  display: "swap",
-});
+/**
+ * The faces are imported as STYLESHEETS from packages in `node_modules`, rather
+ * than fetched from fonts.googleapis.com by `next/font/google` while
+ * `next build` runs — which made every build depend on reaching a third party
+ * and fail behind a proxy, on a locked-down runner, or offline.
+ *
+ * A bare package import rather than `next/font/local` pointing INTO
+ * `node_modules`: a literal path asserts where the package physically lives,
+ * and that assertion is false under Yarn's Plug'n'Play linker (no
+ * `node_modules` at all), under npm/Yarn workspace hoisting (the package moves
+ * to the workspace root), and under pnpm's own symlinked store. An import asks
+ * the resolver instead, which is correct under every layout.
+ *
+ * The trade is `next/font`'s metric-adjusted fallback, so text can shift
+ * slightly as the face arrives. The families are bound to this app's `--font-*`
+ * variables in `globals.css`, which is what every rule downstream reads. *
+ * Importing the package root ships every subset the face offers — Latin, Latin
+ * Extended, Cyrillic, Vietnamese — but each `@font-face` carries a
+ * `unicode-range`, so a browser downloads only the subsets the page actually
+ * uses. The deployed bundle is larger than a single hand-picked file; what a
+ * reader fetches is not, and a page in Cyrillic now gets its face instead of a
+ * fallback.
+ */
 
 /**
  * Blank-template root layout.
@@ -24,9 +38,7 @@ const mono = JetBrains_Mono({
  * blank-template pages can use relative OG image URLs without breaking.
  */
 export const metadata: Metadata = {
-  metadataBase: new URL(
-    process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000"
-  ),
+  metadataBase: new URL(SITE_URL),
   title: { default: "Nextly", template: "%s — Nextly" },
   description: "A Nextly project.",
 };
@@ -38,9 +50,7 @@ export default function RootLayout({
 }>) {
   return (
     <html lang="en" suppressHydrationWarning>
-      <body className={`${display.variable} ${mono.variable} antialiased`}>
-        {children}
-      </body>
+      <body className="antialiased">{children}</body>
     </html>
   );
 }

package/templates/blank/src/instrumentation.ts

@@ -0,0 +1,32 @@
+/**
+ * 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");
+  // 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.
+  await createRegister(config, {
+    cacheComponents: process.env.__NEXT_CACHE_COMPONENTS,
+  })();
+}