@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 +37 -0
- package/LICENSE +21 -0
- package/README.md +211 -2
- package/agents/astro.md +162 -0
- package/agents/next.md +109 -0
- package/agents/vite-react.md +108 -0
- package/bin/unbase.mjs +147 -0
- package/lib/args.mjs +49 -0
- package/lib/build.mjs +71 -0
- package/lib/compare.mjs +96 -0
- package/lib/config-edit.mjs +629 -0
- package/lib/doctor.mjs +37 -0
- package/lib/errors.mjs +15 -0
- package/lib/feature.mjs +23 -0
- package/lib/frameworks/astro.mjs +485 -0
- package/lib/frameworks/index.mjs +50 -0
- package/lib/frameworks/next.mjs +321 -0
- package/lib/frameworks/vite-react.mjs +299 -0
- package/lib/init.mjs +165 -0
- package/lib/next-config.mjs +131 -0
- package/lib/pm.mjs +109 -0
- package/lib/readers.mjs +1918 -0
- package/lib/site.mjs +153 -0
- package/lib/uninstall.mjs +136 -0
- package/lib/versions.mjs +71 -0
- package/lib/vite-config.mjs +294 -0
- package/package.json +43 -4
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
|
-
#
|
|
1
|
+
# @unbase-app/cli
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
package/agents/astro.md
ADDED
|
@@ -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.
|