create-nextly-app 0.0.1 → 0.0.2-alpha.0

package/templates/base/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"],
+      "@nextly-config": ["./nextly.config.ts"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/blank/.env.example

@@ -0,0 +1,8 @@
+# Public site URL used by:
+# - Metadata API (canonical URLs, OpenGraph image resolution)
+# - sitemap.xml, robots.txt, and any RSS feed route handlers you add
+# - JSON-LD structured data links
+#
+# Set this to your production domain when deploying (e.g. https://yourapp.com).
+# The localhost fallback keeps local development working.
+NEXT_PUBLIC_SITE_URL=http://localhost:3000

package/templates/blank/README.md

@@ -0,0 +1,63 @@
+# Blank template
+
+A minimal Nextly project with the conventional folder layout already
+scaffolded. Empty `nextly.config.ts`, no collections, one landing
+page, and READMEs in every convention folder so you know where things
+go as you grow.
+
+## When to use
+
+Choose `blank` when you want to build everything from scratch but
+appreciate having the right folder structure waiting for you. Pick
+[`blog`](../blog/README.md) instead if you want a populated example
+with collections, singles, frontend pages, RSS, search, and demo
+content already wired up.
+
+## Scaffold
+
+```bash
+pnpm create nextly-app my-app --template blank
+```
+
+## What you get
+
+```
+my-app/
+├── nextly.config.ts        # Empty config — add your collections / singles
+├── .env.example            # NEXT_PUBLIC_SITE_URL etc.
+├── next.config.ts          # (inherited from base)
+├── postcss.config.mjs      # (inherited from base)
+├── tsconfig.json           # (inherited from base)
+└── src/
+    ├── access/             # RBAC functions (anyone, authenticated, ...)
+    ├── collections/        # defineCollection() definitions
+    ├── singles/            # defineSingle() definitions
+    ├── components/         # React components (ThemeToggle ships as an example)
+    ├── lib/                # Project-wide helpers
+    └── app/
+        ├── layout.tsx      # Root layout (font + metadata)
+        ├── globals.css     # Design tokens
+        └── (frontend)/     # Public-facing routes (route group)
+            └── page.tsx    # Landing page — flips between "Set up admin" / "Open admin"
+```
+
+The `(frontend)` route group keeps your public pages cleanly separated
+from `app/admin/...` and `app/api/...` routes that Nextly mounts. As
+you add routes, drop them inside `(frontend)/` and they'll inherit
+your blog/marketing layout instead of the admin's.
+
+Every convention folder ships with a `README.md` explaining what
+belongs there. Replace them with real code as you build.
+
+## Next steps
+
+- **Add a collection** — create `src/collections/Posts.ts`, register
+  it in `nextly.config.ts`, run `pnpm dev`. The admin will surface it
+  immediately.
+- **Add a public page** — drop a new file under
+  `src/app/(frontend)/blog/page.tsx`. It'll be live at `/blog`.
+- **Configure storage / email** — see
+  [`nextlyhq.com/docs`](https://nextlyhq.com/docs) for adapter setup.
+
+See [`templates/blog/README.md`](../blog/README.md) for a fully
+populated example showing all of the above wired up.

package/templates/blank/nextly.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "nextly/config";
+
+export default defineConfig({
+  // Add your collections here
+  collections: [],
+
+  // Add your singles (globals) here
+  singles: [],
+
+  // TypeScript type generation
+  typescript: {
+    outputFile: "./src/types/generated/nextly-types.ts",
+  },
+});

package/templates/blank/src/access/README.md

@@ -0,0 +1,22 @@
+# Access
+
+Access-control functions used by `defineCollection({ access: ... })`
+and `defineSingle({ access: ... })`. Each function decides whether the
+current user can perform an action (read, create, update, delete) on a
+collection or single.
+
+Conventions:
+
+- One function per file. File name matches the function name.
+- Export the function as a named export.
+- Type signature: `AccessControlFunction` from `nextly`.
+
+Common patterns shipped in the blog template (for reference):
+
+- `anyone.ts` — always allow (use for public reads).
+- `authenticated.ts` — require any logged-in user.
+- `is-admin.ts` — require the `admin` role.
+- `is-author-or-editor.ts` — require one of several roles.
+
+Add your own here as your project grows. Wire them up in your
+collections / singles config.

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

@@ -0,0 +1,176 @@
+import Link from "next/link";
+
+import { ThemeToggle } from "@/components/ThemeToggle";
+
+/**
+ * Blank-template landing page (public route via the (frontend) route group).
+ *
+ * Replaces the inherited Next.js placeholder at `/` with a minimal,
+ * brutalist-edge welcome page that points the developer at the admin
+ * panel and the docs. Server Component — fetches setup-status so the
+ * primary button label flips between "Set up admin" (no super-admin
+ * yet) and "Open admin" (super-admin exists).
+ *
+ * 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
+ * works either way.
+ *
+ * Edit this file in src/app/(frontend)/page.tsx after scaffolding to customise.
+ */
+
+interface SetupStatus {
+  isSetup: boolean;
+  requiresInitialUser: boolean;
+}
+
+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`, {
+      cache: "no-store",
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as SetupStatus;
+  } catch {
+    return null;
+  }
+}
+
+export default async function HomePage() {
+  const status = await fetchSetupStatus();
+  const needsSetup = status?.requiresInitialUser ?? false;
+  const adminLabel = needsSetup ? "Set up admin" : "Open admin";
+  const adminHref = needsSetup ? "/admin/setup" : "/admin";
+
+  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 />
+      <div className="max-w-[640px] w-full text-center">
+        <div className="flex items-center justify-center mb-8">
+          <svg
+            width="180"
+            height="48"
+            viewBox="0 0 235 63"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            className="text-foreground"
+          >
+            <rect width="62" height="63" fill="currentColor" />
+            <path
+              d="M18 46.7034L24.6253 43.6455V26.6564L32.9494 30.5448V23.26L18 16.21V46.7034Z"
+              fill="var(--color-background)"
+            />
+            <path
+              d="M44 16.2102L37.3747 19.268V36.2905L29.035 32.4021L29.0506 39.6536L44 46.7036V16.2102Z"
+              fill="var(--color-background)"
+            />
+            <path
+              d="M116.233 11.0908V45.9999H109.858L94.6705 24.0283H94.4148V45.9999H87.0341V11.0908H93.5114L108.58 33.0454H108.886V11.0908H116.233ZM134.126 46.5113C131.433 46.5113 129.115 45.9658 127.172 44.8749C125.24 43.7726 123.751 42.2158 122.706 40.2044C121.661 38.1817 121.138 35.7897 121.138 33.0283C121.138 30.3351 121.661 27.9715 122.706 25.9374C123.751 23.9033 125.223 22.3181 127.121 21.1817C129.03 20.0454 131.268 19.4772 133.837 19.4772C135.564 19.4772 137.172 19.7556 138.661 20.3124C140.161 20.8579 141.467 21.6817 142.581 22.784C143.706 23.8863 144.581 25.2726 145.206 26.9431C145.831 28.6022 146.143 30.5454 146.143 32.7726V34.7669H124.036V30.2669H139.308C139.308 29.2215 139.081 28.2954 138.626 27.4885C138.172 26.6817 137.541 26.051 136.734 25.5965C135.939 25.1306 135.013 24.8976 133.956 24.8976C132.854 24.8976 131.876 25.1533 131.024 25.6647C130.183 26.1647 129.524 26.8408 129.047 27.6931C128.57 28.534 128.325 29.4715 128.314 30.5056V34.784C128.314 36.0794 128.553 37.1988 129.03 38.1419C129.518 39.0851 130.206 39.8124 131.092 40.3238C131.979 40.8351 133.03 41.0908 134.246 41.0908C135.053 41.0908 135.791 40.9772 136.462 40.7499C137.132 40.5226 137.706 40.1817 138.183 39.7272C138.661 39.2726 139.024 38.7158 139.274 38.0567L145.99 38.4999C145.649 40.1135 144.95 41.5226 143.893 42.7272C142.848 43.9204 141.496 44.8522 139.837 45.5226C138.189 46.1817 136.286 46.5113 134.126 46.5113ZM156.482 19.8181L161.288 28.9715L166.214 19.8181H173.663L166.078 32.909L173.868 45.9999H166.453L161.288 36.9488L156.209 45.9999H148.709L156.482 32.909L148.982 19.8181H156.482ZM191.902 19.8181V25.2726H176.135V19.8181H191.902ZM179.714 13.5454H186.976V37.9544C186.976 38.6249 187.078 39.1476 187.283 39.5226C187.487 39.8863 187.771 40.1419 188.135 40.2897C188.51 40.4374 188.942 40.5113 189.43 40.5113C189.771 40.5113 190.112 40.4829 190.453 40.426C190.794 40.3579 191.055 40.3067 191.237 40.2726L192.379 45.676C192.016 45.7897 191.504 45.9204 190.845 46.0681C190.186 46.2272 189.385 46.3238 188.442 46.3579C186.692 46.426 185.158 46.1931 183.839 45.659C182.533 45.1249 181.516 44.2954 180.788 43.1704C180.061 42.0454 179.703 40.6249 179.714 38.909V13.5454ZM204.456 11.0908V45.9999H197.195V11.0908H204.456ZM214.756 55.8181C213.835 55.8181 212.972 55.7442 212.165 55.5965C211.369 55.4601 210.71 55.284 210.188 55.0681L211.824 49.6476C212.676 49.909 213.443 50.051 214.125 50.0738C214.818 50.0965 215.415 49.9374 215.915 49.5965C216.426 49.2556 216.841 48.676 217.159 47.8579L217.585 46.7499L208.193 19.8181H215.83L221.25 39.0454H221.523L226.994 19.8181H234.682L224.506 48.8294C224.017 50.2385 223.352 51.4658 222.511 52.5113C221.682 53.5681 220.631 54.3806 219.358 54.9488C218.085 55.5283 216.551 55.8181 214.756 55.8181Z"
+              fill="currentColor"
+            />
+          </svg>
+          <span className="ml-4 font-mono text-[10px] font-semibold tracking-wide uppercase px-2 py-0.5 bg-foreground/5 text-slate-500">
+            Alpha
+          </span>
+        </div>
+
+        <h1 className="mx-auto font-semibold tracking-[-0.03em] leading-[1.1] text-[clamp(24px,5vw,32px)]">
+          Welcome to your new Nextly project.
+        </h1>
+
+        <p className="mt-6 mx-auto text-slate-500 dark:text-slate-400 max-w-[42ch] text-[clamp(16px,1.8vw,18px)] leading-[1.6]">
+          This is the blank template. Open the admin to create your first
+          collection or read the docs to see what Nextly can do.
+        </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>
+          <Link href="https://nextlyhq.com/docs" className="btn-secondary">
+            <span>Read documentation</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-up-right"
+            >
+              <path d="M7 7h10v10" />
+              <path d="M7 17 17 7" />
+            </svg>
+          </Link>
+        </div>
+
+        <div className="mt-16 pt-8 border-t border-foreground/5 flex flex-col sm:flex-row items-center justify-between gap-6">
+          <p className="font-mono text-[11px] tracking-tight text-slate-500">
+            Edit in{" "}
+            <span className="text-foreground">src/app/(frontend)/page.tsx</span>
+          </p>
+          <div className="flex gap-6">
+            <Link
+              href="https://github.com/nextlyhq/nextly"
+              className="flex items-center gap-2 text-[12px] font-medium text-slate-500 hover:text-foreground transition-colors"
+            >
+              <svg
+                aria-hidden="true"
+                focusable="false"
+                viewBox="0 0 24 24"
+                width="16"
+                height="16"
+                fill="currentColor"
+                style={{ verticalAlign: "text-bottom" }}
+              >
+                <path d="M10.226 17.284c-2.965-.36-5.054-2.493-5.054-5.256 0-1.123.404-2.336 1.078-3.144-.292-.741-.247-2.314.09-2.965.898-.112 2.111.36 2.83 1.01.853-.269 1.752-.404 2.853-.404 1.1 0 1.999.135 2.807.382.696-.629 1.932-1.1 2.83-.988.315.606.36 2.179.067 2.942.72.854 1.101 2 1.101 3.167 0 2.763-2.089 4.852-5.098 5.234.763.494 1.28 1.572 1.28 2.807v2.336c0 .674.561 1.056 1.235.786 4.066-1.55 7.255-5.615 7.255-10.646C23.5 6.188 18.334 1 11.978 1 5.62 1 .5 6.188.5 12.545c0 4.986 3.167 9.12 7.435 10.669.606.225 1.19-.18 1.19-.786V20.63a2.9 2.9 0 0 1-1.078.224c-1.483 0-2.359-.808-2.987-2.313-.247-.607-.517-.966-1.034-1.033-.27-.023-.359-.135-.359-.27 0-.27.45-.471.898-.471.652 0 1.213.404 1.797 1.235.45.651.921.943 1.483.943.561 0 .92-.202 1.437-.719.382-.381.674-.718.944-.943"></path>
+              </svg>
+              <span>GitHub</span>
+            </Link>
+            <Link
+              href="https://nextlyhq.com"
+              className="flex items-center gap-2 text-[12px] font-medium text-slate-500 hover:text-foreground transition-colors"
+            >
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="lucide lucide-globe"
+              >
+                <circle cx="12" cy="12" r="10" />
+                <path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" />
+                <path d="M2 12h20" />
+              </svg>
+              <span>Website</span>
+            </Link>
+          </div>
+        </div>
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,79 @@
+@import "tailwindcss";
+
+/**
+ * Blank-template global styles.
+ *
+ * Overrides templates/base/src/app/globals.css so the branded landing
+ * page renders with its supporting decorations: a subtle 56px grid
+ * backdrop, the corner brackets, the pulsing "Localhost / Development"
+ * dot, and a hover-invert helper for the secondary button.
+ *
+ * Tailwind base tokens still apply — these rules are additive.
+ */
+
+:root {
+  --color-background: #f9fafb;
+  --color-foreground: #0f172a;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-background: #0b0f19;
+    --color-foreground: #f9fafb;
+  }
+}
+
+.dark {
+  --color-background: #0b0f19;
+  --color-foreground: #f9fafb;
+}
+
+@theme {
+  --color-background: var(--color-background);
+  --color-foreground: var(--color-foreground);
+}
+
+body {
+  background-color: var(--color-background);
+  color: var(--color-foreground);
+  overflow-x: hidden;
+}
+
+.pulse-dot {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  margin-right: 6px;
+  background: #10b981;
+  border-radius: 50%;
+  box-shadow: 0 0 8px #10b981;
+  animation: nextly-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes nextly-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.4;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pulse-dot {
+    animation: none;
+  }
+}
+
+.font-display {
+  font-family: var(--font-display), ui-sans-serif, system-ui, sans-serif;
+}
+
+.btn-primary {
+  @apply inline-flex items-center gap-2.5 rounded-none bg-foreground px-6 py-3.5 text-sm font-semibold text-background transition-all hover:opacity-90 active:scale-95;
+}
+
+.btn-secondary {
+  @apply inline-flex items-center gap-2.5 rounded-none border border-foreground/10 bg-transparent px-6 py-3.5 text-sm font-medium text-foreground transition-all hover:bg-foreground/5 active:scale-95;
+}

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

@@ -0,0 +1,46 @@
+import type { Metadata } from "next";
+import { Inter, JetBrains_Mono } from "next/font/google";
+
+import "./globals.css";
+
+const display = Inter({
+  variable: "--font-display",
+  subsets: ["latin"],
+  display: "swap",
+});
+
+const mono = JetBrains_Mono({
+  variable: "--font-mono",
+  subsets: ["latin"],
+  display: "swap",
+});
+
+/**
+ * Blank-template root layout.
+ *
+ * Overrides templates/base/src/app/layout.tsx so the landing page can
+ * use a distinctive font pairing (Bricolage Grotesque for display,
+ * JetBrains Mono for tech accents). `metadataBase` is set so future
+ * 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"
+  ),
+  title: { default: "Nextly", template: "%s — Nextly" },
+  description: "A Nextly project.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={`${display.variable} ${mono.variable} antialiased`}>
+        {children}
+      </body>
+    </html>
+  );
+}

package/templates/blank/src/collections/README.md

@@ -0,0 +1,22 @@
+# Collections
+
+Code-first collections. Each collection is defined via
+`defineCollection({ ... })` from `nextly/config` and wired into the
+root `nextly.config.ts` as part of the `collections: [...]` array.
+
+Conventions:
+
+- Trivial collections (a few scalar fields, no hooks): single file
+  named after the collection (e.g. `Categories.ts`).
+- Complex collections (many fields, hooks, or per-collection helpers):
+  folder named after the collection, with `index.ts` exporting the
+  collection definition and a `hooks/` subdir for hooks specific to
+  that collection (e.g. `Posts/index.ts` + `Posts/hooks/`).
+- Imports inside collection files use relative paths (`../access/...`)
+  rather than the `@/` alias because `nextly.config.ts` is loaded by
+  the CLI through plain Node.js module resolution, which does not
+  honour TypeScript path aliases.
+
+Skip this folder if you're using the Visual Schema Builder (admin UI)
+to manage your schemas — UI-built collections live in the database, not
+on disk.

package/templates/blank/src/components/README.md

@@ -0,0 +1,10 @@
+# Components
+
+React components used by your `src/app/` routes. Server Components by
+default; add `"use client"` at the top of any file that needs
+interactivity.
+
+The blank template ships one example: `ThemeToggle.tsx` (used on the
+landing page). Add your own components here as your project grows.
+
+Use the `@/` path alias to import: `import { Foo } from "@/components/Foo"`.

package/templates/blank/src/components/ThemeToggle.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import { useEffect, useState } 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 applyTheme = (newTheme: Theme) => {
+    const isDark =
+      newTheme === "dark" ||
+      (newTheme === "system" &&
+        window.matchMedia("(prefers-color-scheme: dark)").matches);
+
+    document.documentElement.classList.toggle("dark", isDark);
+  };
+
+  const handleThemeChange = (newTheme: Theme) => {
+    setTheme(newTheme);
+    localStorage.setItem("theme", newTheme);
+    applyTheme(newTheme);
+  };
+
+  return (
+    <div className="fixed top-6 right-6 flex items-center border border-foreground/10 bg-background p-1 z-50">
+      <button
+        onClick={() => handleThemeChange("light")}
+        className={`p-1.5 transition-colors cursor-pointer ${
+          theme === "light"
+            ? "text-foreground bg-foreground/5"
+            : "text-slate-400 hover:text-foreground"
+        }`}
+        aria-label="Light theme"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth={2}
+          stroke="currentColor"
+          className="w-4 h-4"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M3 12h2.25m.386-6.364l1.591 1.591M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z"
+          />
+        </svg>
+      </button>
+
+      <button
+        onClick={() => handleThemeChange("system")}
+        className={`p-1.5 transition-colors cursor-pointer ${
+          theme === "system"
+            ? "text-foreground bg-foreground/5"
+            : "text-slate-400 hover:text-foreground"
+        }`}
+        aria-label="System theme"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth={2}
+          stroke="currentColor"
+          className="w-4 h-4"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M9 17.25v1.007a3 3 0 01-.879 2.122L7.5 21h9l-.621-.621A3 3 0 0115 18.257V17.25m6-12V15a2.25 2.25 0 01-2.25 2.25H5.25A2.25 2.25 0 013 15V5.25m18 0A2.25 2.25 0 0018.75 3H5.25A2.25 2.25 0 003 5.25m18 0V12a2.25 2.25 0 01-2.25 2.25H5.25A2.25 2.25 0 013 12V5.25"
+          />
+        </svg>
+      </button>
+
+      <button
+        onClick={() => handleThemeChange("dark")}
+        className={`p-1.5 transition-colors cursor-pointer ${
+          theme === "dark"
+            ? "text-foreground bg-foreground/5"
+            : "text-slate-400 hover:text-foreground"
+        }`}
+        aria-label="Dark theme"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth={2}
+          stroke="currentColor"
+          className="w-4 h-4"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z"
+          />
+        </svg>
+      </button>
+    </div>
+  );
+}

package/templates/blank/src/lib/README.md

@@ -0,0 +1,15 @@
+# Lib
+
+Project-wide helpers and utilities. Add files here for things that get
+imported across multiple components or routes.
+
+Examples (from the blog template, for inspiration):
+
+- `format-date.ts` — locale-aware date formatting.
+- `site-url.ts` — resolves canonical URLs for OG / sitemap.
+- `queries/` — cached Direct-API wrappers (e.g. `getPostBySlug`).
+- `rss.ts` — RSS feed builder.
+
+Use the `@/` path alias (`import { ... } from "@/lib/foo"`) inside
+your `src/app/`, `src/components/`, etc. Do not use the alias inside
+`nextly.config.ts` or files transitively loaded by it.

package/templates/blank/src/singles/README.md

@@ -0,0 +1,19 @@
+# Singles
+
+Code-first singles (formerly "globals"). Each single is defined via
+`defineSingle({ ... })` from `nextly/config` and wired into the root
+`nextly.config.ts` as part of the `singles: [...]` array.
+
+A single is a one-of content record — Site Settings, Homepage layout,
+Footer config, etc. Use Singles when there is exactly one record of a
+given type, and use Collections when the type has many records.
+
+Conventions:
+
+- One file or folder per single. Folder if the single has hooks or
+  helpers; flat file if it's a small scalar definition.
+- Imports inside single files use relative paths (`../access/...`)
+  rather than the `@/` alias because `nextly.config.ts` is loaded by
+  the CLI through plain Node.js module resolution.
+
+Skip this folder if you're using the Visual Schema Builder.

package/templates/blank/template.json

@@ -0,0 +1,14 @@
+{
+  "name": "blank",
+  "label": "Blank",
+  "description": "Start fresh with an empty config",
+  "hint": "Empty project, define your own schemas",
+  "approaches": [],
+  "defaultApproach": null,
+  "collections": [],
+  "singles": [],
+  "hasDemoData": false,
+  "hasFrontendPages": true,
+  "recommendedDatabase": "any",
+  "release": "alpha"
+}