create-nextly-app 0.0.2-alpha.65 → 0.0.2-alpha.67

package/templates/plugin/AGENTS.md.template

@@ -40,10 +40,10 @@ 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`, `registerComponents` and
-  `registerKnownPlugin` from `@nextlyhq/plugin-sdk/admin`, `createTestNextly`
-  from `@nextlyhq/plugin-sdk/testing`, field factories, `pluginField`,
-  `NextlyError`. Collections and singles are defined the same way an app defines
+  does AS a plugin: `definePlugin`, field factories, `pluginField` and
+  `NextlyError` from `@nextlyhq/plugin-sdk`; `registerComponents` and
+  `registerKnownPlugin` 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.
 
@@ -73,6 +73,8 @@ in-memory SQLite with your plugin registered, so a test exercises the same
 lifecycle a host would run:
 
 ```ts
+import { createTestNextly } from "@nextlyhq/plugin-sdk/testing";
+
 const t = await createTestNextly({ plugins: [myPlugin()] });
 ```
 
@@ -84,6 +86,33 @@ those slugs a second time as code-owned entities and boot fails with
 Assert on behaviour through `t.nextly` rather than on the plugin object: what a
 host observes is the contract, and the object shape is not.
 
+## Which Nextly this is, and where its docs are
+
+An agent working here will otherwise answer from whatever it remembers of some
+other version. Ask the project instead:
+
+```bash
+{{execCommand}} nextly --version      # the running core version
+```
+
+That is the same version the plugin resolver validates a plugin's `nextly`
+range against, so a compatibility answer and a reported version cannot
+disagree. The dependency range this project pins is in `package.json` under
+`nextly`; the resolved version is what the command above prints.
+
+**The authoritative documentation is <https://nextlyhq.com/docs>.** Two files
+are published for machine readers and are the ones to fetch:
+
+| file | what it is |
+| ---- | ---------- |
+| <https://nextlyhq.com/llms.txt> | the index — every documentation page, with a one-line summary |
+| <https://nextlyhq.com/llms-full.txt> | the same documentation as one file |
+
+Both are generated from the pages the site publishes, so they cannot describe a
+page that does not exist. Neither is version-stamped: they describe the CURRENT
+release, so check the version above before trusting a detail against an older
+pin.
+
 ## Conventions worth keeping
 
 - Version `nextly` compatibility in the factory's `nextly` range, and widen it

package/templates/plugin/README.md

@@ -13,6 +13,10 @@ Your plugin lives in `src/`. The `dev/` folder is a minimal Nextly app on SQLite
 that registers this plugin so you can exercise it in a real admin with hot-reload.
 Editing files under `src/` reloads the playground. **`dev/` is never published.**
 
+The playground signs you in automatically as `dev@nextly.local` (password
+`DevPassword123!`). That user is created on the first `pnpm dev`, and only
+under `next dev`; production builds ignore the auto-login setting.
+
 ## Test
 
 ```bash

package/templates/plugin/dev/.env.example

@@ -1,6 +1,9 @@
-# Dev playground env. Copy to dev/.env and run `pnpm dev`.
+# Dev playground env. create-nextly-app writes dev/.env from this file;
+# copy it again to start over.
 DB_DIALECT=sqlite
-DATABASE_URL=file:./nextly-dev.db
+# Relative to the plugin root, where `pnpm dev` runs (`next dev dev` keeps
+# that working directory), so the database lands in dev/.
+DATABASE_URL=file:./dev/nextly-dev.db
 
 # Any non-empty secret works for local dev (sign/verify session cookies).
 NEXTLY_SECRET=dev-secret-change-me

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

@@ -1,9 +1,21 @@
 "use client";
 
 import "@nextlyhq/admin/style.css";
-import { RootLayout } from "@nextlyhq/admin";
+import { ErrorBoundary, QueryProvider, RootLayout } from "@nextlyhq/admin";
 
 // Mounts the Nextly admin shell. Your plugin's menu/pages/settings appear here.
+// The admin's data hooks read their client from QueryProvider, so RootLayout
+// renders only inside it, as in an app scaffold.
 export default function AdminPage() {
-  return <RootLayout />;
+  return (
+    <ErrorBoundary
+      onError={(error, errorInfo) => {
+        console.error("Admin error:", error, errorInfo);
+      }}
+    >
+      <QueryProvider>
+        <RootLayout />
+      </QueryProvider>
+    </ErrorBoundary>
+  );
 }

package/templates/plugin/dev/src/instrumentation.ts

