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

package/templates/plugin/AGENTS.md.template

@@ -0,0 +1,125 @@
+<!-- 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 {{pluginName}}
+
+A [Nextly](https://nextlyhq.com) plugin. This is a publishable **library**, not
+an app: `src/` is what ships, and `dev/` is a throwaway Nextly app that exists
+only so you can exercise the plugin in a real admin.
+
+## Where things are
+
+| path                    | what it is                                                       |
+| ----------------------- | ---------------------------------------------------------------- |
+| `src/index.ts`          | the public entry — React-free, so it stays importable on the server |
+| `src/admin/index.ts`    | the `./admin` subpath, where React components are registered      |
+| `src/plugin.ts`         | the plugin factory: what it contributes and what it does on init  |
+| `src/collections/`      | collections the plugin contributes to its host                    |
+| `dev/`                  | the embedded playground: a minimal Nextly app on SQLite           |
+| `dist/`                 | the build output, and the only thing `npm publish` ships          |
+
+## Commands
+
+```bash
+{{runCommand}} dev            # the embedded playground → http://localhost:3000/admin
+{{runCommand}} test           # vitest, against a real Nextly on in-memory SQLite
+{{runCommand}} build          # tsdown → dist/
+{{runCommand}} check-types    # tsc --noEmit
+{{runCommand}} lint           # eslint
+```
+
+`{{runCommand}} dev` runs `next dev dev` — Next.js with `dev/` as the project root.
+Editing anything under `src/` reloads the playground, so the loop is the same as
+working on an app.
+
+## Things that surprise people
+
+- **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`, 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.
+
+  **What is never supported is importing `@nextlyhq/admin` directly.** It carries
+  no compatibility promise to plugin authors, so an import that compiles today
+  breaks on a patch release. If you need something from it that the SDK does not
+  re-export, that is worth raising rather than reaching past the boundary.
+
+- **The root export must stay React-free.** It is imported by the host's server
+  config, so a React import at `src/index.ts` breaks apps that never render your
+  admin UI. Components belong on the `./admin` subpath, which is where the host
+  looks for them.
+- **Resolve your own slugs through `ctx.self`.** A host can rename a collection
+  your plugin contributes; `ctx.self.collections.examples` follows the rename,
+  a hardcoded `"examples"` does not.
+- **`dev/` is never published.** `files` is `["dist"]`, so the playground can
+  depend on anything it likes without adding weight for consumers.
+- **Peers, not dependencies.** `nextly`, `@nextlyhq/admin`,
+  `@nextlyhq/plugin-sdk` and React are peer dependencies — the host supplies
+  them, and bundling a second copy is what causes the "two Reacts" class of
+  failure.
+
+## Testing
+
+`createTestNextly` from `@nextlyhq/plugin-sdk/testing` boots a real Nextly on
+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()] });
+```
+
+**Pass `plugins` alone.** Registration auto-syncs the tables for contributed
+collections, so passing the same collections again as `collections` registers
+those slugs a second time as code-owned entities and boot fails with
+`NEXTLY_SCHEMA_SLUG_COLLISION`.
+
+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
+  deliberately rather than by default.
+- Clean up in `destroy()`. Event subscriptions are dropped for you on registry
+  reset; timers, watchers and connections are not.
+- Keep `contributes` declarative. Work belongs in `init()`, where the context is
+  available and failures are attributable to your plugin.
+
+<!-- nextly:managed:end -->

package/templates/plugin/CLAUDE.md.template

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

package/templates/plugin/README.md

@@ -0,0 +1,48 @@
+# {{pluginName}}
+
+A [Nextly](https://nextlyhq.com) plugin.
+
+## Develop
+
+```bash
+pnpm install
+pnpm dev      # runs the embedded /dev playground → open http://localhost:3000/admin
+```
+
+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
+pnpm test     # boots a real Nextly on in-memory SQLite via createTestNextly
+```
+
+## Build & publish
+
+```bash
+pnpm build    # tsdown → dist/
+npm publish
+```
+
+Only `dist/` ships (see `files` in `package.json`). The `nextly-plugin` keyword
+makes this package discoverable.
+
+## Use in an app
+
+```ts
+// nextly.config.ts
+import { defineConfig } from "nextly";
+import { myPlugin } from "{{pluginName}}";
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+See the [Nextly plugin author guide](https://nextlyhq.com/docs/plugins/author-guide).

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

@@ -0,0 +1,11 @@
+# Dev playground env. create-nextly-app writes dev/.env from this file;
+# copy it again to start over.
+DB_DIALECT=sqlite
+# 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
+
+NEXT_PUBLIC_SITE_URL=http://localhost:3000

package/templates/plugin/dev/next.config.ts

@@ -0,0 +1,43 @@
+import type { NextConfig } from "next";
+
+// Dev playground for the plugin. The plugin's own source (../src) is aliased and
+// transpiled so editing it hot-reloads. `nextly` + the admin come from
+// node_modules (real deps). Node-only / dynamically-imported packages stay
+// external (Turbopack can't bundle them).
+const nextConfig: NextConfig = {
+  typescript: { ignoreBuildErrors: true },
+  // Nextly does not support Cache Components yet; see the installation guide.
+  cacheComponents: false,
+  // Transpile the aliased plugin source so HMR fires on src/ edits.
+  transpilePackages: ["{{pluginName}}"],
+  serverExternalPackages: [
+    "better-sqlite3",
+    "drizzle-orm",
+    "drizzle-kit",
+    "esbuild",
+    "bundle-require",
+    "sharp",
+    "@nextlyhq/adapter-drizzle",
+    "@nextlyhq/adapter-sqlite",
+  ],
+  experimental: {
+    // Next.js type-checks and loads its config through the project's own
+    // TypeScript CLI rather than TypeScript's library API. That is the 16.4
+    // default, stated here so it cannot change underneath: a TypeScript with no
+    // library API (7.0) works only this way.
+    useTypeScriptCli: true,
+    // Turbopack's garbage collector removes cache entries nothing reaches any
+    // more, so `.next` stops growing across dev sessions and builds. Off by
+    // default in 16.4.
+    turbopackGc: true,
+  },
+  turbopack: {
+    resolveAlias: {
+      // Map the package name to its source so HMR works without a build step.
+      "{{pluginName}}": ["./../src/index.ts"],
+      "{{pluginName}}/admin": ["./../src/admin/index.ts"],
+    },
+  },
+};
+
+export default nextConfig;

package/templates/plugin/dev/nextly.config.ts

@@ -0,0 +1,17 @@
+/**
+ * Dev playground config — a minimal Nextly app that registers THIS plugin so you
+ * can exercise it in a real admin. SQLite, dev auto-login. Never published.
+ */
+import { defineConfig } from "nextly/config";
+import { myPlugin } from "{{pluginName}}";
+
+export default defineConfig({
+  admin: {
+    // Land on /admin already logged in. Hard-blocked in production by Nextly.
+    devAutoLogin: {
+      email: "dev@nextly.local",
+      password: "DevPassword123!",
+    },
+  },
+  plugins: [myPlugin()],
+});

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

@@ -0,0 +1,24 @@
+"use client";
+
+import "@nextlyhq/admin/style.css";
+// Registers your plugin's admin components. Generated by
+// `nextly generate:types`; run it again after adding or changing a plugin.
+import "../../../types/generated/plugin-admin-imports.generated";
+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 (
+    <ErrorBoundary
+      onError={(error, errorInfo) => {
+        console.error("Admin error:", error, errorInfo);
+      }}
+    >
+      <QueryProvider>
+        <RootLayout />
+      </QueryProvider>
+    </ErrorBoundary>
+  );
+}

package/templates/plugin/dev/src/app/admin/api/[[...params]]/route.ts

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- framework adapter passes through Next.js App Router context */
+/**
+ * Admin API catch-all. Routes every /admin/api/* request (incl. your plugin's
+ * /api/plugins/<name>/… routes) through the handler built from nextly.config.ts.
+ */
+import { createDynamicHandlers } from "nextly/runtime";
+
+import nextlyConfig from "../../../../../nextly.config";
+
+const handlers = createDynamicHandlers({ config: nextlyConfig });
+
+export const GET = (req: Request, context: any) => handlers.GET(req, context);
+export const POST = (req: Request, context: any) => handlers.POST(req, context);
+export const PUT = (req: Request, context: any) => handlers.PUT(req, context);
+export const PATCH = (req: Request, context: any) =>
+  handlers.PATCH(req, context);
+export const DELETE = (req: Request, context: any) =>
+  handlers.DELETE(req, context);
+export const OPTIONS = (req: Request) => handlers.OPTIONS(req);

package/templates/plugin/dev/src/app/layout.tsx

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+
+export const metadata = {
+  title: "{{pluginName}} — dev playground",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

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

@@ -0,0 +1,25 @@
+// 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");
+  // 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,
+  })();
+
+  // 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/dev/src/types/generated/plugin-admin-components.generated.ts

@@ -0,0 +1,8 @@
+/* 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 = [
+  "{{pluginName}}/admin#SettingsPage",
+] as const;

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

@@ -0,0 +1,37 @@
+/* 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 { registerComponents } from "@nextlyhq/admin";
+import * as _p0 from "{{pluginName}}/admin";
+import { registeredComponentPaths as listed } from "./plugin-admin-components.generated";
+
+const registered = {
+  "{{pluginName}}/admin#SettingsPage": _p0.SettingsPage,
+};
+
+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" }
+  );
+}
+
+registerComponents(registered);
+export const registeredComponentPaths = listed;

package/templates/plugin/dev/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "{{pluginName}}": ["../src/index.ts"],
+      "{{pluginName}}/admin": ["../src/admin/index.ts"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/plugin/eslint.config.mjs

@@ -0,0 +1,19 @@
+import js from "@eslint/js";
+import nextly from "@nextlyhq/eslint-plugin";
+import tseslint from "typescript-eslint";
+
+/**
+ * `nextly.configs.recommended` carries the design-token rules the Nextly admin
+ * holds itself to: no fixed palette colours, no hardcoded colour literals, and
+ * no inline `style` object that a class could have expressed. Admin UI that
+ * follows them inherits light and dark mode and survives a retheme.
+ *
+ * Mark a genuine exception in place, with a reason, rather than switching a rule
+ * off: `// design-lint-ok: <why>` on the line or the line above.
+ */
+export default tseslint.config(
+  { ignores: ["dist", "dev/.next", "node_modules"] },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...nextly.configs.recommended
+);

package/templates/plugin/gitignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+*.log
+
+# Embedded dev playground — never published, never committed build output
+dev/.next
+# 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/admin/SettingsPage.tsx

@@ -0,0 +1,57 @@
+/**
+ * Example plugin settings page, rendered at `/admin/plugins/<slug>` and wrapped in an
+ * error boundary, so a mistake here cannot take the admin down with it.
+ *
+ * Every class here is a design token utility, so this page follows the admin's
+ * theme and its light/dark modes with no styling work of its own. Build your
+ * real settings UI the same way.
+ *
+ * Third-party plugins are not part of the admin's Tailwind `@source` scan, so
+ * only the curated utilities in `plugin-safelist.css` are guaranteed to be
+ * compiled — layout, spacing, type, and the token-mapped colours used below.
+ * Anything outside that set belongs in the stylesheet your plugin declares as
+ * `adminStyles`, written against the `--nx-*` custom properties.
+ */
+export function SettingsPage() {
+  return (
+    <div className="w-full max-w-2xl space-y-6 p-6">
+      <header className="space-y-1">
+        <h1 className="text-xl font-semibold tracking-tight text-foreground">
+          Plugin Settings
+        </h1>
+        <p className="text-sm text-muted-foreground">
+          Settings UI goes here. Edit{" "}
+          <span className="font-mono text-xs">src/admin/SettingsPage.tsx</span>.
+        </p>
+      </header>
+
+      <section className="space-y-4 rounded-lg border border-border bg-card p-6">
+        <div className="space-y-1">
+          <h2 className="text-sm font-semibold text-foreground">
+            Where to put your fields
+          </h2>
+          <p className="text-sm leading-relaxed text-muted-foreground">
+            Replace this card with your own form. Group related settings under a
+            heading, and keep one save action for the page rather than one per
+            group.
+          </p>
+        </div>
+
+        <ul className="space-y-2 text-sm text-muted-foreground">
+          <li>
+            Colours come from tokens —{" "}
+            <span className="font-mono text-xs">bg-card</span>,{" "}
+            <span className="font-mono text-xs">text-muted-foreground</span>,{" "}
+            <span className="font-mono text-xs">border-border</span> — never
+            from a fixed palette shade, which would keep its light-mode
+            appearance in dark mode.
+          </li>
+          <li>
+            Spacing and radius come from the same scales the rest of the admin
+            uses, so your page stays aligned with it when those move.
+          </li>
+        </ul>
+      </section>
+    </div>
+  );
+}

package/templates/plugin/src/admin/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Admin component registration (D19/D60). Importing this module registers the
+ * React components referenced by `contributes.admin` string paths so the host
+ * admin can resolve them. The host's generated import map imports this for you;
+ * the eager + lazy registration below is the fallback.
+ */
+import {
+  registerComponents,
+  registerKnownPlugin,
+} from "@nextlyhq/plugin-sdk/admin";
+
+import { SettingsPage } from "./SettingsPage";
+
+const SETTINGS_PATH = "{{pluginName}}/admin#SettingsPage";
+
+// Eager: register on module load.
+registerComponents({ [SETTINGS_PATH]: SettingsPage });
+
+// Lazy fallback: the host can trigger registration on demand by package prefix.
+registerKnownPlugin("{{pluginName}}", async () => {
+  registerComponents({ [SETTINGS_PATH]: SettingsPage });
+});
+
+export { SettingsPage };

package/templates/plugin/src/collections/example.ts

@@ -0,0 +1,13 @@
+import { defineCollection, text, textarea } from "nextly/config";
+
+/**
+ * An example plugin-owned collection. Replace or remove it with your own.
+ * Plugin collections are merged into the host schema automatically (D3/D12)
+ * and get a real table on `nextly migrate` / boot.
+ */
+export const Examples = defineCollection({
+  slug: "examples",
+  labels: { singular: "Example", plural: "Examples" },
+  fields: [text({ name: "title", required: true }), textarea({ name: "body" })],
+  admin: { useAsTitle: "title" },
+});

package/templates/plugin/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * {{pluginName}} — public entry. The default `.` export is React-free
+ * (Node-safe). Admin React components live on the `./admin` subpath.
+ */
+export { myPlugin } from "./plugin";
+export type { MyPluginOptions } from "./types";

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

@@ -0,0 +1,35 @@
+import { createTestNextly } from "@nextlyhq/plugin-sdk/testing";
+import { afterEach, beforeEach, expect, it } from "vitest";
+
+import { myPlugin } from "./index";
+
+let t: Awaited<ReturnType<typeof createTestNextly>>;
+
+beforeEach(async () => {
+  // `plugins` alone. Runtime auto-sync creates the tables for contributed
+  // collections during registration, so passing them again as `collections`
+  // registers the same slugs as code-owned entities and boot fails with
+  // NEXTLY_SCHEMA_SLUG_COLLISION.
+  t = await createTestNextly({ plugins: [myPlugin()] });
+});
+
+afterEach(async () => {
+  await t.destroy();
+});
+
+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.
+  // 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({
+    collection: "examples",
+    id: String(created.item.id),
+  });
+  expect(fetched?.title).toBe("First example");
+});