@unbase-app/cli 0.0.0-stage → 0.3.0

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/AGENTS.md ADDED
@@ -0,0 +1,38 @@
1
+ # Unbase in a site: the steps for an agent or a developer
2
+
3
+ `npx @unbase-app/cli init` adds what a fixed change can add: the packages, their lines in the
4
+ framework's config, the files they need, and the analytics collector (`https://unbase.app`) in the
5
+ Content-Security-Policy of `vercel.json` and `public/_headers`. What is left needs judgement about
6
+ this site's code, and is yours. You add code. You never move or rewrite the site's content: Unbase
7
+ edits a text where it is written, in a page, a component or a content file, so moving text into
8
+ JSON gains nothing and risks the site.
9
+
10
+ ## Your framework's steps
11
+
12
+ The steps differ per framework, and each framework has its own file next to this one. `init` names
13
+ the one for this site (in `--json`: `agents`):
14
+
15
+ | Framework | Steps |
16
+ |---|---|
17
+ | Astro | [`agents/astro.md`](./agents/astro.md), in a site: `node_modules/@unbase-app/cli/agents/astro.md` |
18
+ | Vite + React (React Router as a library) | [`agents/vite-react.md`](./agents/vite-react.md), in a site: `node_modules/@unbase-app/cli/agents/vite-react.md` |
19
+ | Next.js | [`agents/next.md`](./agents/next.md), in a site: `node_modules/@unbase-app/cli/agents/next.md` |
20
+
21
+ Unbase's CLI has no package for other frameworks yet: `init` and `doctor` stop on them with
22
+ `framework_unsupported` (exit 2). Unbase still works on such a site, without a package.
23
+
24
+ ## Check
25
+
26
+ Work through your framework's steps, run `npx @unbase-app/cli doctor`, fix what it names, and run it again
27
+ until it passes. Every finding names a file and the step in your framework's file that fixes it.
28
+ `doctor --json` gives the same as data. `missing` is yours to fix; `waiting` is outside this
29
+ repository and does not fail the run. Then commit on a new branch.
30
+
31
+ These are conventions, not an Unbase runtime: everything the steps ask for is plain code for the
32
+ framework that a developer would write, it renders the same with or without Unbase, and you can
33
+ follow it while a site is first written.
34
+
35
+ ## Leaving
36
+
37
+ `npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted, and
38
+ compares every built page before and after.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jens van der Blij
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,240 @@
1
- # Temporary Holding Version
1
+ # @unbase-app/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Adds [Unbase](https://unbase.app) to an Astro, Vite + React or Next.js site, checks it, and takes it out again.
4
+
5
+ ```bash
6
+ npx @unbase-app/cli init # the framework's package, its line in its config, comment-modus.json
7
+ npx @unbase-app/cli doctor # per feature: on, or what is missing, where, and how to fix it
8
+ npx @unbase-app/cli uninstall # all of it out again; the built pages compared before and after
9
+ ```
10
+
11
+ Always with the package's name: the unscoped `unbase` on npm is another product's package, so a
12
+ bare `npx @unbase-app/cli` outside a site that has this CLI installed would fetch that one.
13
+
14
+ Unbase works on a connected site without any of this: the canvas, comments on the canvas,
15
+ publishing, and visual editing (on Astro, nothing installed). What has to live in the site's own
16
+ code is what this adds: comments on the live site (`?comment`), page management (draft pages
17
+ kept off Live, page and site settings), and analytics (Unbase's beacon, a pageview from every page
18
+ of a production build, no cookies). The packages change how the site is edited and built, never
19
+ how it renders, but for the beacon's script, which renders nothing. The CLI itself never calls
20
+ Unbase.
21
+
22
+ Astro, Vite + React with React Router as a library (what Lovable makes: *Vite + React*, below),
23
+ and Next.js; each framework's own steps are in `agents/<framework>.md`. Node 18.17 or newer for the
24
+ CLI (comment-modus itself needs 22.12). Until 03-11-2026 this was `@unbase-app/cli`; `init` moves a
25
+ site installed with it across (*Moving from before 03-11*).
26
+
27
+ ## For a coding agent
28
+
29
+ ```
30
+ Add Unbase to this site.
31
+
32
+ 1. Run `npx @unbase-app/cli init --yes` and keep its changes.
33
+ 2. Read node_modules/@unbase-app/cli/AGENTS.md and do the steps it leaves to you.
34
+ 3. Don't move or rewrite the site's content. Unbase edits text where it is written.
35
+ 4. Run `npx @unbase-app/cli doctor` until it passes. Commit on a new branch and push it.
36
+ ```
37
+
38
+ [`AGENTS.md`](./AGENTS.md) is in the package, so the steps are pinned by the site's lockfile. It points to
39
+ the framework's own file, [`agents/astro.md`](./agents/astro.md) or
40
+ [`agents/vite-react.md`](./agents/vite-react.md), which `init` names.
41
+
42
+ ## `unbase init`
43
+
44
+ | Flag | |
45
+ |---|---|
46
+ | `--comments` / `--no-comments` | Comments on the live site, with `?comment` (`@jens4m/comment-modus`, inside `@unbase-app/astro`). Default: in, or as the site has it when Unbase is in it already |
47
+ | `--project <id or slug>` | Link comment mode and analytics to an Unbase project now (see *Linking*) |
48
+ | `--pointer[=AGENTS.md\|CLAUDE.md]` / `--no-pointer` | One line in the site's `AGENTS.md` (or `CLAUDE.md`) pointing its agent at this package's `AGENTS.md`. Default: no |
49
+ | `--no-install` | Write `package.json` only; install yourself |
50
+ | `--tarballs <dir>` | Install the packages from `npm pack` tarballs in `<dir>`, for testing a release before it is on npm |
51
+ | `--yes` | The default for every choice not given |
52
+ | `--json`, `--dir <path>` | Output for programs; the site's folder (default: here) |
53
+
54
+ It adds, with the site's own package manager (npm, pnpm or yarn, from its lockfile), at these
55
+ versions:
56
+
57
+ | Package | Version | |
58
+ |---|---|---|
59
+ | `@unbase-app/astro` | 0.2.0 | Unbase in an Astro site, one integration: comment mode (`@jens4m/comment-modus` 1.9.0: comments on the live site; it writes the content schemas Unbase reads), the draft-pages kit (`@unbase-app/pages` 0.3.0: draft pages kept out of production builds) and the analytics beacon (`@unbase-app/analytics` 0.1.0) |
60
+ | `@unbase-app/cli` | this one | devDependency: `AGENTS.md` and `doctor`, pinned |
61
+
62
+ In `astro.config`, found and changed through its syntax tree, never by text substitution:
63
+
64
+ ```js
65
+ import unbase from "@unbase-app/astro";
66
+ import commentModusConfig from "./comment-modus.json";
67
+ // …
68
+ integrations: [
69
+ // …the site's own
70
+ unbase({ project: commentModusConfig.project, layerUrl: "https://layer.unbase.app/v1/loader.js", edit: true }),
71
+ ],
72
+ ```
73
+
74
+ `unbase()` adds comment mode and the kit after every other integration itself, so the kit runs last
75
+ wherever the line stands. Its options are comment mode's own; `--no-comments` writes
76
+ `unbase({ comments: false })`, and `init --comments` later turns it on in the same line.
77
+
78
+ A config it cannot change with certainty (CommonJS, no `export default`, `integrations` that is not
79
+ an array literal, a spread that may hold it) stops the run with the file named and nothing changed.
80
+ A package that is already there at an older version is moved up to the pinned one, so running
81
+ init again is also how a site updates; a newer one is kept and reported, never moved down. A
82
+ second run changes nothing. It touches no content.
83
+
84
+ ### Vite + React
85
+
86
+ One package, `@unbase-app/vite` (a devDependency, beside `vite`), at 0.2.0: the draft-pages kit, the analytics beacon and
87
+ comment mode's loader in one Vite plugin. In `vite.config`, through its syntax tree (Lovable's
88
+ `defineConfig(({ mode }) => ({ … }))` and `plugins: [ … ].filter(Boolean)` included):
89
+
90
+ ```ts
91
+ import { unbase } from "@unbase-app/vite";
92
+ // …
93
+ plugins: [react(), mode === "development" && componentTagger(), unbase()].filter(Boolean),
94
+ ```
95
+
96
+ `--no-comments` writes `unbase({ comments: false })`; `init --comments` later takes that option
97
+ out again. A config with the kit's own Vite plugin (`unbasePages()` from
98
+ `@jens4m/unbase-pages/vite`) gets `unbase()` in its place. The plugin reads `comment-modus.json`
99
+ itself, so the config does not import it. A Vite app keeps its site settings in `index.html`, which
100
+ Unbase reads and writes as it is; it has no page settings, so nothing is written for them.
101
+
102
+ ### Next.js
103
+
104
+ On a Next.js site `init` adds `@unbase-app/next` (0.2.0) and wraps the config `next.config` hands Next.js in
105
+ `withUnbase(…)` (through its syntax tree; a CommonJS config gets the `require`), writes
106
+ `comment-modus.json`, and on a Next.js from 15.3 to 16.2 imports the comments' loader in
107
+ `instrumentation-client.ts` (from 16.3 `withUnbase` injects it). `doctor` builds with `next build`
108
+ into the site's own `.next` and reads it; page settings need nothing installed (each page's
109
+ `export const metadata`), so it lists which pages Unbase can set and why not the others.
110
+ `uninstall` takes it all out and compares the prerendered pages, with Next.js's scripts and hashed
111
+ asset names left out. The steps: [`agents/next.md`](./agents/next.md).
112
+
113
+ ### Analytics
114
+
115
+ The beacon comes with the framework's package, on by default (`@unbase-app/analytics`): every page
116
+ of a production build sends a pageview to Unbase once the site is linked, never in a dev server.
117
+ `analytics: false` in the package's call (`unbase({ … })`, `withUnbase(nextConfig, { … })`) leaves
118
+ it out; init never writes that, and keeps it when a site has it.
119
+
120
+ What init adds for it is the collector's origin, `https://unbase.app`, in `connect-src` wherever
121
+ the site sets a Content-Security-Policy it can edit safely: `vercel.json`'s `headers` and
122
+ `public/_headers` (Netlify, Cloudflare Pages), each value changed in place and the rest of the file
123
+ as it was; with no `connect-src`, one made of `default-src`'s sources and the origin. A CSP set
124
+ anywhere else (next.config's `headers()`, a middleware, a `<meta http-equiv>`, `netlify.toml`,
125
+ Astro's `csp` option) is named in `next` and `csp.elsewhere`, never edited. `uninstall` takes the
126
+ origin out of the two files again, to the letter. The reading and the editing are Unbase's own
127
+ (`lib/readers.mjs`, `csp`), the same code `read_install` uses for its Analytics row.
128
+
129
+ On Astro and Vite the package reads `comment-modus.json` itself, so `--no-comments` still writes
130
+ it for analytics, and `--project` links analytics alone. On Next.js the beacon comes with the
131
+ comments' client module: one link for both, and `--no-comments` leaves both out.
132
+
133
+ ### Linking
134
+
135
+ comment mode and analytics need the site's Unbase project, which a site added before Unbase knows it
136
+ does not have yet. So init writes `comment-modus.json` with `"project": null`, and the config only
137
+ turns comment mode (and analytics) on once that file names the project: until then the site builds
138
+ and renders as before.
139
+ Unbase fills the value in when the site is connected (one JSON value, never a change to the
140
+ config), or `init --project <id>` does. `comment-modus.json` is the same file comment-modus's own
141
+ CLI reads.
142
+
143
+ A config that sets comment mode up itself, with its own `project` (a site that had comment mode
144
+ before init existed), keeps it: `init --project` with that same project changes nothing there and
145
+ writes no `comment-modus.json`; another project is refused, to be changed in the config by a person.
146
+
147
+ ### Moving from before 03-11
148
+
149
+ A site installed before 03-11-2026 has the pair, `@jens4m/comment-modus` and `@jens4m/unbase-pages`
150
+ with `commentModus()` and `unbasePages()` in its config, and the CLI as `@unbase-app/cli`. `init`
151
+ moves it across, and it is how Unbase's Update does it:
152
+
153
+ - `@unbase-app/astro` and `@unbase-app/cli` in; `@jens4m/unbase-pages` and `@unbase-app/cli` out
154
+ (`removed`, with `replacedBy`, in `--json`): written to `package.json` together and installed in
155
+ one run, so the `unbase` bin both CLIs have is the new one's. A failed install puts
156
+ `package.json` back, and nothing else has changed yet.
157
+ - `unbase()` takes `commentModus()`'s place with its options as they are (a site's own `project`,
158
+ `titles`, `language`…); the `commentModusConfig.project ? … : null` init wrote around it goes,
159
+ since `unbase()` waits for the project itself. `unbasePages()` and its import go.
160
+ - `@jens4m/comment-modus` goes too, unless the site uses it for itself: a name its config still
161
+ imports from it, its CLI in a script or a workflow. Then it stays, moved to the version
162
+ `@unbase-app/astro` brings, so there is one.
163
+ - The pointer line moves to `node_modules/@unbase-app/cli/AGENTS.md`.
164
+ - With `--yes`, a site keeps its choice of comments. A second run changes nothing.
165
+
166
+ `doctor` passes on a site from before as it is, and says the move is there (`moved`, info).
167
+
168
+ ## `unbase doctor`
169
+
170
+ Builds the site once (production, into a folder of its own), then reads it with Unbase's own
171
+ readers, the code the Edge Functions run, bundled into this package. Per feature it gives a state
172
+ and per check what is missing, the file, and the step in `agents/astro.md` that fixes it.
173
+
174
+ | Check state | |
175
+ |---|---|
176
+ | `ok` | Works |
177
+ | `missing` | The site has to change. Fails the run |
178
+ | `waiting` | Outside this repository: Unbase linking the project, or a package release. Named, does not fail the run |
179
+ | `info` | Worth knowing |
180
+ | `skipped` | Not checked (`--no-build`, or a build that failed) |
181
+
182
+ Features: **Visual editing** (Astro, the site builds), **Comments on the site** (the package, its
183
+ line, the link, the markers, the loader), **Page management** (the kit, the drafts in
184
+ `unbase.pages.json`, the kit running in a production build, the content schemas, the route files
185
+ and the site settings and that the layout reads them), **Analytics** (the package at a version that
186
+ brings it, not `analytics: false`, the link, before Next.js 16.3 the client module's import, and the
187
+ CSP of `vercel.json` and `public/_headers` allowing `https://unbase.app`; a CSP set elsewhere is
188
+ named as `info`). `--no-build` skips the build and what needs it.
189
+
190
+ The markers are comment mode's `data-c`: a pin on the live site takes its title and source file
191
+ from them, so with comments they belong in the production build. A site without comment mode, or
192
+ whose `unbase()` says `componentMarker: "preview"` (comment-modus 1.9.0: markers in the dev
193
+ server and previews only) or `false`, must have none there; `doctor` fails when it does, and names
194
+ an older comment-modus that ignores `"preview"`.
195
+
196
+ ## `unbase uninstall`
197
+
198
+ Refuses while `unbase.pages.json` holds a draft, and lists them: without the kit a draft is built
199
+ and goes live, so each is published or deleted in Unbase first. Then it builds the site, removes
200
+ the packages, their lines in `astro.config`, `comment-modus.json`, `unbase.pages.json`,
201
+ `src/content/.schemas/`, the collector in the CSP of `vercel.json` and `public/_headers`, and the
202
+ pointer line, builds again, and compares every page's HTML. Taken out first: comment mode's markers
203
+ and loader, the analytics beacon, and what differs between any two builds (asset
204
+ hashes, Astro's ids, white space, attribute order). When pages still differ it builds the after
205
+ state once more, and what differs between those two builds (an id a component makes at random on
206
+ every render) is noise, not a change. "No differences in the built pages" is the pass. `--yes` without
207
+ a terminal; `--no-build` skips the comparison; `--no-install` writes `package.json` only.
208
+
209
+ The route files, the settings file and the layout's reads stay: they are the site's own code.
210
+
211
+ ## For programs
212
+
213
+ - **Never asks without a terminal.** A choice without its flag is an error (exit 2) naming the
214
+ flags; `--json` never asks.
215
+ - **`--json`** on every command. `init`: `packages` (name, the pinned `version`, dev, and `action`:
216
+ `added`, `updated` with `from` and `to`, or `kept`, with a `note` when the one there is newer)
217
+ and `files` (file, `created`, `changed` or `removed`, and the changes; the lockfile too when
218
+ the package manager ran); `analytics` (on, unless the config says `analytics: false`) and `csp`
219
+ (`files` it allowed the collector in, `invalid` ones it could not read, and `elsewhere`: each
220
+ `{ file, why }` that may set a CSP it does not edit). `doctor`: `features`, each
221
+ with `state` (`on`, `off`, `waiting`, `not-installed`) and `checks` (`id`, `state`, `message`,
222
+ and for a `missing` or `waiting` check `missing`, `file`, `step`). `uninstall`: `files`
223
+ (every file it touched, the lockfile included), `packages`, `comparison` (`pages`,
224
+ `differences`, `secondBuild`), or `refused: "drafts"` with `drafts`.
225
+ An error: `{ ok: false, exitCode: 2, error: { code, message, file? } }`.
226
+ - **Exit codes:** `0` passed, `1` failed (doctor found something missing; uninstall refused or
227
+ found a difference), `2` could not run (usage, no Astro site, a config it cannot edit safely, an
228
+ install that failed).
229
+ - **No login, no project, no network** beyond the package manager's install: it never calls Unbase,
230
+ and the versions are pinned.
231
+
232
+ ## Developing
233
+
234
+ Part of the kit (`kit/` in Unbase's repository; see its README): `npm test` there runs every
235
+ package's tests. `lib/readers.mjs` is generated from the Edge Functions' readers (`detect.ts`,
236
+ `settings.ts`, `pages.ts`, the kit's core), which live in Unbase's repository: after changing one of
237
+ them, `node kit/cli/scripts/readers.mjs`; the tests fail there while it is out of date. In the kit
238
+ on its own the file ships as it was generated.
239
+
240
+ MIT licence.
@@ -0,0 +1,179 @@
1
+ # Unbase in an Astro site: the steps for an agent or a developer
2
+
3
+ `npx @unbase-app/cli init` adds what a fixed change can add: the package, its line in
4
+ `astro.config`, and `comment-modus.json`. What is left needs judgement about this site's code, and
5
+ is yours. You add code. You never move or rewrite the site's content: Unbase edits a text where it
6
+ is written, in a page, a component or a content file, so moving text into JSON gains nothing and
7
+ risks the site.
8
+
9
+ Work through the steps, run `npx @unbase-app/cli doctor`, fix what it names, and run it again until it
10
+ passes. Every finding names a file and the step below that fixes it. `doctor --json` gives the
11
+ same as data.
12
+
13
+ These are conventions, not an Unbase runtime: everything here is plain Astro that a developer
14
+ would write, it renders the same with or without Unbase, and you can follow it while a site is
15
+ first written.
16
+
17
+ ## 1. Install
18
+
19
+ `npx @unbase-app/cli init` (add `--yes` without a terminal). It is safe to run again: a second run
20
+ changes nothing, and a package that is older than the version init pins is moved up to it. It adds:
21
+
22
+ - `@unbase-app/astro`, and one entry in `integrations`, `unbase({ … })`. It brings comment mode
23
+ (`@jens4m/comment-modus`: comments on the live site with `?comment`; it also writes the content
24
+ schemas, step 4) and the draft-pages kit (`@unbase-app/pages`), and adds both after every other
25
+ integration itself. Its options are comment mode's own. `--no-comments` writes
26
+ `unbase({ comments: false })`, which leaves comment mode out, and with it page and site settings.
27
+ - `comment-modus.json` with `"project": null`, which `unbase({ project: commentModusConfig.project, … })`
28
+ reads. Unbase fills in the project when the site is connected; until then comment mode stays
29
+ off. Do not invent a value.
30
+ - `@unbase-app/cli` as a devDependency, so this file and `doctor` are pinned by the lockfile.
31
+
32
+ A site installed before 03-11 has the pair instead (`@jens4m/comment-modus` and
33
+ `@jens4m/unbase-pages`, `commentModus()` and `unbasePages()`) and the CLI as `@jens4m/unbase`. init
34
+ moves it across: `unbase()` takes `commentModus()`'s place with its options as they are, and the old
35
+ packages go. A site that imports something of comment-modus for itself, or runs its CLI, keeps it.
36
+
37
+ If init says it cannot edit `astro.config` safely, make the same change by hand: import `unbase`
38
+ from `@unbase-app/astro` and `commentModusConfig` from `./comment-modus.json`, and add
39
+ `unbase({ project: commentModusConfig.project, layerUrl: "https://layer.unbase.app/v1/loader.js", edit: true })`
40
+ to `integrations`.
41
+
42
+ ## 2. Page settings: one route file per page
43
+
44
+ Unbase sets a page's title, description, share image and indexing in a JSON file for that route,
45
+ which the layout reads before its own defaults. Unbase finds the collection by its shape: a schema
46
+ with `pad` and `seo`.
47
+
48
+ 1. A collection in `src/content.config.ts`, JSON files under `src/content/`:
49
+
50
+ ```ts
51
+ import { defineCollection } from "astro:content";
52
+ import { glob } from "astro/loaders";
53
+ import { z } from "astro/zod"; // or "astro:content", as the site already does
54
+
55
+ const seo = defineCollection({
56
+ loader: glob({ pattern: "*.json", base: "src/content/seo" }),
57
+ schema: z.object({
58
+ pad: z.string(),
59
+ seo: z
60
+ .object({
61
+ titel: z.string().optional(),
62
+ beschrijving: z.string().optional(),
63
+ ogImage: z.string().optional(),
64
+ noindex: z.boolean().optional(),
65
+ zoeken: z.boolean().optional(),
66
+ })
67
+ .optional(),
68
+ }),
69
+ });
70
+ export const collections = { /* the site's own */ seo };
71
+ ```
72
+
73
+ The field names are the ones Unbase reads today. Keep them.
74
+
75
+ 2. One file per route the site has, named after the route: `/` is `home.json`, `/about` is
76
+ `about.json`, `/landing/sales` is `landing-sales.json`. Start each with what is in the code
77
+ now, or empty: `{ "pad": "/about", "seo": {} }`. An empty `seo` is fine: the layout falls back
78
+ to what the page says. A route without a file gets one the first time its settings are
79
+ published, but at least one file has to exist for the collection to count.
80
+
81
+ 3. The layout reads it, before its own values. In the component that writes `<title>` and the
82
+ meta tags:
83
+
84
+ ```astro
85
+ ---
86
+ import { getCollection } from "astro:content";
87
+ const here = Astro.url.pathname.replace(/\/+$/, "") || "/";
88
+ const route = (await getCollection("seo")).find((e) => e.data.pad === here)?.data.seo;
89
+ const title = route?.titel || Astro.props.title; // the page's own title stays the default
90
+ const description = route?.beschrijving || Astro.props.description;
91
+ const noindex = route?.noindex ?? false;
92
+ ---
93
+ ```
94
+
95
+ Use the values where the layout already writes them (`<title>`, `meta name="description"`,
96
+ `og:image`, `robots`). Don't remove the page's own titles: they stay the default.
97
+
98
+ ## 3. Site settings: one file for the site
99
+
100
+ The site's name, description, language, favicons, share image and analytics id, in one file.
101
+ Unbase finds it by a mark on the collection's schema.
102
+
103
+ 1. A collection marked `"x-instellingen": "site"`:
104
+
105
+ ```ts
106
+ const site = defineCollection({
107
+ loader: glob({ pattern: "*.json", base: "src/content/site" }),
108
+ schema: z
109
+ .object({
110
+ naam: z.string().optional(),
111
+ beschrijving: z.string().optional(),
112
+ taal: z.string().optional(),
113
+ favicon: z.string().optional(),
114
+ faviconDonker: z.string().optional(),
115
+ ogImage: z.string().optional(),
116
+ googleAnalytics: z.string().optional(),
117
+ })
118
+ .meta({ "x-instellingen": "site" }),
119
+ });
120
+ ```
121
+
122
+ 2. One file, `src/content/site/settings.json`. It may start as `{}`: a field the schema allows
123
+ counts. Don't copy the site's values into it; they stay where they are.
124
+
125
+ 3. The layout reads it before its own defaults, as in step 2:
126
+ `const settings = (await getEntry("site", "settings"))?.data;` then `settings?.naam || SITE.name`,
127
+ and so on for the fields the site has (language on `<html lang>`, favicons, the analytics id).
128
+
129
+ ## 4. Schemas
130
+
131
+ Unbase reads the collections' JSON Schemas from `src/content/.schemas/`, committed with the site.
132
+ comment-modus copies them there from Astro's own output on every build and dev run, once it is
133
+ linked to a project (step 1); only collections with files are copied. After steps 2 and 3: run
134
+ `npx @unbase-app/cli doctor` (it builds the site), or `npm run build`, and commit `src/content/.schemas/`.
135
+ Commit them again whenever `content.config` changes.
136
+
137
+ ## 5. Draft pages
138
+
139
+ Nothing to add: `unbase()` brings the kit, which keeps every page Unbase marks as a draft (in
140
+ `unbase.pages.json`, which Unbase writes) out of production builds, and stops the build when it
141
+ cannot. It runs after every other integration by itself; don't add `unbasePages()` beside it. A page
142
+ that cannot be a draft (a dynamic route, a page another file imports) is fine; doctor lists them.
143
+
144
+ ## 6. Analytics
145
+
146
+ Nothing to add for the beacon itself: the package brings it, on by default, and every page of a
147
+ production build sends a pageview to Unbase once the site is linked to its project (no cookies,
148
+ nothing stored on the visitor's device; never in the dev server). `analytics: false` in `unbase({ … })`
149
+ leaves it out; keep that only if the site's owner asked for it.
150
+
151
+ What can stop it is the site's own **Content-Security-Policy**: the beacon posts to
152
+ `https://unbase.app`, so a CSP needs that origin in `connect-src` (or in `default-src` when there
153
+ is no `connect-src`). `init` adds it where the site sets the CSP in `vercel.json` (its `headers`) or
154
+ `public/_headers`, and doctor checks both. A CSP set anywhere else (next.config's `headers()`, a
155
+ middleware, a `<meta http-equiv>`, `netlify.toml`, Astro's own `csp` option) is yours: doctor names the file; add
156
+ `https://unbase.app` to its `connect-src`, and change nothing else in it.
157
+ The beacon is bundled with the site's own page scripts, so `script-src` needs nothing new.
158
+
159
+ ## 7. Check
160
+
161
+ `npx @unbase-app/cli doctor` builds the site once and says, per feature, what Unbase will say:
162
+
163
+ - **Visual editing**: nothing to install on Astro; the site has to build.
164
+ - **Comments on the site**: the package, its line, the link to a project, the markers (`data-c`:
165
+ in the production build with comments; none without comment mode, or with
166
+ `componentMarker: "preview"` in `unbase()`).
167
+ - **Page management**: the kit, the drafts, the route files and the site settings, and that the
168
+ layout reads them.
169
+ - **Analytics**: the package new enough, not `analytics: false`, the link to a project, and the
170
+ CSP allowing `https://unbase.app`.
171
+
172
+ `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
173
+ package release) and does not fail the run. Then commit on a new branch.
174
+
175
+ ## Leaving
176
+
177
+ `npx @unbase-app/cli uninstall` takes out what init added (the collector in the CSP too), after the drafts
178
+ are published or deleted, and compares every built page before and after. The route files, the settings file and the layout's
179
+ reads stay: they are the site's own code and keep working.
package/agents/next.md ADDED
@@ -0,0 +1,129 @@
1
+ # Unbase in a Next.js site: the steps for an agent or a developer
2
+
3
+ `npx @unbase-app/cli init` adds what a fixed change can add: `@unbase-app/next`, `withUnbase(…)`
4
+ around the config in `next.config`, `comment-modus.json`, and on a Next.js before 16.3 the import
5
+ of the comments' loader. What is left needs judgement about this site's code, and is yours. You add
6
+ code. You never move or rewrite the site's content: Unbase edits a text where it is written, in a
7
+ page, a component or a content file, so moving text into JSON gains nothing and risks the site.
8
+
9
+ Work through the steps, run `npx @unbase-app/cli doctor`, fix what it names, and run it again until it
10
+ passes. Every finding names a file and the step below that fixes it. `doctor --json` gives the
11
+ same as data.
12
+
13
+ These are conventions, not an Unbase runtime: everything here is plain Next.js that a developer
14
+ would write, it renders the same with or without Unbase, and you can follow it while a site is
15
+ first written.
16
+
17
+ ## 1. Install
18
+
19
+ `npx @unbase-app/cli init` (add `--yes` without a terminal). It is safe to run again: a second run
20
+ changes nothing, and a package older than the version init pins is moved up to it. It adds:
21
+
22
+ - `@unbase-app/next`, and `withUnbase(…)` around what `next.config` hands Next.js:
23
+
24
+ ```ts
25
+ import type { NextConfig } from "next";
26
+ import { withUnbase } from "@unbase-app/next";
27
+
28
+ const nextConfig: NextConfig = {
29
+ // the site's own
30
+ };
31
+
32
+ export default withUnbase(nextConfig);
33
+ ```
34
+
35
+ A CommonJS `next.config.js` gets `const { withUnbase } = require("@unbase-app/next");` and
36
+ `module.exports = withUnbase(…)`. A config that is a function of the phase is wrapped the same.
37
+ - `comment-modus.json` with `"project": null`. Unbase fills in the project when the site is
38
+ connected; until then comments stay off. Do not invent a value. `--no-comments` leaves the file
39
+ out, and comments with it.
40
+ - `@unbase-app/cli` as a devDependency, so this file and `doctor` are pinned by the lockfile.
41
+
42
+ If init says it cannot edit `next.config` safely, make the same change by hand: the import, and
43
+ `withUnbase(…)` around the exported config.
44
+
45
+ `doctor` and `uninstall` build the site with `next build`, into its own `.next`.
46
+
47
+ ## 2. Comments on the site
48
+
49
+ On Next.js 16.3 and later there is nothing to add: `withUnbase` puts the `?comment` loader on every
50
+ page. It loads nothing for a visitor, only for someone who opens the page with `?comment`.
51
+
52
+ - Next.js 15.3 to 16.2: init writes the import in `instrumentation-client.ts` (in `src/` when the
53
+ app is in `src/app`). Keep it as the file's first line: `import "@unbase-app/next/comments";`.
54
+ - Older than 15.3: render the loader from the root layout with a client component of your own
55
+ that imports it once (`"use client"; import "@unbase-app/next/comments"; export function
56
+ Comments() { return null; }`), placed in `<body>`.
57
+
58
+ Comments find Unbase's backend through `PUBLIC_SUPABASE_URL` and `PUBLIC_SUPABASE_ANON_KEY` (or the
59
+ `NEXT_PUBLIC_` names) where the site is built. Unbase's Vercel integration sets them; on another host,
60
+ set them there. A site with a Content Security Policy allows `https://layer.unbase.app` in
61
+ `script-src`, the Supabase project and `data:` in `connect-src`.
62
+
63
+ ## 3. Page settings
64
+
65
+ Nothing to install: Unbase sets a page's title, description, share image and noindex in its own
66
+ `export const metadata = { … }` (app router), and the site's name, description, share image and
67
+ language in the root layout's metadata and `<html lang>`. It writes only the value that changes,
68
+ where it is written. A page without metadata gets `export const metadata` the first time its
69
+ settings are published.
70
+
71
+ What it cannot set, `doctor` lists, and that is fine:
72
+
73
+ - `generateMetadata`, and values built in code (`` title: `${name} | Site` ``, a constant, a call):
74
+ they stay code. Where a page's title is fixed text, a literal is what Unbase can set
75
+ (`title: "Prices"`). Don't turn text that comes from a CMS or from data into literals.
76
+ - A client component's page (`"use client"`), which Next.js gives no metadata, and the pages router
77
+ (`next/head`).
78
+ - A share image drawn by `opengraph-image.tsx` beside the page.
79
+
80
+ Unbase puts a new picture in `public/images/` and names it `/images/…` in the metadata.
81
+
82
+ ## 4. Draft pages
83
+
84
+ Nothing to add: `withUnbase` keeps every page Unbase marks as a draft (in `unbase.pages.json`, which
85
+ Unbase writes) out of production builds, and stops the build when it cannot. A page that cannot be
86
+ a draft is fine; doctor lists them with the reason:
87
+
88
+ - Home, and a dynamic route (`[slug]`): its pages are its data's, keep them off the site there;
89
+ - a page another file imports, or JSON content another file reads too;
90
+ - a page whose folder has its own `layout`, `loading`, `error`, `not-found` or `template`, or an
91
+ `opengraph-image`, `icon`, `route` or `sitemap`: Next.js renders them with the page or serves them
92
+ on their own;
93
+ - a site that writes its page list after the build with `next-sitemap`: use an app router
94
+ `sitemap.ts` (one `export default`), which `withUnbase` cleans.
95
+
96
+ Drafts need Next.js 15.4 or later (the check after the compile).
97
+
98
+ ## 5. Analytics
99
+
100
+ Nothing to add for the beacon itself: the package brings it, on by default, and every page of a
101
+ production build sends a pageview to Unbase once the site is linked to its project (no cookies,
102
+ nothing stored on the visitor's device; never in the dev server). `analytics: false` in `withUnbase(nextConfig, { analytics: false })`
103
+ leaves it out; keep that only if the site's owner asked for it.
104
+
105
+ What can stop it is the site's own **Content-Security-Policy**: the beacon posts to
106
+ `https://unbase.app`, so a CSP needs that origin in `connect-src` (or in `default-src` when there
107
+ is no `connect-src`). `init` adds it where the site sets the CSP in `vercel.json` (its `headers`) or
108
+ `public/_headers`, and doctor checks both. A CSP set anywhere else (next.config's `headers()`, a
109
+ middleware, a `<meta http-equiv>`, `netlify.toml`) is yours: doctor names the file; add
110
+ `https://unbase.app` to its `connect-src`, and change nothing else in it.
111
+ The beacon comes with the comments' client module (step 2), so it needs the same link to a project
112
+ and, before Next.js 16.3, the same import in `instrumentation-client`: on Next.js, a site without
113
+ comments on the live site has no analytics either. It is bundled into the site's own chunks, so
114
+ `script-src` needs nothing new.
115
+
116
+ ## 6. Check
117
+
118
+ `npx @unbase-app/cli doctor` builds the site once and says, per feature, what Unbase will say:
119
+
120
+ - **Visual editing**: nothing to install on Next.js; the site has to build.
121
+ - **Comments on the site**: the package, its wrapper in `next.config`, the link to a project, the
122
+ loader on the page and in the build.
123
+ - **Page management**: the package, the drafts, `withUnbase` running in a production build, which
124
+ pages can be drafts, and which pages' settings Unbase can set.
125
+ - **Analytics**: the package new enough, not `analytics: false`, the link to a project, the client
126
+ module on the page, and the CSP allowing `https://unbase.app`.
127
+
128
+ `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
129
+ package release) and does not fail the run. Then commit on a new branch.