create-nextly-app 0.0.2-alpha.6 → 0.0.2-alpha.60

package/dist/index.d.cts

@@ -1,8 +1,9 @@
 /**
  * Project type / template selection.
  * "blog" is the first content template added for alpha.
+ * "plugin" scaffolds a publishable Nextly plugin package + embedded /dev playground (D44/D45).
  */
-type ProjectType = "blank" | "blog";
+type ProjectType = "blank" | "blog" | "plugin";
 /**
  * Schema approach selection for content templates.
  * - code-first: Full schema definitions in nextly.config.ts (like Payload CMS)

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * Project type / template selection.
  * "blog" is the first content template added for alpha.
+ * "plugin" scaffolds a publishable Nextly plugin package + embedded /dev playground (D44/D45).
  */
-type ProjectType = "blank" | "blog";
+type ProjectType = "blank" | "blog" | "plugin";
 /**
  * Schema approach selection for content templates.
  * - code-first: Full schema definitions in nextly.config.ts (like Payload CMS)

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { createRequire } from 'module';
-export { createNextly } from './chunk-6NVRVAZA.mjs';
+export { createNextly } from './chunk-SEU6FVET.mjs';
 
 createRequire(import.meta.url);
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nextly-app",
-  "version": "0.0.2-alpha.6",
+  "version": "0.0.2-alpha.60",
   "description": "CLI to scaffold Nextly in your Next.js project",
   "license": "MIT",
   "type": "module",
@@ -27,27 +27,26 @@
     "commander": "^14.0.2",
     "execa": "^9.6.0",
     "fs-extra": "^11.3.0",
-    "ora": "^9.0.0",
     "picocolors": "^1.1.1",
-    "tar": "^7.4.0"
+    "tar": "^7.5.19"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
-    "@types/tar": "^6.1.13",
     "@types/node": "^20.19.17",
-    "@vitest/coverage-v8": "^4.0.8",
-    "@vitest/ui": "^4.0.8",
-    "eslint": "^9.34.0",
+    "@types/tar": "^6.1.13",
+    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/ui": "^4.1.0",
+    "eslint": "^9.39.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.0.8",
-    "@nextlyhq/eslint-config": "0.0.2-alpha.5",
-    "@nextlyhq/telemetry": "0.0.2-alpha.5",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.5"
+    "vitest": "^4.1.0",
+    "@nextlyhq/eslint-config": "0.0.2-alpha.60",
+    "@nextlyhq/telemetry": "0.0.2-alpha.60",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.60"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
   },
   "keywords": [
     "nextly",

package/templates/base/.env.example

@@ -12,5 +12,16 @@ NEXTLY_SECRET=change-me-generate-a-secure-secret
 # Application URL
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 
+# Development diagnostics (opt-in)
+# Uncomment to add a _devDiagnostics field to error responses, carrying the
+# error's log context and the underlying cause, so a failure names itself while
+# you build instead of only in the server log.
+#
+# Left commented on purpose. It is the SECOND of two independent signals — the
+# first is NODE_ENV — and the second exists precisely because NODE_ENV is a
+# runtime value a deployment can carry by mistake. A default that ships in this
+# file would be true in exactly that case, which is the one it guards against.
+# NEXTLY_DEV_DIAGNOSTICS=1
+
 # Storage Configuration
 {{storageEnvVars}}

package/templates/base/AGENTS.md.template

@@ -0,0 +1,158 @@
+<!-- nextly:managed:start -->
+<!--
+  Everything between these markers is generated by create-nextly-app and may be
+  replaced when the project is upgraded. Write your own notes OUTSIDE the block:
+  anything above or below it is yours and is preserved.
+-->
+
+# Agent guide for this Nextly project
+
+A Next.js app with [Nextly](https://nextlyhq.com) for content. The CMS runs
+inside this app rather than beside it: same server, same database, no separate
+service to start.
+
+## Where things are
+
+| path                   | what it is                                                         |
+| ---------------------- | ------------------------------------------------------------------ |
+| `nextly.config.ts`     | the config the whole app boots from — collections, database, admin |
+| `src/collections/`     | code-first collection definitions, when this project uses them     |
+| `src/app/(frontend)/`  | the public site                                                    |
+| `src/app/admin/`       | the admin panel, served at `/admin`                                |
+| `migrations/`          | SQL migrations, in this project's dialect                          |
+| `src/types/generated/` | generated types — never edit by hand                               |
+
+## Commands
+
+```bash
+{{runCommand}} dev                  # start Next.js; schema changes apply in-process
+{{runCommand}} build                # migrate, then build
+{{runCommand}} db:setup             # first run: create the schema
+{{runCommand}} db:migrate           # apply pending migrations
+{{runCommand}} db:migrate:status    # what has and has not been applied
+{{runCommand}} db:migrate:fresh     # drop everything and re-run (destructive)
+{{runCommand}} types:generate       # regenerate types after a schema change
+```
+
+This project uses **{{databaseDialect}}**.
+
+## Reading content
+
+Content is read through the Direct API, on the server:
+
+```ts
+import { getNextly } from "nextly";
+import nextlyConfig from "@nextly-config";
+
+const nextly = await getNextly({ config: nextlyConfig });
+const posts = await nextly.find({ collection: "posts", limit: 10 });
+```
+
+**`find()` returns loosely-typed documents until types are generated.** Without
+`{{runCommand}} types:generate`, `posts.items` is `Record<string, unknown>[]` and a
+field access is `unknown`. Generating types makes the slug and the return type
+infer, so `posts.items` becomes `Post[]`.
+
+Until then, narrow with a runtime check rather than an assertion — a document
+missing a field yields `undefined`, and asserting the type only moves the
+failure to where the value is used:
+
+```ts
+const slug = typeof doc.slug === "string" ? doc.slug : undefined;
+```
+
+## Things that surprise people
+
+- **Users are not a normal collection.** Read them through `nextly.users`, not
+  `find({ collection: "users" })`. The users namespace supports pagination and
+  `search`; it does not support a `where` filter.
+- **A migration you generate is one file, in THIS project's dialect.**
+  `{{execCommand}} nextly migrate:create <name>` (no package.json script exists for it) writes a
+  single `migrations/<timestamp>_<slug>.sql` containing **{{databaseDialect}}**
+  SQL — no `.mysql.sql` or `.sqlite.sql` beside it. Edit that file.
+- **A suffixed set means the migration was shipped, not generated.** A template
+  that supports every dialect ships `0001_x.sql` (Postgres) alongside
+  `0001_x.mysql.sql` and `0001_x.sqlite.sql`, and the CLI runs the variant for
+  the configured dialect. Those are prebuilt. Adding companion variants to a
+  migration you generated is not part of the normal workflow, and nothing will
+  run them unless this project is itself meant to support several dialects.
+- **The admin needs a first user.** Visit `/admin` after `{{runCommand}} dev` and
+  complete the setup screen.
+- **Cache tags come from `nextly/runtime`.** Wrap PUBLIC reads in `cachedFind`
+  and tag them with `nextlyTags(collection)` so a write invalidates the right
+  pages.
+
+  **`keyParts` is a security boundary, not a performance detail.** Two callers
+  whose `keyParts` match share one cache entry. So if the read applies any
+  per-caller rule — owner-only scoping, role-based visibility, an API key's
+  narrowed scope — the caller's identity has to be IN the key, or one user's
+  rows get served to another:
+
+  **A shared cache entry is only safe if the read is public for EVERY reader.**
+  Two independent things can make it not so, and each needs its own answer:
+
+  - **drafts** — `find()` defaults to `overrideAccess: true`, a trusted server
+    read, so a slug filter alone can return an unpublished row. `status:
+    "published"` is enforced even on a trusted read and fixes this one.
+  - **per-row access rules** — owner-only scoping, role-based visibility, an API
+    key's narrowed scope. `status` does NOT evaluate these; it is a
+    draft/published lifecycle filter and nothing more. A published row that only
+    its owner may read is still returned by the query above.
+
+  So the decision is: **does this collection carry read-access rules?**
+
+  ```ts
+  // NO access rules — the result is identical for every reader, so one shared
+  // entry is correct and gets the full ISR benefit.
+  // `find()` always returns the list envelope `{ items, meta }`, so a detail route takes the
+  // first item — and caches THAT, not the envelope around it.
+  cachedFind(
+    async () =>
+      (
+        await nextly.find({
+          collection: "posts",
+          where: { slug: { equals: slug } },
+          status: "published",
+          limit: 1,
+        })
+      ).items[0] ?? null,
+    { tags: nextlyTags("posts"), keyParts: ["posts", slug] }
+  );
+
+  // ACCESS RULES — evaluate them as the caller, and key by EVERY dimension the
+  // rules read, not just who the caller is.
+  //
+  // Both role fields are optional and Nextly reads BOTH: the many-to-many
+  // `roles` unioned with the singular `role`. Deduped and sorted, so one role
+  // set spelled two ways is one cache entry rather than two.
+  const roleKey = (u: { role?: string; roles?: string[] }) =>
+    [...new Set([...(u.roles ?? []), u.role ?? []].flat())].sort().join(",");
+
+  cachedFind(
+    () => nextly.find({ collection: "orders", user, overrideAccess: false }),
+    {
+      tags: nextlyTags("orders"),
+      keyParts: ["orders", "list", user.id, roleKey(user)],
+    }
+  );
+  ```
+
+  **`user.id` alone is not the authorization context.** Roles change, custom
+  claims change, an API key's scope is narrower than its owner's. A key built
+  from identity alone survives all of those, so the same person can fill the
+  entry while privileged and read it back after being downgraded — the tags bust
+  on CONTENT changes, and a permission change is not one. Include whatever the
+  rules actually read: the role set, the claim, the key's scope.
+
+  If you are unsure whether a collection has read rules, do not cache it. A
+  missing cache is slow; a shared one leaks.
+
+## Conventions worth keeping
+
+- Server components read content directly; do not build an API route to fetch
+  your own content.
+- Regenerate types in the same change as the schema edit that needs them.
+- Migrations are append-only once shared. Add a new one rather than editing an
+  applied file.
+
+<!-- nextly:managed:end -->

package/templates/base/CLAUDE.md.template

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/base/gitignore

@@ -0,0 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

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/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,31 @@
 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";
 
-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
@@ -32,12 +47,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/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/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,32 @@
 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";
 
-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.
@@ -38,9 +51,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>
   );
 }