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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createRequire } from 'module';
2
- export { createNextly } from './chunk-E6IFBI6N.mjs';
2
+ export { createNextly } from './chunk-SEU6FVET.mjs';
3
3
 
4
4
  createRequire(import.meta.url);
5
5
  //# sourceMappingURL=index.mjs.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-nextly-app",
3
- "version": "0.0.2-alpha.58",
3
+ "version": "0.0.2-alpha.60",
4
4
  "description": "CLI to scaffold Nextly in your Next.js project",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -27,7 +27,6 @@
27
27
  "commander": "^14.0.2",
28
28
  "execa": "^9.6.0",
29
29
  "fs-extra": "^11.3.0",
30
- "ora": "^9.0.0",
31
30
  "picocolors": "^1.1.1",
32
31
  "tar": "^7.5.19"
33
32
  },
@@ -42,9 +41,9 @@
42
41
  "typescript": "^5.9.3",
43
42
  "vite-tsconfig-paths": "^5.1.4",
44
43
  "vitest": "^4.1.0",
45
- "@nextlyhq/eslint-config": "0.0.2-alpha.58",
46
- "@nextlyhq/telemetry": "0.0.2-alpha.58",
47
- "@nextlyhq/tsconfig": "0.0.2-alpha.58"
44
+ "@nextlyhq/eslint-config": "0.0.2-alpha.60",
45
+ "@nextlyhq/telemetry": "0.0.2-alpha.60",
46
+ "@nextlyhq/tsconfig": "0.0.2-alpha.60"
48
47
  },
