@unbase-app/cli 0.0.0-stage → 0.2.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,37 @@
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, and the files they need. What is left needs judgement about this site's code,
5
+ and is yours. You add code. You never move or rewrite the site's content: Unbase edits a text where
6
+ it 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
+ ## Your framework's steps
10
+
11
+ The steps differ per framework, and each framework has its own file next to this one. `init` names
12
+ the one for this site (in `--json`: `agents`):
13
+
14
+ | Framework | Steps |
15
+ |---|---|
16
+ | Astro | [`agents/astro.md`](./agents/astro.md), in a site: `node_modules/@unbase-app/cli/agents/astro.md` |
17
+ | 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` |
18
+ | Next.js | [`agents/next.md`](./agents/next.md), in a site: `node_modules/@unbase-app/cli/agents/next.md` |
19
+
20
+ Unbase's CLI has no package for other frameworks yet: `init` and `doctor` stop on them with
21
+ `framework_unsupported` (exit 2). Unbase still works on such a site, without a package.
22
+
23
+ ## Check
24
+
25
+ Work through your framework's steps, run `npx @unbase-app/cli doctor`, fix what it names, and run it again
26
+ until it passes. Every finding names a file and the step in your framework's file that fixes it.
27
+ `doctor --json` gives the same as data. `missing` is yours to fix; `waiting` is outside this
28
+ repository and does not fail the run. Then commit on a new branch.
29
+
30
+ These are conventions, not an Unbase runtime: everything the steps ask for is plain code for the
31
+ framework that a developer would write, it renders the same with or without Unbase, and you can
32
+ follow it while a site is first written.
33
+
34
+ ## Leaving
35
+
36
+ `npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted, and
37
+ 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,212 @@
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`), and page management (draft pages
17
+ kept off Live, page and site settings). The packages change how the site is edited and built, never
18
+ how it renders, and nothing here calls Unbase.
19
+
20
+ Astro, Vite + React with React Router as a library (what Lovable makes: *Vite + React*, below),
21
+ and Next.js; each framework's own steps are in `agents/<framework>.md`. Node 18.17 or newer for the
22
+ CLI (comment-modus itself needs 22.12). Until 03-11-2026 this was `@unbase-app/cli`; `init` moves a
23
+ site installed with it across (*Moving from before 03-11*).
24
+
25
+ ## For a coding agent
26
+
27
+ ```
28
+ Add Unbase to this site.
29
+
30
+ 1. Run `npx @unbase-app/cli init --yes` and keep its changes.
31
+ 2. Read node_modules/@unbase-app/cli/AGENTS.md and do the steps it leaves to you.
32
+ 3. Don't move or rewrite the site's content. Unbase edits text where it is written.
33
+ 4. Run `npx @unbase-app/cli doctor` until it passes. Commit on a new branch and push it.
34
+ ```
35
+
36
+ [`AGENTS.md`](./AGENTS.md) is in the package, so the steps are pinned by the site's lockfile. It points to
37
+ the framework's own file, [`agents/astro.md`](./agents/astro.md) or
38
+ [`agents/vite-react.md`](./agents/vite-react.md), which `init` names.
39
+
40
+ ## `unbase init`
41
+
42
+ | Flag | |
43
+ |---|---|
44
+ | `--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 |
45
+ | `--project <id or slug>` | Link comment mode to an Unbase project now (see *Linking*) |
46
+ | `--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 |
47
+ | `--no-install` | Write `package.json` only; install yourself |
48
+ | `--tarballs <dir>` | Install the packages from `npm pack` tarballs in `<dir>`, for testing a release before it is on npm |
49
+ | `--yes` | The default for every choice not given |
50
+ | `--json`, `--dir <path>` | Output for programs; the site's folder (default: here) |
51
+
52
+ It adds, with the site's own package manager (npm, pnpm or yarn, from its lockfile), at these
53
+ versions:
54
+
55
+ | Package | Version | |
56
+ |---|---|---|
57
+ | `@unbase-app/astro` | 0.1.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) and the draft-pages kit (`@unbase-app/pages` 0.3.0: draft pages kept out of production builds) |
58
+ | `@unbase-app/cli` | this one | devDependency: `AGENTS.md` and `doctor`, pinned |
59
+
60
+ In `astro.config`, found and changed through its syntax tree, never by text substitution:
61
+
62
+ ```js
63
+ import unbase from "@unbase-app/astro";
64
+ import commentModusConfig from "./comment-modus.json";
65
+ // …
66
+ integrations: [
67
+ // …the site's own
68
+ unbase({ project: commentModusConfig.project, layerUrl: "https://layer.unbase.app/v1/loader.js", edit: true }),
69
+ ],
70
+ ```
71
+
72
+ `unbase()` adds comment mode and the kit after every other integration itself, so the kit runs last
73
+ wherever the line stands. Its options are comment mode's own; `--no-comments` writes
74
+ `unbase({ comments: false })`, and `init --comments` later turns it on in the same line.
75
+
76
+ A config it cannot change with certainty (CommonJS, no `export default`, `integrations` that is not
77
+ an array literal, a spread that may hold it) stops the run with the file named and nothing changed.
78
+ A package that is already there at an older version is moved up to the pinned one, so running
79
+ init again is also how a site updates; a newer one is kept and reported, never moved down. A
80
+ second run changes nothing. It touches no content.
81
+
82
+ ### Vite + React
83
+
84
+ One package, `@unbase-app/vite` (a devDependency, beside `vite`), at 0.1.0: the draft-pages kit and
85
+ comment mode's loader in one Vite plugin. In `vite.config`, through its syntax tree (Lovable's
86
+ `defineConfig(({ mode }) => ({ … }))` and `plugins: [ … ].filter(Boolean)` included):
87
+
88
+ ```ts
89
+ import { unbase } from "@unbase-app/vite";
90
+ // …
91
+ plugins: [react(), mode === "development" && componentTagger(), unbase()].filter(Boolean),
92
+ ```
93
+
94
+ `--no-comments` writes `unbase({ comments: false })`; `init --comments` later takes that option
95
+ out again. A config with the kit's own Vite plugin (`unbasePages()` from
96
+ `@jens4m/unbase-pages/vite`) gets `unbase()` in its place. The plugin reads `comment-modus.json`
97
+ itself, so the config does not import it. A Vite app keeps its site settings in `index.html`, which
98
+ Unbase reads and writes as it is; it has no page settings, so nothing is written for them.
99
+
100
+ ### Next.js
101
+
102
+ On a Next.js site `init` adds `@unbase-app/next` and wraps the config `next.config` hands Next.js in
103
+ `withUnbase(…)` (through its syntax tree; a CommonJS config gets the `require`), writes
104
+ `comment-modus.json`, and on a Next.js from 15.3 to 16.2 imports the comments' loader in
105
+ `instrumentation-client.ts` (from 16.3 `withUnbase` injects it). `doctor` builds with `next build`
106
+ into the site's own `.next` and reads it; page settings need nothing installed (each page's
107
+ `export const metadata`), so it lists which pages Unbase can set and why not the others.
108
+ `uninstall` takes it all out and compares the prerendered pages, with Next.js's scripts and hashed
109
+ asset names left out. The steps: [`agents/next.md`](./agents/next.md).
110
+
111
+ ### Linking
112
+
113
+ comment mode needs the site's Unbase project, which a site added before Unbase knows it does not
114
+ have yet. So init writes `comment-modus.json` with `"project": null`, and the config only turns
115
+ comment mode on once that file names the project: until then the site builds and renders as before.
116
+ Unbase fills the value in when the site is connected (one JSON value, never a change to the
117
+ config), or `init --project <id>` does. `comment-modus.json` is the same file comment-modus's own
118
+ CLI reads.
119
+
120
+ A config that sets comment mode up itself, with its own `project` (a site that had comment mode
121
+ before init existed), keeps it: `init --project` with that same project changes nothing there and
122
+ writes no `comment-modus.json`; another project is refused, to be changed in the config by a person.
123
+
124
+ ### Moving from before 03-11
125
+
126
+ A site installed before 03-11-2026 has the pair, `@jens4m/comment-modus` and `@jens4m/unbase-pages`
127
+ with `commentModus()` and `unbasePages()` in its config, and the CLI as `@unbase-app/cli`. `init`
128
+ moves it across, and it is how Unbase's Update does it:
129
+
130
+ - `@unbase-app/astro` and `@unbase-app/cli` in; `@jens4m/unbase-pages` and `@unbase-app/cli` out
131
+ (`removed`, with `replacedBy`, in `--json`): written to `package.json` together and installed in
132
+ one run, so the `unbase` bin both CLIs have is the new one's. A failed install puts
133
+ `package.json` back, and nothing else has changed yet.
134
+ - `unbase()` takes `commentModus()`'s place with its options as they are (a site's own `project`,
135
+ `titles`, `language`…); the `commentModusConfig.project ? … : null` init wrote around it goes,
136
+ since `unbase()` waits for the project itself. `unbasePages()` and its import go.
137
+ - `@jens4m/comment-modus` goes too, unless the site uses it for itself: a name its config still
138
+ imports from it, its CLI in a script or a workflow. Then it stays, moved to the version
139
+ `@unbase-app/astro` brings, so there is one.
140
+ - The pointer line moves to `node_modules/@unbase-app/cli/AGENTS.md`.
141
+ - With `--yes`, a site keeps its choice of comments. A second run changes nothing.
142
+
143
+ `doctor` passes on a site from before as it is, and says the move is there (`moved`, info).
144
+
145
+ ## `unbase doctor`
146
+
147
+ Builds the site once (production, into a folder of its own), then reads it with Unbase's own
148
+ readers, the code the Edge Functions run, bundled into this package. Per feature it gives a state
149
+ and per check what is missing, the file, and the step in `agents/astro.md` that fixes it.
150
+
151
+ | Check state | |
152
+ |---|---|
153
+ | `ok` | Works |
154
+ | `missing` | The site has to change. Fails the run |
155
+ | `waiting` | Outside this repository: Unbase linking the project, or a package release. Named, does not fail the run |
156
+ | `info` | Worth knowing |
157
+ | `skipped` | Not checked (`--no-build`, or a build that failed) |
158
+
159
+ Features: **Visual editing** (Astro, the site builds), **Comments on the site** (the package, its
160
+ line, the link, the markers, the loader), **Page management** (the kit, the drafts in
161
+ `unbase.pages.json`, the kit running in a production build, the content schemas, the route files
162
+ and the site settings and that the layout reads them). `--no-build` skips the build and what needs
163
+ it.
164
+
165
+ The markers are comment mode's `data-c`: a pin on the live site takes its title and source file
166
+ from them, so with comments they belong in the production build. A site without comment mode, or
167
+ whose `unbase()` says `componentMarker: "preview"` (comment-modus 1.9.0: markers in the dev
168
+ server and previews only) or `false`, must have none there; `doctor` fails when it does, and names
169
+ an older comment-modus that ignores `"preview"`.
170
+
171
+ ## `unbase uninstall`
172
+
173
+ Refuses while `unbase.pages.json` holds a draft, and lists them: without the kit a draft is built
174
+ and goes live, so each is published or deleted in Unbase first. Then it builds the site, removes
175
+ the packages, their lines in `astro.config`, `comment-modus.json`, `unbase.pages.json`,
176
+ `src/content/.schemas/` and the pointer line, builds again, and compares every page's HTML. Taken
177
+ out first: comment mode's markers and loader, and what differs between any two builds (asset
178
+ hashes, Astro's ids, white space, attribute order). When pages still differ it builds the after
179
+ state once more, and what differs between those two builds (an id a component makes at random on
180
+ every render) is noise, not a change. "No differences in the built pages" is the pass. `--yes` without
181
+ a terminal; `--no-build` skips the comparison; `--no-install` writes `package.json` only.
182
+
183
+ The route files, the settings file and the layout's reads stay: they are the site's own code.
184
+
185
+ ## For programs
186
+
187
+ - **Never asks without a terminal.** A choice without its flag is an error (exit 2) naming the
188
+ flags; `--json` never asks.
189
+ - **`--json`** on every command. `init`: `packages` (name, the pinned `version`, dev, and `action`:
190
+ `added`, `updated` with `from` and `to`, or `kept`, with a `note` when the one there is newer)
191
+ and `files` (file, `created`, `changed` or `removed`, and the changes; the lockfile too when
192
+ the package manager ran). `doctor`: `features`, each
193
+ with `state` (`on`, `off`, `waiting`, `not-installed`) and `checks` (`id`, `state`, `message`,
194
+ and for a `missing` or `waiting` check `missing`, `file`, `step`). `uninstall`: `files`
195
+ (every file it touched, the lockfile included), `packages`, `comparison` (`pages`,
196
+ `differences`, `secondBuild`), or `refused: "drafts"` with `drafts`.
197
+ An error: `{ ok: false, exitCode: 2, error: { code, message, file? } }`.
198
+ - **Exit codes:** `0` passed, `1` failed (doctor found something missing; uninstall refused or
199
+ found a difference), `2` could not run (usage, no Astro site, a config it cannot edit safely, an
200
+ install that failed).
201
+ - **No login, no project, no network** beyond the package manager's install: it never calls Unbase,
202
+ and the versions are pinned.
203
+
204
+ ## Developing
205
+
206
+ Part of the kit (`kit/` in Unbase's repository; see its README): `npm test` there runs every
207
+ package's tests. `lib/readers.mjs` is generated from the Edge Functions' readers (`detect.ts`,
208
+ `settings.ts`, `pages.ts`, the kit's core), which live in Unbase's repository: after changing one of
209
+ them, `node kit/cli/scripts/readers.mjs`; the tests fail there while it is out of date. In the kit
210
+ on its own the file ships as it was generated.
211
+
212
+ MIT licence.
@@ -0,0 +1,162 @@
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. Check
145
+
146
+ `npx @unbase-app/cli doctor` builds the site once and says, per feature, what Unbase will say:
147
+
148
+ - **Visual editing**: nothing to install on Astro; the site has to build.
149
+ - **Comments on the site**: the package, its line, the link to a project, the markers (`data-c`:
150
+ in the production build with comments; none without comment mode, or with
151
+ `componentMarker: "preview"` in `unbase()`).
152
+ - **Page management**: the kit, the drafts, the route files and the site settings, and that the
153
+ layout reads them.
154
+
155
+ `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
156
+ package release) and does not fail the run. Then commit on a new branch.
157
+
158
+ ## Leaving
159
+
160
+ `npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted, and
161
+ compares every built page before and after. The route files, the settings file and the layout's
162
+ reads stay: they are the site's own code and keep working.
package/agents/next.md ADDED
@@ -0,0 +1,109 @@
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. Check
99
+
100
+ `npx @unbase-app/cli doctor` builds the site once and says, per feature, what Unbase will say:
101
+
102
+ - **Visual editing**: nothing to install on Next.js; the site has to build.
103
+ - **Comments on the site**: the package, its wrapper in `next.config`, the link to a project, the
104
+ loader on the page and in the build.
105
+ - **Page management**: the package, the drafts, `withUnbase` running in a production build, which
106
+ pages can be drafts, and which pages' settings Unbase can set.
107
+
108
+ `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
109
+ package release) and does not fail the run. Then commit on a new branch.
@@ -0,0 +1,108 @@
1
+ # Unbase in a Vite + React site: the steps for an agent or a developer
2
+
3
+ For a single-page app made with Vite, React and React Router as a library (`react-router-dom`, the
4
+ `<Routes>` in `src/App.tsx`), as Lovable makes them. React Router's framework mode
5
+ (`@react-router/dev`, `app/routes.ts`) is another framework, which has no package yet.
6
+
7
+ `npx @unbase-app/cli init` adds what a fixed change can add: the package, its line in
8
+ `vite.config`, and `comment-modus.json`. What is left needs judgement about this site's code, and
9
+ is yours. You add code. You never move or rewrite the site's content: Unbase edits a text where it
10
+ is written, in a page, a component or a data file, so moving text into JSON gains nothing and
11
+ risks the site.
12
+
13
+ Work through the steps, run `npx @unbase-app/cli doctor`, fix what it names, and run it again until it
14
+ passes. Every finding names a file and the step below that fixes it. `doctor --json` gives the
15
+ same as data.
16
+
17
+ These are conventions, not an Unbase runtime: everything here is plain Vite and React that a
18
+ developer would write, it renders the same with or without Unbase, and you can follow it while a
19
+ site is first written.
20
+
21
+ ## 1. Install
22
+
23
+ `npx @unbase-app/cli init` (add `--yes` without a terminal). It is safe to run again: a second run
24
+ changes nothing, and a package that is older than the version init pins is moved up to it. It adds:
25
+
26
+ - `@unbase-app/vite` as a devDependency, and `unbase()` last in `plugins` in `vite.config`, with
27
+ `import { unbase } from "@unbase-app/vite"`. One plugin that keeps draft pages out of production
28
+ builds, and turns on comments on the live site with `?comment` once the site is linked.
29
+ `--no-comments` writes `unbase({ comments: false })`.
30
+ - `comment-modus.json` with `"project": null`. Unbase fills in the project when the site is
31
+ connected; until then comment mode stays off. Do not invent a value.
32
+ - `@unbase-app/cli` as a devDependency, so this file and `doctor` are pinned by the lockfile.
33
+
34
+ A site with the draft-pages kit's own plugin (`unbasePages()` from `@jens4m/unbase-pages/vite`)
35
+ gets `unbase()` in its place: `@unbase-app/vite` carries the kit, and two kits in one build would
36
+ stop it. `@jens4m/unbase-pages` is then unused; remove it from `package.json`.
37
+
38
+ If init says it cannot edit `vite.config` safely, make the same change by hand: the import, and
39
+ `unbase()` as the last entry of `plugins`.
40
+
41
+ ## 2. Site settings
42
+
43
+ Unbase sets the site's name, description, language, tab icon and share image where a Vite app
44
+ keeps them: as values in the `<head>` of `index.html`. It changes a value in place and nothing
45
+ else. It reads, as plain values written in the file:
46
+
47
+ - `<title>`: the site's name in Unbase. An `og:title` or `twitter:title` with the same text
48
+ follows it.
49
+ - `<meta name="description" content="…">`. `og:description` and `twitter:description` with the
50
+ same text follow it.
51
+ - `<html lang="…">`.
52
+ - one `<link rel="icon" href="…">` (and one with `media="(prefers-color-scheme: dark)"` for the
53
+ dark icon). A new icon is uploaded into `public/`; when the link names a `type`, a picture of
54
+ that type.
55
+ - `<meta property="og:image" content="…">`, with a `twitter:image` that says the same.
56
+
57
+ Nothing to add when `index.html` has them. A setting `index.html` does not have is not offered:
58
+ add the tag with the value the site already uses if you want it settable, never an invented one.
59
+ Keep the values literal: a `%VITE_…%` placeholder, or a head library that sets them at runtime,
60
+ is code Unbase leaves alone.
61
+
62
+ There are no page settings on a single-page app: every route is `index.html`, so a route has no
63
+ `<head>` of its own. Do not add a head library or a per-route settings file for Unbase.
64
+
65
+ ## 3. Draft pages
66
+
67
+ Nothing to add when the routes are JSX in the router: `unbase()` keeps every page Unbase marks as a
68
+ draft (in `unbase.pages.json`, which Unbase writes) out of production builds, and stops the build
69
+ when it cannot. Unbase finds a page as
70
+
71
+ ```tsx
72
+ <Route path="/pricing" element={<Pricing />} />
73
+ ```
74
+
75
+ in a file that imports `react-router-dom` (or `react-router`): a literal `path`, one component in
76
+ `element`, that component imported (or `lazy(() => import(…))`) from its own file. A page that
77
+ cannot be a draft is fine (a dynamic route such as `/blog/:slug`, a page another file imports, a
78
+ route with child routes); doctor lists them. Routes written as objects
79
+ (`createBrowserRouter([{ path, element }])`) are not read: their pages have no draft and no place in
80
+ comment mode's page tree. Do not rewrite a router for Unbase.
81
+
82
+ ## 4. Comments on the site
83
+
84
+ Nothing to add. Once Unbase links the site (`comment-modus.json` names the project), every build
85
+ puts a few lines in `index.html` that load comment mode only with `?comment`, and writes
86
+ `version.json` and `comment-modus/pages.json` beside it. Comment mode needs Unbase's two public
87
+ values where the site is built, `PUBLIC_SUPABASE_URL` and `PUBLIC_SUPABASE_ANON_KEY`; Unbase sets
88
+ them on Vercel when the site is connected there. Do not put them in the repository.
89
+
90
+ ## 5. Check
91
+
92
+ `npx @unbase-app/cli doctor` builds the site once (production, with `vite build` into a folder of its own)
93
+ and says, per feature, what Unbase will say:
94
+
95
+ - **Visual editing**: nothing to install on Vite + React; the site has to build.
96
+ - **Comments on the site**: the package, its line, the link to a project, the loader and the two
97
+ files in the build.
98
+ - **Page management**: the kit, the drafts, the pages Unbase finds in the router, and the site
99
+ settings in `index.html`.
100
+
101
+ `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
102
+ package release) and does not fail the run. Then commit on a new branch.
103
+
104
+ ## Leaving
105
+
106
+ `npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted, and
107
+ compares the built `index.html` before and after. `index.html`'s settings stay as they are: they
108
+ are the site's own.