@@ -0,0 +1,20 @@
+// Warm up Nextly once per worker at startup (Node.js runtime only) so admin/API
+// handlers never run before init and schema boot-apply runs once, not per request.
+// Imported dynamically + guarded so nextly stays out of the Edge bundle. It sits
+// in src/ beside app/, where Next.js looks for it when an app lives under src/.
+export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+
+  const { createRegister, getService } = await import("nextly");
+  const { default: config } = await import("../nextly.config");
+  await createRegister(config)();
+
+  // Create the user admin.devAutoLogin signs in as (see seed-dev-user.ts).
+  // After boot, because boot seeds every permission and the Super Admin role
+  // created here takes all that exist.
+  const { seedSuperAdmin } = await import("nextly/database/seeders");
+  const { seedDevUser } = await import("./seed-dev-user");
+  await seedDevUser(config.admin?.devAutoLogin, options =>
+    seedSuperAdmin(getService("adapter"), options)
+  );
+}

package/templates/plugin/dev/src/seed-dev-user.ts

@@ -0,0 +1,51 @@
+/**
+ * Create the account `admin.devAutoLogin` signs in as.
+ *
+ * Auto-login signs in a user that already exists and never creates one, so
+ * without this the first /admin visit lands on the setup wizard. The seeder is
+ * passed in by instrumentation.ts, which keeps this file free of imports and
+ * lets it run on its own.
+ */
+
+/** The account `admin.devAutoLogin` names, as nextly.config.ts declares it. */
+export type DevAutoLogin = false | { email: string; password?: string };
+
+/** Creates a super-admin, skipping one that already exists. */
+export type SeedSuperAdmin = (options: {
+  email: string;
+  password: string;
+  name: string;
+  silent: boolean;
+}) => Promise<{ success: boolean; errorMessages?: string[] }>;
+
+export async function seedDevUser(
+  login: DevAutoLogin | undefined,
+  seed: SeedSuperAdmin
+): Promise<void> {
+  // `next dev` only: no credentials in a production build, and tests bring
+  // their own fixtures.
+  if (process.env.NODE_ENV !== "development" || !login) return;
+
+  // Auto-login needs no password, but creating the account does.
+  if (!login.password) {
+    console.warn(
+      `[dev] admin.devAutoLogin names ${login.email} without a password, so that user is not created.`
+    );
+    return;
+  }
+
+  const result = await seed({
+    email: login.email,
+    password: login.password,
+    name: "Dev User",
+    silent: true,
+  });
+  if (!result.success) {
+    // Otherwise the only sign is the setup wizard, with nothing saying why.
+    console.warn(
+      `[dev] Could not create the auto-login user ${login.email}: ${
+        result.errorMessages?.join("; ") ?? "unknown error"
+      }`
+    );
+  }
+}

package/templates/plugin/gitignore

@@ -4,7 +4,10 @@ dist
 
 # Embedded dev playground — never published, never committed build output
 dev/.next
-dev/*.db
-dev/*.db-journal
+# SQLite files, and the journal and WAL files beside them, wherever they land.
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
 .env
 .env.local

package/templates/plugin/src/plugin.test.ts

@@ -20,9 +20,16 @@ afterEach(async () => {
 it("boots and exposes the plugin's example collection (real table)", async () => {
   // Creating an entry proves the contributed collection got a real table and
   // the plugin's lifecycle ran. Replace with assertions for your own behavior.
-  const created = await t.nextly.create("examples", { title: "First example" });
+  // The Direct API takes one argument object per call.
+  const created = await t.nextly.create({
+    collection: "examples",
+    data: { title: "First example" },
+  });
   expect(created.item.id).toBeDefined();
 
-  const fetched = await t.nextly.findById("examples", created.item.id);
+  const fetched = await t.nextly.findByID({
+    collection: "examples",
+    id: String(created.item.id),
+  });
   expect(fetched?.title).toBe("First example");
 });

package/templates/plugin/vitest.config.ts

@@ -4,5 +4,24 @@ export default defineConfig({
   test: {
     environment: "node",
     include: ["src/**/*.test.ts"],
+    /*
+     * Sized for an instance boot, because that is what this suite does.
+     *
+     * `plugin.test.ts` calls `createTestNextly` in `beforeEach`, which builds a
+     * DI container, registers the plugin's schema and runs auto-sync against a
+     * real SQLite database. Vitest's defaults are sized for a unit test that
+     * touches none of that: 5s for a case and 10s for a hook. A boot is about a
+     * second and a half on a warm machine, and the first run of a freshly
+     * scaffolded project is the least warm moment there is - a cold install, no
+     * build cache, whatever the laptop or CI container is doing.
+     *
+     * This is the first command a new plugin author runs, so a timeout here
+     * reads as "the scaffold ships a broken test" rather than "the budget was
+     * tight". The monorepo solves the same problem by routing boots to a lane
+     * with a 30s budget; a single-package project has one lane and nothing to
+     * contend with, so it states the budget instead.
+     */
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
   },
 });