create-nextly-app 0.0.2-alpha.66 → 0.0.2-alpha.68

package/dist/index.d.cts

@@ -48,6 +48,12 @@ interface CreateNextlyOptions {
     localTemplatePath?: string;
     /** Git branch for template download from GitHub (defaults to "main") */
     branch?: string;
+    /**
+     * Whether to add the Nextly skills for coding agents to the project.
+     * False skips them without asking; otherwise the developer is asked, and
+     * defaults mode adds them.
+     */
+    skills?: boolean;
 }
 
 /**

package/dist/index.d.ts

@@ -48,6 +48,12 @@ interface CreateNextlyOptions {
     localTemplatePath?: string;
     /** Git branch for template download from GitHub (defaults to "main") */
     branch?: string;
+    /**
+     * Whether to add the Nextly skills for coding agents to the project.
+     * False skips them without asking; otherwise the developer is asked, and
+     * defaults mode adds them.
+     */
+    skills?: boolean;
 }
 
 /**

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { createRequire } from 'module';
-export { createNextly } from './chunk-I2U7KBH6.mjs';
+export { createNextly } from './chunk-XCYSH46I.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.66",
+  "version": "0.0.2-alpha.68",
   "description": "CLI to scaffold Nextly in your Next.js project",
   "license": "MIT",
   "type": "module",
@@ -20,32 +20,43 @@
   "files": [
     "dist",
     "bin",
+    "skills",
     "templates"
   ],
   "dependencies": {
+    "@babel/parser": "^7.29.7",
     "@clack/prompts": "^1.1.0",
     "commander": "^14.0.2",
+    "dotenv-expand": "10.0.0",
     "execa": "^9.6.0",
     "fs-extra": "^11.3.0",
     "picocolors": "^1.1.1",
-    "tar": "^7.5.19"
+    "picomatch": "^4.0.5",
+    "tar": "^7.5.19",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
+    "@babel/types": "^7.29.7",
+    "@nextlyhq/eslint-config": "0.0.2-alpha.68",
+    "@nextlyhq/eslint-plugin": "0.0.2-alpha.68",
+    "@nextlyhq/telemetry": "0.0.2-alpha.68",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.68",
+    "@testing-library/react": "^16.3.0",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^20.19.17",
+    "@types/picomatch": "^4.0.3",
     "@types/tar": "^6.1.13",
     "@typescript-eslint/parser": "^8.59.0",
     "@vitest/coverage-v8": "^4.1.0",
     "@vitest/ui": "^4.1.0",
     "eslint": "^9.39.1",
+    "jsdom": "^27.1.0",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.1.0",
-    "@nextlyhq/eslint-config": "0.0.2-alpha.66",
-    "@nextlyhq/eslint-plugin": "0.0.2-alpha.66",
-    "@nextlyhq/telemetry": "0.0.2-alpha.66",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.66"
+    "vitest": "^4.1.0"
   },
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0"

package/skills/nextly-authentication/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: nextly-authentication
+description: >-
+  Use when deciding who can sign in to a Nextly project and what they can do:
+  the first admin account, roles, access rules on collections, API keys for
+  other apps and scripts, checking the signed-in user in your own server
+  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.67
+---
+
+# Authentication and access in Nextly
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4. Run
+`npx nextly --version`; if it prints a newer version, prefer
+<https://nextlyhq.com/docs/guides/authentication> where it disagrees with this
+skill.
+
+## What is built in, and what is not
+
+Nextly has its own email and password sign-in for the **people who run the
+site**: admins, editors and authors who use the admin panel at `/admin`. It is
+not built on NextAuth or any OAuth library, and it needs no setup beyond
+`NEXTLY_SECRET`.
+
+Its session cookies are scoped to `/admin`. So in this release Nextly does
+**not** provide sign-in for the visitors of your public site, nor social or
+OAuth login. If the site needs visitor accounts, use an auth library for the
+site and keep Nextly for content; do not try to reuse the admin sign-in for
+visitors.
+
+In particular, do not build a sign-in form for your own pages on the Direct
+API's `nextly.login()`. It is for trusted server code, not for signing people
+in, and this release has no ready path for members-only pages. Protect those
+with the auth library the site uses.
+
+## The secret
+
+`NEXTLY_SECRET` signs the session tokens. The installer generates one in
+`.env`. In production it must be at least 32 characters; generate one with:
+
+```bash
+openssl rand -base64 32
+```
+
+Never commit it, and use a different one per environment.
+
+## The first admin
+
+Open `/admin/setup` once, on an empty database, and create the first account.
+It gets the **Super Admin** role, which passes every check. After that, setup
+is closed, and people are added in the admin under **Users**.
+
+Built-in roles: `super-admin`, `admin`, `editor`, `author`, `viewer`. Roles and
+their permissions are managed in the admin under **Settings > Roles**.
+
+## Access rules on a collection
+
+Each operation takes `true`, `false` or a function. A function receives
+`{ user, roles, permissions, operation, collection }`, where `roles` are role
+slugs such as `"editor"` and `user` is `null` for a request with no session.
+
+```ts
+import { defineCollection, text } from "nextly/config";
+import type { AccessControlFunction } from "nextly";
+
+const signedIn: AccessControlFunction = ({ user }) => Boolean(user);
+const editors: AccessControlFunction = ({ roles }) =>
+  roles.includes("admin") || roles.includes("editor");
+
+export const Articles = defineCollection({
+  slug: "articles",
+  fields: [text({ name: "title", required: true })],
+  access: {
+    read: () => true,
+    create: signedIn,
+    update: editors,
+    delete: editors,
+  },
+});
+```
+
+- A Super Admin passes every rule; test rules with another role.
+- These rules are applied to requests to the admin API and to Direct API
+  reads made with `overrideAccess: false`. A plain server-side
+  `nextly.find(...)` is a trusted read that skips them.
+- `read: () => true` does not make the admin API public. Every request to
+  `/admin/api/...` needs a session or an API key, and is refused with 401
+  otherwise. Public pages read content on the server with `getNextly` (the
+  `nextly-collections` skill).
+
+To apply the rules for a particular user in server code:
+
+```ts
+const result = await nextly.find({
+  collection: "articles",
+  overrideAccess: false,
+  user: { id: userId },
+});
+```
+
+## API keys, for other apps and scripts
+
+Create keys in the admin under **Settings > API Keys**. The full key is shown
+once. Send it as a bearer token:
+
+```bash
+curl -H "Authorization: Bearer $NEXTLY_API_KEY" \
+  "https://example.com/admin/api/collections/posts/entries?limit=10"
+```
+
+A **Read-only** key can read and is refused writes (403). **Full access**
+carries its creator's permissions; **Role-based** carries the permissions of a
+role you choose. Keys can expire and be revoked. Keep keys in environment
+variables, never in client code.
+
+## The signed-in user in your own server code
+
+```ts
+// src/app/admin/me/route.ts: the session cookie only reaches /admin paths
+import { getNextly } from "nextly";
+import { getSession, isSuperAdmin } from "nextly/auth";
+
+import nextlyConfig from "../../../../nextly.config";
+
+export async function GET(request: Request) {
+  // Start Nextly first: this route may be the first request a server handles.
+  await getNextly({ config: nextlyConfig });
+  const session = await getSession(request, process.env.NEXTLY_SECRET ?? "");
+  if (!session.authenticated) {
+    return Response.json({ error: "Not signed in" }, { status: 401 });
+  }
+  return Response.json({
+    email: session.user.email,
+    superAdmin: await isSuperAdmin(session.user.id),
+  });
+}
+```
+
+- 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.
+
+## Extra fields on users
+
+```ts
+import { defineConfig, text, textarea } from "nextly/config";
+
+export default defineConfig({
+  users: {
+    fields: [
+      textarea({ name: "bio", maxLength: 500 }),
+      text({ name: "avatarUrl" }),
+    ],
+  },
+  // collections, typescript, ...
+});
+```
+
+Read users with `nextly.users.find()`, not `find({ collection: "users" })`.
+
+## Password reset and verification emails
+
+These need an email provider. Without one, tokens come back in the API
+response as a development fallback. See
+<https://nextlyhq.com/docs/guides/email>.
+
+## Check it worked
+
+- `/admin/setup` creates the first account, and `/admin` signs in.
+- A request to `/admin/api/collections/<slug>/entries` without a session or
+  key answers 401.
+- A read-only API key reads entries and gets 403 on a write.

package/skills/nextly-collections/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: nextly-collections
+description: >-
+  Use when defining or changing content types in a Nextly project in code:
+  writing a collection with defineCollection, choosing field types, adding
+  draft and published status, registering it in nextly.config.ts, generating
+  TypeScript types, creating a migration, and reading entries from a Next.js
+  Server Component with getNextly and find. Also use when a collection does
+  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.67
+---
+
+# Define a collection in Nextly
+
+A collection is a content type with many entries: posts, products, authors.
+Each one becomes a database table, an admin list and edit screen, and a type
+you can query. Collections can also be made in the admin's visual Schema
+Builder; this skill covers the code-first way.
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4. Run
+`npx nextly --version`; if it prints a newer version, prefer
+<https://nextlyhq.com/docs> where it disagrees with this skill. Nextly must
+already be installed (the `nextly-install` skill), with `esbuild` among the
+dev dependencies.
+
+## 1. Write the collection
+
+`src/collections/posts.ts`:
+
+```ts
+import {
+  defineCollection,
+  text,
+  textarea,
+  richText,
+  date,
+  select,
+} from "nextly/config";
+
+export const Posts = defineCollection({
+  slug: "posts",
+  labels: { singular: "Post", plural: "Posts" },
+  fields: [
+    text({ name: "title", required: true }),
+    text({ name: "slug", required: true, unique: true }),
+    textarea({ name: "excerpt" }),
+    richText({ name: "content" }),
+    date({ name: "publishedAt" }),
+    select({
+      name: "category",
+      options: [
+        { label: "News", value: "news" },
+        { label: "Guide", value: "guide" },
+      ],
+    }),
+  ],
+  // Draft and Published, with Save draft and Publish buttons in the admin.
+  status: true,
+  admin: { useAsTitle: "title" },
+  access: {
+    read: () => true,
+    create: ({ user }) => Boolean(user),
+    update: ({ user }) => Boolean(user),
+    delete: ({ roles }) => roles.includes("admin"),
+  },
+});
+```
+
+Rules that matter:
+
+- Import from `nextly/config` in collection files and in `nextly.config.ts`.
+- Use **relative imports** in these files, never the `@/` alias. The Nextly
+  CLI loads them with Node.js, which does not know Next.js aliases.
+- `slug` is the table and API name: lowercase, stable. Renaming it later is a
+  migration, not an edit.
+- `id`, `createdAt` and `updatedAt` are added for you; do not declare them.
+  Declare `title` and `slug` yourself, as above, or the admin shows no input
+  for them and the slug is not unique. The admin fills an empty `slug` from
+  the title.
+- Field helpers in this release: `text`, `textarea`, `richText`, `email`,
+  `password`, `code`, `number`, `checkbox`, `date`, `select`, `radio`,
+  `chips`, `upload`, `relationship`, `repeater`, `array`, `group`, `json`.
+  `relationship({ name: "author", relationTo: "users" })` links entries;
+  add `hasMany: true` for several. `upload({ name: "image", relationTo: "media" })`
+  links a media file.
+- Access rules are explained in the `nextly-authentication` skill.
+
+## 2. Register it
+
+`nextly.config.ts`:
+
+```ts
+import { defineConfig } from "nextly/config";
+
+import { Posts } from "./src/collections/posts";
+
+export default defineConfig({
+  collections: [Posts],
+  singles: [],
+  typescript: {
+    outputFile: "./src/types/generated/nextly-types.ts",
+  },
+});
+```
+
+## 3. Apply it in development
+
+Restart `next dev` after adding or changing a collection. The change is
+applied to the development database on the first request after the restart:
+the log says `Code-first sync completed`. On Next.js 16.4 the in-process
+reload does not pick up a changed field without a restart.
+
+Then open `/admin`: the collection is in the sidebar, with list and create
+screens.
+
+## 4. Generate types
+
+```bash
+npx nextly generate:types
+```
+
+This writes the file named in `typescript.outputFile`, and Zod schemas under
+`src/db/schemas/collections/zod/` (`db/schemas/collections/zod/` without a
+`src/` folder). With them, `find({ collection: "posts" })` is typed; without
+them, entries are loosely typed and fields read as `unknown`. Regenerate in
+the same change as every schema edit.
+
+The Zod schemas import `z` from `nextly/zod`, so the project needs no `zod`
+dependency of its own. To combine them with your own Zod code, import `z`
+from `nextly/zod` there too.
+
+## 5. Read entries in a page
+
+Content is read on the server with the Direct API. Do not build an API route
+to fetch your own content.
+
+```tsx
+// src/app/posts/page.tsx
+import { getNextly } from "nextly";
+import { cachedFind, nextlyTags } from "nextly/runtime";
+
+import nextlyConfig from "../../../nextly.config";
+
+async function getPublishedPosts() {
+  return cachedFind(
+    async () => {
+      const nextly = await getNextly({ config: nextlyConfig });
+      const { items } = await nextly.find({
+        collection: "posts",
+        status: "published",
+        limit: 10,
+      });
+      return items;
+    },
+    { tags: nextlyTags("posts"), keyParts: ["posts", "list"] }
+  );
+}
+
+export default async function PostsPage() {
+  const posts = await getPublishedPosts();
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={String(post.id)}>{String(post.title)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+- Without a `src/` folder the page is `app/posts/page.tsx`, importing
+  `"../../nextly.config"`.
+- `find()` returns `{ items, meta }`. `meta` holds the totals and pages.
+- `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`.
+- `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
+  on any of its fields. Do not cache a read that applies a reader's access
+  rules (`overrideAccess: false` with a `user`): the reader's roles and
+  permissions can change without any content changing, so no tag clears the
+  entry. Read it uncached inside `<Suspense>` instead.
+- Rich text comes back as Lexical JSON. Pass `richTextFormat: "html"` to
+  `find()` to get HTML instead.
+- Users are not a normal collection: read them with `nextly.users.find()`,
+  which supports pagination and `search` but not `where`.
+
+## 6. Make a migration before deploying
+
+Development applies changes directly; production applies migration files.
+When the change is ready to ship:
+
+```bash
+npx nextly migrate:create add_posts
+```
+
+This compares the config with the last migration's snapshot and writes
+`src/db/migrations/<timestamp>_add_posts.sql` plus a snapshot under
+`src/db/migrations/meta/`. Read the SQL, then commit both with the config
+change. `npx nextly migrate` applies pending migrations; the `nextly-deploy`
+skill runs it on every deploy. Once a migration is shared, never edit it: add
+a new one.
+
+## Check it worked
+
+- The admin lists the collection and saves an entry.
+- `npx nextly generate:types` succeeds and `npx tsc --noEmit` is clean.
+- The page shows a published entry, and a draft does not appear.
+- `next build` succeeds.