49
48
  "engines": {
50
49
  "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
@@ -0,0 +1,158 @@
1
+ <!-- nextly:managed:start -->
2
+ <!--
3
+ Everything between these markers is generated by create-nextly-app and may be
4
+ replaced when the project is upgraded. Write your own notes OUTSIDE the block:
5
+ anything above or below it is yours and is preserved.
6
+ -->
7
+
8
+ # Agent guide for this Nextly project
9
+
10
+ A Next.js app with [Nextly](https://nextlyhq.com) for content. The CMS runs
11
+ inside this app rather than beside it: same server, same database, no separate
12
+ service to start.
13
+
14
+ ## Where things are
15
+
16
+ | path | what it is |
17
+ | ---------------------- | ------------------------------------------------------------------ |
18
+ | `nextly.config.ts` | the config the whole app boots from — collections, database, admin |
19
+ | `src/collections/` | code-first collection definitions, when this project uses them |
20
+ | `src/app/(frontend)/` | the public site |
21
+ | `src/app/admin/` | the admin panel, served at `/admin` |
22
+ | `migrations/` | SQL migrations, in this project's dialect |
23
+ | `src/types/generated/` | generated types — never edit by hand |
24
+
25
+ ## Commands
26
+
27
+ ```bash
28
+ {{runCommand}} dev # start Next.js; schema changes apply in-process
29
+ {{runCommand}} build # migrate, then build
30
+ {{runCommand}} db:setup # first run: create the schema
31
+ {{runCommand}} db:migrate # apply pending migrations
32
+ {{runCommand}} db:migrate:status # what has and has not been applied
33
+ {{runCommand}} db:migrate:fresh # drop everything and re-run (destructive)
34
+ {{runCommand}} types:generate # regenerate types after a schema change
35
+ ```
36
+
37
+ This project uses **{{databaseDialect}}**.
38
+
39
+ ## Reading content
40
+
41
+ Content is read through the Direct API, on the server:
42
+
43
+ ```ts
44
+ import { getNextly } from "nextly";
45
+ import nextlyConfig from "@nextly-config";
46
+
47
+ const nextly = await getNextly({ config: nextlyConfig });
48
+ const posts = await nextly.find({ collection: "posts", limit: 10 });
49
+ ```
50
+
51
+ **`find()` returns loosely-typed documents until types are generated.** Without
52
+ `{{runCommand}} types:generate`, `posts.items` is `Record<string, unknown>[]` and a
53
+ field access is `unknown`. Generating types makes the slug and the return type
54
+ infer, so `posts.items` becomes `Post[]`.
55
+
56
+ Until then, narrow with a runtime check rather than an assertion — a document
57
+ missing a field yields `undefined`, and asserting the type only moves the
58
+ failure to where the value is used:
59
+
60
+ ```ts
61
+ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
62
+ ```
63
+
64
+ ## Things that surprise people
65
+
66
+ - **Users are not a normal collection.** Read them through `nextly.users`, not
67
+ `find({ collection: "users" })`. The users namespace supports pagination and
68
+ `search`; it does not support a `where` filter.
69
+ - **A migration you generate is one file, in THIS project's dialect.**
70
+ `{{execCommand}} nextly migrate:create <name>` (no package.json script exists for it) writes a
71
+ single `migrations/<timestamp>_<slug>.sql` containing **{{databaseDialect}}**
72
+ SQL — no `.mysql.sql` or `.sqlite.sql` beside it. Edit that file.
73
+ - **A suffixed set means the migration was shipped, not generated.** A template
74
+ that supports every dialect ships `0001_x.sql` (Postgres) alongside
75
+ `0001_x.mysql.sql` and `0001_x.sqlite.sql`, and the CLI runs the variant for
76
+ the configured dialect. Those are prebuilt. Adding companion variants to a
77
+ migration you generated is not part of the normal workflow, and nothing will
78
+ run them unless this project is itself meant to support several dialects.
79
+ - **The admin needs a first user.** Visit `/admin` after `{{runCommand}} dev` and
80
+ complete the setup screen.
81
+ - **Cache tags come from `nextly/runtime`.** Wrap PUBLIC reads in `cachedFind`
82
+ and tag them with `nextlyTags(collection)` so a write invalidates the right
83
+ pages.
84
+
85
+ **`keyParts` is a security boundary, not a performance detail.** Two callers
86
+ whose `keyParts` match share one cache entry. So if the read applies any
87
+ per-caller rule — owner-only scoping, role-based visibility, an API key's
88
+ narrowed scope — the caller's identity has to be IN the key, or one user's
89
+ rows get served to another:
90
+
91
+ **A shared cache entry is only safe if the read is public for EVERY reader.**
92
+ Two independent things can make it not so, and each needs its own answer:
93
+
94
+ - **drafts** — `find()` defaults to `overrideAccess: true`, a trusted server
95
+ read, so a slug filter alone can return an unpublished row. `status:
96
+ "published"` is enforced even on a trusted read and fixes this one.
97
+ - **per-row access rules** — owner-only scoping, role-based visibility, an API
98
+ key's narrowed scope. `status` does NOT evaluate these; it is a
99
+ draft/published lifecycle filter and nothing more. A published row that only
100
+ its owner may read is still returned by the query above.
101
+
102
+ So the decision is: **does this collection carry read-access rules?**
103
+
104
+ ```ts
105
+ // NO access rules — the result is identical for every reader, so one shared
106
+ // entry is correct and gets the full ISR benefit.
107
+ // `find()` always returns the list envelope `{ items, meta }`, so a detail route takes the
108
+ // first item — and caches THAT, not the envelope around it.
109
+ cachedFind(
110
+ async () =>
111
+ (
112
+ await nextly.find({
113
+ collection: "posts",
114
+ where: { slug: { equals: slug } },
115
+ status: "published",
116
+ limit: 1,
117
+ })
118
+ ).items[0] ?? null,
119
+ { tags: nextlyTags("posts"), keyParts: ["posts", slug] }
120
+ );
121
+
122
+ // ACCESS RULES — evaluate them as the caller, and key by EVERY dimension the
123
+ // rules read, not just who the caller is.
124
+ //
125
+ // Both role fields are optional and Nextly reads BOTH: the many-to-many
126
+ // `roles` unioned with the singular `role`. Deduped and sorted, so one role
127
+ // set spelled two ways is one cache entry rather than two.
128
+ const roleKey = (u: { role?: string; roles?: string[] }) =>
129
+ [...new Set([...(u.roles ?? []), u.role ?? []].flat())].sort().join(",");
130
+
131
+ cachedFind(
132
+ () => nextly.find({ collection: "orders", user, overrideAccess: false }),
133
+ {
134
+ tags: nextlyTags("orders"),
135
+ keyParts: ["orders", "list", user.id, roleKey(user)],
136
+ }
137
+ );
138
+ ```
139
+
140
+ **`user.id` alone is not the authorization context.** Roles change, custom
141
+ claims change, an API key's scope is narrower than its owner's. A key built
142
+ from identity alone survives all of those, so the same person can fill the
143
+ entry while privileged and read it back after being downgraded — the tags bust
144
+ on CONTENT changes, and a permission change is not one. Include whatever the
145
+ rules actually read: the role set, the claim, the key's scope.
146
+
147
+ If you are unsure whether a collection has read rules, do not cache it. A
148
+ missing cache is slow; a shared one leaks.
149
+
150
+ ## Conventions worth keeping
151
+
152
+ - Server components read content directly; do not build an API route to fetch
153
+ your own content.
154
+ - Regenerate types in the same change as the schema edit that needs them.
155
+ - Migrations are append-only once shared. Add a new one rather than editing an
156
+ applied file.
157
+
158
+ <!-- nextly:managed:end -->
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,96 @@
1
+ <!-- nextly:managed:start -->
2
+ <!--
3
+ Everything between these markers is generated by create-nextly-app and may be
4
+ replaced when the project is upgraded. Write your own notes OUTSIDE the block:
5
+ anything above or below it is yours and is preserved.
6
+ -->
7
+
8
+ # Agent guide for {{pluginName}}
9
+
10
+ A [Nextly](https://nextlyhq.com) plugin. This is a publishable **library**, not
11
+ an app: `src/` is what ships, and `dev/` is a throwaway Nextly app that exists
12
+ only so you can exercise the plugin in a real admin.
13
+
14
+ ## Where things are
15
+
16
+ | path | what it is |
17
+ | ----------------------- | ---------------------------------------------------------------- |
18
+ | `src/index.ts` | the public entry — React-free, so it stays importable on the server |
19
+ | `src/admin/index.ts` | the `./admin` subpath, where React components are registered |
20
+ | `src/plugin.ts` | the plugin factory: what it contributes and what it does on init |
21
+ | `src/collections/` | collections the plugin contributes to its host |
22
+ | `dev/` | the embedded playground: a minimal Nextly app on SQLite |
23
+ | `dist/` | the build output, and the only thing `npm publish` ships |
24
+
25
+ ## Commands
26
+
27
+ ```bash
28
+ {{runCommand}} dev # the embedded playground → http://localhost:3000/admin
29
+ {{runCommand}} test # vitest, against a real Nextly on in-memory SQLite
30
+ {{runCommand}} build # tsup → dist/
31
+ {{runCommand}} check-types # tsc --noEmit
32
+ {{runCommand}} lint # eslint
33
+ ```
34
+
35
+ `{{runCommand}} dev` runs `next dev dev` — Next.js with `dev/` as the project root.
36
+ Editing anything under `src/` reloads the playground, so the loop is the same as
37
+ working on an app.
38
+
39
+ ## Things that surprise people
40
+
41
+ - **Plugin APIs come from `@nextlyhq/plugin-sdk`; schema APIs come from
42
+ `nextly/config`.** The SDK is the stability boundary for everything a plugin
43
+ does AS a plugin: `definePlugin`, `registerComponents` and
44
+ `registerKnownPlugin` from `@nextlyhq/plugin-sdk/admin`, `createTestNextly`
45
+ from `@nextlyhq/plugin-sdk/testing`, field factories, `pluginField`,
46
+ `NextlyError`. Collections and singles are defined the same way an app defines
47
+ them, with `defineCollection` from `nextly/config` — which is what
48
+ `src/collections/example.ts` does.
49
+
50
+ **What is never supported is importing `@nextlyhq/admin` directly.** It carries
51
+ no compatibility promise to plugin authors, so an import that compiles today
52
+ breaks on a patch release. If you need something from it that the SDK does not
53
+ re-export, that is worth raising rather than reaching past the boundary.
54
+
55
+ - **The root export must stay React-free.** It is imported by the host's server
56
+ config, so a React import at `src/index.ts` breaks apps that never render your
57
+ admin UI. Components belong on the `./admin` subpath, which is where the host
58
+ looks for them.
59
+ - **Resolve your own slugs through `ctx.self`.** A host can rename a collection
60
+ your plugin contributes; `ctx.self.collections.examples` follows the rename,
61
+ a hardcoded `"examples"` does not.
62
+ - **`dev/` is never published.** `files` is `["dist"]`, so the playground can
63
+ depend on anything it likes without adding weight for consumers.
64
+ - **Peers, not dependencies.** `nextly`, `@nextlyhq/admin`,
65
+ `@nextlyhq/plugin-sdk` and React are peer dependencies — the host supplies
66
+ them, and bundling a second copy is what causes the "two Reacts" class of
67
+ failure.
68
+
69
+ ## Testing
70
+
71
+ `createTestNextly` from `@nextlyhq/plugin-sdk/testing` boots a real Nextly on
72
+ in-memory SQLite with your plugin registered, so a test exercises the same
73
+ lifecycle a host would run:
74
+
75
+ ```ts
76
+ const t = await createTestNextly({ plugins: [myPlugin()] });
77
+ ```
78
+
79
+ **Pass `plugins` alone.** Registration auto-syncs the tables for contributed
80
+ collections, so passing the same collections again as `collections` registers
81
+ those slugs a second time as code-owned entities and boot fails with
82
+ `NEXTLY_SCHEMA_SLUG_COLLISION`.
83
+
84
+ Assert on behaviour through `t.nextly` rather than on the plugin object: what a
85
+ host observes is the contract, and the object shape is not.
86
+
87
+ ## Conventions worth keeping
88
+
89
+ - Version `nextly` compatibility in the factory's `nextly` range, and widen it
90
+ deliberately rather than by default.
91
+ - Clean up in `destroy()`. Event subscriptions are dropped for you on registry
92
+ reset; timers, watchers and connections are not.
93
+ - Keep `contributes` declarative. Work belongs in `init()`, where the context is
94
+ available and failures are attributable to your plugin.
95
+
96
+ <!-- nextly:managed:end -->
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -1,13 +1,57 @@
1
1
  /**
2
- * Example plugin settings page, rendered at `/admin/plugins/<slug>` and inside
3
- * a per-component error boundary (D53). Build your real settings UI here with
4
- * `@nextlyhq/ui` components.
2
+ * Example plugin settings page, rendered at `/admin/plugins/<slug>` and wrapped in an
3
+ * error boundary, so a mistake here cannot take the admin down with it.
4
+ *
5
+ * Every class here is a design token utility, so this page follows the admin's
6
+ * theme and its light/dark modes with no styling work of its own. Build your
7
+ * real settings UI the same way.
8
+ *
9
+ * Third-party plugins are not part of the admin's Tailwind `@source` scan, so
10
+ * only the curated utilities in `plugin-safelist.css` are guaranteed to be
11
+ * compiled — layout, spacing, type, and the token-mapped colours used below.
12
+ * Anything outside that set belongs in the stylesheet your plugin declares as
13
+ * `adminStyles`, written against the `--nx-*` custom properties.
5
14
  */
6
15
  export function SettingsPage() {
7
16
  return (
8
- <div style={{ padding: 24 }}>
9
- <h1>Plugin Settings</h1>
10
- <p>Settings UI goes here. Edit src/admin/SettingsPage.tsx.</p>
17
+ <div className="w-full max-w-2xl space-y-6 p-6">
18
+ <header className="space-y-1">
19
+ <h1 className="text-xl font-semibold tracking-tight text-foreground">
20
+ Plugin Settings
21
+ </h1>
22
+ <p className="text-sm text-muted-foreground">
23
+ Settings UI goes here. Edit{" "}
24
+ <span className="font-mono text-xs">src/admin/SettingsPage.tsx</span>.
25
+ </p>
26
+ </header>
27
+
28
+ <section className="space-y-4 rounded-lg border border-border bg-card p-6">
29
+ <div className="space-y-1">
30
+ <h2 className="text-sm font-semibold text-foreground">
31
+ Where to put your fields
32
+ </h2>
33
+ <p className="text-sm leading-relaxed text-muted-foreground">
34
+ Replace this card with your own form. Group related settings under a
35
+ heading, and keep one save action for the page rather than one per
36
+ group.
37
+ </p>
38
+ </div>
39
+
40
+ <ul className="space-y-2 text-sm text-muted-foreground">
41
+ <li>
42
+ Colours come from tokens —{" "}
43
+ <span className="font-mono text-xs">bg-card</span>,{" "}
44
+ <span className="font-mono text-xs">text-muted-foreground</span>,{" "}
45
+ <span className="font-mono text-xs">border-border</span> — never
46
+ from a fixed palette shade, which would keep its light-mode
47
+ appearance in dark mode.
48
+ </li>
49
+ <li>
50
+ Spacing and radius come from the same scales the rest of the admin
51
+ uses, so your page stays aligned with it when those move.
52
+ </li>
53
+ </ul>
54
+ </section>
11
55
  </div>
12
56
  );
13
57
  }
@@ -4,7 +4,10 @@
4
4
  * admin can resolve them. The host's generated import map imports this for you;
5
5
  * the eager + lazy registration below is the fallback.
6
6
  */
7
- import { registerComponents, registerKnownPlugin } from "@nextlyhq/admin";
7
+ import {
8
+ registerComponents,
9
+ registerKnownPlugin,
10
+ } from "@nextlyhq/plugin-sdk/admin";
8
11
 
9
12
  import { SettingsPage } from "./SettingsPage";
10
13
 
@@ -6,12 +6,11 @@ import { myPlugin } from "./index";
6
6
  let t: Awaited<ReturnType<typeof createTestNextly>>;
7
7
 
8
8
  beforeEach(async () => {
9
- const plugin = myPlugin();
10
- t = await createTestNextly({
11
- plugins: [plugin],
12
- // Pass the plugin's collections so the harness creates their SQLite tables.
13
- collections: plugin.contributes?.collections,
14
- });
9
+ // `plugins` alone. Runtime auto-sync creates the tables for contributed
10
+ // collections during registration, so passing them again as `collections`
11
+ // registers the same slugs as code-owned entities and boot fails with
12
+ // NEXTLY_SCHEMA_SLUG_COLLISION.
13
+ t = await createTestNextly({ plugins: [myPlugin()] });
15
14
  });
16
15
 
17
16
  afterEach(async () => {
@@ -1,7 +1,8 @@
1
1
  import { defineConfig } from "tsup";
2
2
 
3
3
  // Builds the publishable plugin. `dev/` is NOT an entry — it never ships.
4
- // nextly / admin / react are peers, kept external.
4
+ // nextly / admin / sdk / ui / react are peers, kept external: bundling one
5
+ // would ship a second copy of code the host already provides.
5
6
  export default defineConfig({
6
7
  entry: ["src/index.ts", "src/admin/index.ts"],
7
8
  format: ["esm"],
@@ -13,6 +14,7 @@ export default defineConfig({
13
14
  "nextly",
14
15
  "@nextlyhq/admin",
15
16
  "@nextlyhq/plugin-sdk",
17
+ "@nextlyhq/ui",
16
18
  "react",
17
19
  "react-dom",
18
20
  ],