@unbase-app/pages 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/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,106 @@
1
- # Temporary Holding Version
1
+ # @unbase-app/pages
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
+ Keeps draft pages out of a site's production build. A page marked as a draft stays off the live
4
+ site however often the rest is published, while previews and the dev server show it as it is.
5
+
6
+ It is a build step only: an Astro integration and a Vite plugin for React Router apps. Nothing it
7
+ does reaches a visitor's browser, and it never calls a hosted service. Made for
8
+ [Unbase](https://unbase.app), which writes the list of drafts; it works the same without it.
9
+
10
+ An Astro site with Unbase gets it through [`@unbase-app/astro`](../astro), which brings it with
11
+ comment mode in one line; use it on its own for a site without comment mode, or with Vite. Until
12
+ 03-11-2026 it was `@jens4m/unbase-pages`.
13
+
14
+ ```bash
15
+ npm install --save-exact @unbase-app/pages
16
+ ```
17
+
18
+ ## Astro
19
+
20
+ ```js
21
+ // astro.config.mjs
22
+ import { defineConfig } from "astro/config";
23
+ import sitemap from "@astrojs/sitemap";
24
+ import unbasePages from "@unbase-app/pages/astro";
25
+
26
+ export default defineConfig({
27
+ // Last, or at least after sitemap() and comment-modus: it cleans the page lists they write.
28
+ integrations: [sitemap(), unbasePages()],
29
+ });
30
+ ```
31
+
32
+ ## Vite + React Router
33
+
34
+ ```js
35
+ // vite.config.ts
36
+ import react from "@vitejs/plugin-react";
37
+ import { unbasePages } from "@unbase-app/pages/vite";
38
+
39
+ export default { plugins: [react(), unbasePages()] };
40
+ ```
41
+
42
+ [`@unbase-app/vite`](../vite) carries this plugin, an exact copy, together with comment mode's
43
+ loader: a Vite site Unbase installs gets that one package instead (`unbase()`), never both.
44
+
45
+ ## Which pages are drafts
46
+
47
+ `unbase.pages.json` at the app's root lists them. Without the file, or without a draft in it, the
48
+ build is untouched.
49
+
50
+ ```json
51
+ { "pages": { "/pricing-2027": { "draft": true } } }
52
+ ```
53
+
54
+ ## What a production build does with a draft
55
+
56
+ - **Its page is not built.** Astro: the page file compiles to an empty page, so nothing it imports
57
+ is bundled, and its HTML is removed. React Router: its `<Route />` leaves the router and its
58
+ module becomes empty, so the address falls to the app's own Not Found.
59
+ - **Its address leaves every page list:** sitemaps, comment-modus's `pages.json` and content map,
60
+ and the entries the page owns in Astro's content store.
61
+ - **The output is checked for its text.** If a sentence only the draft has is still in a served
62
+ file, the build stops.
63
+
64
+ ## Which builds are production
65
+
66
+ `UNBASE_DEPLOY_CONTEXT` (`production`, `preview`, `development`) when it is set; otherwise a dev
67
+ server is development, and the host decides (`VERCEL_ENV`, Netlify's `CONTEXT`). Anything else
68
+ counts as production, so a draft only shows where a host says it is a preview. `NODE_ENV` is never
69
+ read: previews are production-optimised builds too.
70
+
71
+ ## Fails closed
72
+
73
+ A production build stops, with the page and the reason, when a draft cannot be kept out: a
74
+ dynamic route, a page another file imports, content it cannot attribute to the page, an invalid
75
+ `unbase.pages.json`, or a draft's text still in the output. Mark the page as ready, or fix the
76
+ reason, and build again.
77
+
78
+ ## Removing it
79
+
80
+ Publish or delete the drafts first: without the package, a draft in `unbase.pages.json` is
81
+ simply built. Then remove the package, its line in the config, and `unbase.pages.json`.
82
+
83
+ ## Exports
84
+
85
+ | | |
86
+ |---|---|
87
+ | `@unbase-app/pages/astro` | The Astro integration (default export, and `unbasePages`) |
88
+ | `@unbase-app/pages/vite` | The Vite plugin (`unbasePages`) |
89
+ | `@unbase-app/pages` | The core: discovering a site's pages and checking a draft, as pure functions on the app's files |
90
+
91
+ Node 18.17 or newer. MIT licence.
92
+
93
+ ## Developing
94
+
95
+ Part of the kit (see its README; `npm test` there). `core.mjs` is the one implementation of page
96
+ discovery and the draft check; Unbase's backend and the Vite and Next.js packages run exact copies
97
+ (`supabase/functions/_shared/pages-core.mjs` in Unbase's repository, `vite/pages/core.mjs` and
98
+ `next/core.mjs` in the kit; tests fail when they differ): after changing it, `cp kit/pages/core.mjs
99
+ supabase/functions/_shared/pages-core.mjs`, `node vite/scripts/sync-pages.mjs` and `cp
100
+ pages/core.mjs next/core.mjs`.
101
+
102
+ - `node --test test/core.test.mjs`.
103
+ - A11, the acceptance test, on lab sites only: `node test/a11.mjs vibe` (the Lovable-shaped
104
+ fixture in `test/fixtures/lab-vibe`) and `node test/a11.mjs astro --dir <lab copy>` (a git
105
+ repository without a remote). It needs `playwright-core` (`PLAYWRIGHT_CORE=<path>`) and Chrome
106
+ (`CHROME_PATH`).
package/astro.d.mts ADDED
@@ -0,0 +1,16 @@
1
+ import type { AstroIntegration } from "astro";
2
+
3
+ /**
4
+ * The Astro integration: in a production build every draft in unbase.pages.json is kept out, or
5
+ * the build stops. Put it after sitemap() and comment-modus in `integrations`.
6
+ */
7
+ declare function unbasePages(): AstroIntegration;
8
+ export default unbasePages;
9
+ export { unbasePages };
10
+
11
+ /** Astro's content store without the entries the drafts own (used by the integration; exported for its tests). */
12
+ export declare function withoutDraftEntries(
13
+ code: string,
14
+ owned: Set<string>,
15
+ devalue: { unflatten(value: unknown): unknown; stringify(value: unknown): string },
16
+ ): { code: string; removed: string[] };
package/astro.mjs ADDED
@@ -0,0 +1,114 @@
1
+ // @ts-check
2
+ // ============================================================================
3
+ // @unbase-app/pages/astro — the Astro integration. In a production build
4
+ // every draft in unbase.pages.json is kept out: its page file becomes an empty
5
+ // page before Astro compiles it (so nothing it imports is bundled), its HTML
6
+ // is removed afterwards, and its address and the content it owns leave every
7
+ // page list (sitemaps, comment-modus/pages.json and the content map). Then
8
+ // the output is checked for the page's text. Previews and the dev server show
9
+ // drafts as they are. Fails closed: a draft it cannot keep out stops the build.
10
+ //
11
+ // It goes after @astrojs/sitemap and comment-modus in `integrations`, so the
12
+ // lists they write exist when it cleans them; the build stops otherwise.
13
+ //
14
+ // // astro.config.mjs
15
+ // import unbasePages from "@unbase-app/pages/astro";
16
+ // integrations: [..., sitemap(), unbasePages()]
17
+ // ============================================================================
18
+
19
+ import { createRequire } from "node:module";
20
+ import { join } from "node:path";
21
+ import { fileURLToPath, pathToFileURL } from "node:url";
22
+ import { finishOutput, planBuild, removePageHtml } from "./node.mjs";
23
+
24
+ const NAME = "@unbase-app/pages";
25
+ /** Integrations that write a page list in astro:build:done. */
26
+ const LISTS = ["@astrojs/sitemap", "comment-modus"];
27
+
28
+ const clean = (id) => id.replace(/\?.*$/, "");
29
+ /** Astro's content store as one module: every collection's entries, also in the server's bundle. */
30
+ const DATA_STORE = "\0astro:data-layer-content";
31
+
32
+ /**
33
+ * The content store without the entries a draft owns (by their file), in the form Astro wrote it:
34
+ * `export default JSON.parse("<devalue>")`. Any other form, a store in chunks, stops the build:
35
+ * the kit cannot say the draft's content is out of it.
36
+ */
37
+ export function withoutDraftEntries(code, owned, devalue) {
38
+ if (code.trim() === "export default new Map()") return { code, removed: [] };
39
+ const m = code.match(/^\s*export default JSON\.parse\(("(?:[^"\\]|\\.)*")\)\s*;?\s*$/s);
40
+ if (!m) throw new Error("[unbase-pages] Astro's content store is not in a form the kit can read, so it cannot keep the drafts' content out of it, and the build stops.");
41
+ const store = devalue.unflatten(JSON.parse(JSON.parse(m[1])));
42
+ if (!(store instanceof Map)) throw new Error("[unbase-pages] Astro's content store is not a Map, so the build stops.");
43
+ const removed = [];
44
+ for (const [, entries] of store) {
45
+ if (!(entries instanceof Map)) throw new Error("[unbase-pages] A collection in Astro's content store is not a Map, so the build stops.");
46
+ for (const [key, entry] of entries) {
47
+ if (owned.has(entry?.filePath)) {
48
+ entries.delete(key);
49
+ removed.push(entry.filePath);
50
+ }
51
+ }
52
+ }
53
+ return { code: `export default JSON.parse(${JSON.stringify(devalue.stringify(store))})`, removed };
54
+ }
55
+
56
+ /** @returns {import("astro").AstroIntegration} */
57
+ export default function unbasePages() {
58
+ /** @type {ReturnType<typeof planBuild>} */
59
+ let plan = null;
60
+ /** Where the build writes, client and server, for the leak check. */
61
+ let roots = [];
62
+ return {
63
+ name: NAME,
64
+ hooks: {
65
+ "astro:config:setup": async ({ command, config, updateConfig, logger }) => {
66
+ if (command !== "build") return;
67
+ const root = fileURLToPath(config.root);
68
+ plan = planBuild({ root, framework: "astro", command: "build", log: (l) => logger.info(l) });
69
+ if (!plan) return;
70
+ const stubs = new Set(plan.drafts.map((d) => d.file));
71
+ const owned = new Set(plan.drafts.flatMap((d) => d.content));
72
+ // The site's own devalue, the one Astro wrote its content store with.
73
+ const devalue = await import(pathToFileURL(createRequire(join(root, "package.json")).resolve("devalue")).href);
74
+ updateConfig({
75
+ vite: {
76
+ plugins: [
77
+ {
78
+ name: "unbase-pages:drafts",
79
+ enforce: "pre",
80
+ load: (id) => (stubs.has(clean(id)) ? "---\n---\n" : null),
81
+ },
82
+ {
83
+ name: "unbase-pages:content-store",
84
+ transform(code, id) {
85
+ if (id !== DATA_STORE || !owned.size) return null;
86
+ const out = withoutDraftEntries(code, owned, devalue);
87
+ if (out.removed.length) logger.info(`content store without ${out.removed.join(", ")}`);
88
+ return { code: out.code, map: null };
89
+ },
90
+ },
91
+ ],
92
+ },
93
+ });
94
+ },
95
+ "astro:config:done": ({ config }) => {
96
+ if (!plan) return;
97
+ const all = [config.outDir, config.build.client, config.build.server].map((u) => fileURLToPath(u));
98
+ roots = all.filter((r, i) => !all.some((o, j) => j !== i && r !== o && r.startsWith(o)) && all.indexOf(r) === i);
99
+ const names = config.integrations.map((i) => i.name);
100
+ const later = names.slice(names.indexOf(NAME) + 1).filter((n) => LISTS.includes(n));
101
+ if (later.length) throw new Error(`[unbase-pages] Put unbasePages() after ${later.join(" and ")} in integrations: they write page lists it has to clean, so the build stops.`);
102
+ },
103
+ "astro:build:done": ({ dir, logger }) => {
104
+ if (!plan) return;
105
+ const out = fileURLToPath(dir);
106
+ for (const d of plan.drafts) for (const f of removePageHtml(out, d.path)) logger.info(`removed ${f.slice(out.length)}`);
107
+ // Lists are cleaned where the host serves them; the leak check reads the server's bundle too.
108
+ finishOutput(out, plan, (l) => logger.info(l), roots.length ? roots : [out]);
109
+ },
110
+ },
111
+ };
112
+ }
113
+
114
+ export { unbasePages };