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

package/templates/plugin/AGENTS.md.template

@@ -0,0 +1,96 @@
+<!-- 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          # tsup → 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`, `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
+  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
+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.
+
+## 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,44 @@
+# {{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.**
+
+## Test
+
+```bash
+pnpm test     # boots a real Nextly on in-memory SQLite via createTestNextly
+```
+
+## Build & publish
+
+```bash
+pnpm build    # tsup → 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,8 @@
+# Dev playground env. Copy to dev/.env and run `pnpm dev`.
+DB_DIALECT=sqlite
+DATABASE_URL=file:./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/instrumentation.ts

@@ -0,0 +1,10 @@
+// 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.
+export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+
+  const { createRegister } = await import("nextly");
+  const { default: config } = await import("./nextly.config");
+  await createRegister(config)();
+}

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

@@ -0,0 +1,30 @@
+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 },
+  // 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",
+  ],
+  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,9 @@
+"use client";
+
+import "@nextlyhq/admin/style.css";
+import { RootLayout } from "@nextlyhq/admin";
+
+// Mounts the Nextly admin shell. Your plugin's menu/pages/settings appear here.
+export default function AdminPage() {
+  return <RootLayout />;
+}

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/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,8 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  { ignores: ["dist", "dev/.next", "node_modules"] },
+  js.configs.recommended,
+  ...tseslint.configs.recommended
+);

package/templates/plugin/gitignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+*.log
+
+# Embedded dev playground — never published, never committed build output
+dev/.next
+dev/*.db
+dev/*.db-journal
+.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,28 @@
+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.
+  const created = await t.nextly.create("examples", { title: "First example" });
+  expect(created.item.id).toBeDefined();
+
+  const fetched = await t.nextly.findById("examples", created.item.id);
+  expect(fetched?.title).toBe("First example");
+});

package/templates/plugin/src/plugin.ts

@@ -0,0 +1,48 @@
+import { definePlugin } from "@nextlyhq/plugin-sdk";
+
+import { Examples } from "./collections/example";
+import type { MyPluginOptions } from "./types";
+
+/**
+ * Your plugin factory. Call it in a host app's `defineConfig({ plugins: [...] })`.
+ *
+ * @example
+ * ```ts
+ * import { myPlugin } from "{{pluginName}}";
+ * export default defineConfig({ plugins: [myPlugin({ greeting: "Hi" })] });
+ * ```
+ */
+export const myPlugin = (opts: MyPluginOptions = {}) =>
+  definePlugin({
+    name: "{{pluginName}}",
+    version: "0.1.0",
+    nextly: "{{nextlyRange}}",
+    enabled: opts.enabled,
+    contributes: {
+      collections: [Examples],
+      permissions: [
+        { action: "manage", resource: "examples", label: "Manage Examples" },
+      ],
+      admin: {
+        menu: [
+          {
+            label: "Examples",
+            to: "/admin/collections/examples",
+            icon: "Sparkles",
+          },
+        ],
+        settings: { component: "{{pluginName}}/admin#SettingsPage" },
+      },
+    },
+    init(ctx) {
+      const greeting = opts.greeting ?? "Hello";
+      // Resolve your own slug via ctx.self so this keeps working if the host
+      // renames the collection (D54). React to the post-commit create event.
+      ctx.events.on(`collection.${ctx.self.collections.examples}.created`, () =>
+        ctx.logger.info(`${greeting} from {{pluginName}} — example created`)
+      );
+    },
+    destroy() {
+      // Clean up here (subscriptions are auto-dropped on registry reset).
+    },
+  });

package/templates/plugin/src/types.ts

@@ -0,0 +1,17 @@
+/**
+ * Options accepted by your plugin factory. These are JSDoc-documented so editors
+ * surface them at the call site (D44).
+ */
+export interface MyPluginOptions {
+  /**
+   * Greeting prefix used by the example collection's `afterCreate` hook.
+   * @default "Hello"
+   */
+  greeting?: string;
+
+  /**
+   * Disable the plugin's behavior (init/hooks/events/routes/admin) while still
+   * applying its schema contributions. Default `true`.
+   */
+  enabled?: boolean;
+}

package/templates/plugin/template.json

@@ -0,0 +1,14 @@
+{
+  "name": "plugin",
+  "label": "Plugin",
+  "description": "Build a reusable Nextly plugin (publishable npm package)",
+  "hint": "Plugin package + embedded /dev playground; no schema approach",
+  "approaches": [],
+  "defaultApproach": null,
+  "collections": [],
+  "singles": [],
+  "hasDemoData": false,
+  "hasFrontendPages": false,
+  "recommendedDatabase": "sqlite",
+  "release": "alpha"
+}

package/templates/plugin/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "dev"]
+}

package/templates/plugin/tsup.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "tsup";
+
+// Builds the publishable plugin. `dev/` is NOT an entry — it never ships.
+// nextly / admin / sdk / ui / react are peers, kept external: bundling one
+// would ship a second copy of code the host already provides.
+export default defineConfig({
+  entry: ["src/index.ts", "src/admin/index.ts"],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  treeshake: true,
+  external: [
+    "nextly",
+    "@nextlyhq/admin",
+    "@nextlyhq/plugin-sdk",
+    "@nextlyhq/ui",
+    "react",
+    "react-dom",
+  ],
+  outExtension() {
+    return { js: ".mjs" };
+  },
+});

package/templates/plugin/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});