@opentf/afw-build 0.0.0-stage → 0.1.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/README.md +34 -2
- package/compile.js +89 -0
- package/compiler-client.js +187 -0
- package/document.js +246 -0
- package/host.js +51 -0
- package/index.js +24 -0
- package/package.json +40 -4
- package/prerender.js +124 -0
- package/resolve-compiler.js +75 -0
- package/routes.js +176 -0
- package/server.js +198 -0
package/README.md
CHANGED
|
@@ -1,3 +1,35 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @opentf/afw-build
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The toolchain-neutral core of the AFW build. AFW ships two official workflows, each a
|
|
4
|
+
thin integration over this package:
|
|
5
|
+
|
|
6
|
+
| Workflow | Toolchain package | Runs on |
|
|
7
|
+
| --- | --- | --- |
|
|
8
|
+
| esdev + ES-Runtime | `@opentf/esdev-plugin-afw` | ES-Runtime |
|
|
9
|
+
| Vite + Node | `@opentf/vite-plugin-afw` | Node |
|
|
10
|
+
|
|
11
|
+
You normally install one of those, not this package directly.
|
|
12
|
+
|
|
13
|
+
## What lives here
|
|
14
|
+
|
|
15
|
+
| Module | Purpose |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| `compiler-client.js` | The `afwc serve` protocol: one long-lived compiler child for every module |
|
|
18
|
+
| `compile.js` | Compiler target rules (`chooseTarget`), the compile-error stub, route-module detection |
|
|
19
|
+
| `resolve-compiler.js` | Finds `afwc`: `AFWC_BIN`, the prebuilt `@opentf/afw-compiler` binary, or a cargo build in a source checkout |
|
|
20
|
+
| `routes.js` | File-based routing: page, layout, 404 and loader discovery, and the `@afw/routes` module |
|
|
21
|
+
| `document.js` | The HTML document: shell helpers and `renderDocument`, shared by SSR and static generation |
|
|
22
|
+
| `prerender.js` | Static generation: pages, loader data, `404.html`, sitemap and robots |
|
|
23
|
+
| `server.js` | Server routing: API routes, middleware and loaders composed into the `@afw/server` handler |
|
|
24
|
+
| `host.js` | The host interface the above run against |
|
|
25
|
+
|
|
26
|
+
## The host interface
|
|
27
|
+
|
|
28
|
+
Nothing here imports `runtime:*` or `node:*`. A toolchain supplies a host object with
|
|
29
|
+
file access (`readText`, `readDir`, `kind`), processes (`spawn`, `run`), `cwd`, `env`
|
|
30
|
+
and `path` helpers; see `host.js` for the full contract. A test enforces that the
|
|
31
|
+
package stays platform-free.
|
|
32
|
+
|
|
33
|
+
## License
|
|
34
|
+
|
|
35
|
+
MIT
|
package/compile.js
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
// What every toolchain does with an AFW source module: pick the compiler target for
|
|
2
|
+
// the build at hand, compile through `afwc`, and turn a failure into either a thrown
|
|
3
|
+
// diagnostic or a visible stub module.
|
|
4
|
+
|
|
5
|
+
/** Rendering modes a project chooses from. */
|
|
6
|
+
export const MODES = new Set(["spa", "ssg", "ssr"]);
|
|
7
|
+
/** Compiler backends: live DOM, HTML-string renderers, or the hydrating dual module. */
|
|
8
|
+
export const TARGETS = new Set(["csr", "ssg", "hydrate"]);
|
|
9
|
+
|
|
10
|
+
/** Source modules the compiler owns. */
|
|
11
|
+
export const SOURCE_FILTER = /\.(mdx|md|[jt]sx)$/;
|
|
12
|
+
|
|
13
|
+
/** Throw on an unknown mode or target, before any compiler starts. */
|
|
14
|
+
export function validateOptions({ mode = "spa", target } = {}) {
|
|
15
|
+
if (!MODES.has(mode)) throw new Error(`Unknown AFW rendering mode: ${mode} (expected spa, ssg, or ssr)`);
|
|
16
|
+
if (target !== undefined && !TARGETS.has(target)) {
|
|
17
|
+
throw new Error(`Unknown AFW compiler target: ${target} (expected csr, ssg, or hydrate)`);
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* The compiler target for one module. `server` — the module is bundled for the
|
|
23
|
+
* server (string renderers). `dev` — a dev server or test run, which always renders
|
|
24
|
+
* on the client. Otherwise a release browser build: CSR for an SPA, the hydrating
|
|
25
|
+
* dual module when the server renders first.
|
|
26
|
+
*/
|
|
27
|
+
export function chooseTarget({ mode = "spa", target, server = false, dev = false } = {}) {
|
|
28
|
+
if (target) return target;
|
|
29
|
+
if (server) return "ssg";
|
|
30
|
+
if (dev) return "csr";
|
|
31
|
+
return mode === "spa" ? "csr" : "hydrate";
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Whether framework imports in this build resolve to the DOM-free server entry. */
|
|
35
|
+
export function usesServerEntry({ target, server = false } = {}) {
|
|
36
|
+
return (target ?? (server ? "ssg" : undefined)) === "ssg";
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The framework specifiers that resolve to `@opentf/afw/server` in a server build. */
|
|
40
|
+
export const FRAMEWORK_IMPORT = /^@opentf\/afw(?:\/runtime)?$/;
|
|
41
|
+
|
|
42
|
+
/** Page, layout and 404 modules compile to route factories; the rest to components. */
|
|
43
|
+
export function isRouteModule(id) {
|
|
44
|
+
const base = id.split(/[\\/]/).pop().replace(SOURCE_FILTER, "");
|
|
45
|
+
return base === "page" || base === "layout" || base === "404";
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** A module that shows the compile error in place of the page or component. */
|
|
49
|
+
export function errorStub(text) {
|
|
50
|
+
return (
|
|
51
|
+
`export default function () { const pre = document.createElement("pre");` +
|
|
52
|
+
` pre.style.cssText = "color:#f87171;padding:1rem;white-space:pre-wrap";` +
|
|
53
|
+
` pre.textContent = ${JSON.stringify(`Compile error\n\n${text}`)};` +
|
|
54
|
+
` return pre; }`
|
|
55
|
+
);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Compile one module. `server` is a compiler client (compiler-client.js). `hot`
|
|
60
|
+
* requests the refresh-instrumented CSR build. On failure, `failOnError` throws the
|
|
61
|
+
* diagnostic (after `error(message)` when the toolchain reports through its own
|
|
62
|
+
* channel); otherwise it logs and returns the stub, so one broken file does not
|
|
63
|
+
* stop a dev server.
|
|
64
|
+
*
|
|
65
|
+
* @returns {Promise<{ code: string, map: object | null }>}
|
|
66
|
+
*/
|
|
67
|
+
export async function compileModule(server, code, id, {
|
|
68
|
+
target, hot = false, failOnError = false, onResult, quiet = () => {}, error,
|
|
69
|
+
} = {}) {
|
|
70
|
+
try {
|
|
71
|
+
const out = await server.compile(id, code, !isRouteModule(id), hot && target === "csr" ? "csr-hot" : target);
|
|
72
|
+
onResult?.(id, null);
|
|
73
|
+
return typeof out === "string" ? { code: out, map: null } : { code: out.code, map: out.map ?? null };
|
|
74
|
+
} catch (e) {
|
|
75
|
+
// `text` is the diagnostic as a terminal or overlay shows it — the position line
|
|
76
|
+
// plus a code frame; `diag` is the same as fields, for the overlay.
|
|
77
|
+
const text = e?.text ?? e?.message ?? String(e);
|
|
78
|
+
const diag = e?.diag ?? { file: id, message: e?.message ?? String(e) };
|
|
79
|
+
onResult?.(id, diag);
|
|
80
|
+
// A build phase may be drawing on the terminal's last line; take it back first.
|
|
81
|
+
quiet();
|
|
82
|
+
if (failOnError) {
|
|
83
|
+
error?.(`afwc failed:\n${text}`);
|
|
84
|
+
throw e;
|
|
85
|
+
}
|
|
86
|
+
console.error(`✗ afwc failed:\n${text}`);
|
|
87
|
+
return { code: errorStub(text), map: { version: 3, sources: [], names: [], mappings: "" } };
|
|
88
|
+
}
|
|
89
|
+
}
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
// The `afwc serve` protocol client, shared by every toolchain integration.
|
|
2
|
+
//
|
|
3
|
+
// One long-lived compiler child serves every module of every build in the process;
|
|
4
|
+
// requests and replies are framed over its stdin/stdout. Starting the child is the
|
|
5
|
+
// only platform-specific step, so it comes from the host's `spawn` (see host.js).
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Turn an `ERR` reply payload into an `Error` carrying the compiler's diagnostic.
|
|
9
|
+
* The payload is the JSON object `Diag::json` writes — `{ file, message, line,
|
|
10
|
+
* column, frame, note }` — so the position survives as data all the way to the browser
|
|
11
|
+
* overlay instead of being flattened into prose. An older compiler (or a protocol
|
|
12
|
+
* error) sends a bare string; that still works, it just has no position.
|
|
13
|
+
*
|
|
14
|
+
* `error.message` is the one-line human form (`path:line:col message`), `error.diag`
|
|
15
|
+
* the structured fields, and `error.text` the full terminal rendering with the frame.
|
|
16
|
+
*/
|
|
17
|
+
export function compileError(payload) {
|
|
18
|
+
let d = null;
|
|
19
|
+
if (payload.startsWith("{")) {
|
|
20
|
+
try {
|
|
21
|
+
d = JSON.parse(payload);
|
|
22
|
+
} catch {}
|
|
23
|
+
}
|
|
24
|
+
if (!d?.message) {
|
|
25
|
+
const err = new Error(payload);
|
|
26
|
+
err.diag = { message: payload };
|
|
27
|
+
err.text = payload;
|
|
28
|
+
return err;
|
|
29
|
+
}
|
|
30
|
+
const where = d.line ? `${d.file}:${d.line}:${d.column}` : d.file;
|
|
31
|
+
const err = new Error(`${where}: ${d.message}`);
|
|
32
|
+
err.diag = d;
|
|
33
|
+
err.text =
|
|
34
|
+
`${where}: ${d.message}\n` + (d.note ? `note: ${d.note}\n` : "") + (d.frame ? `\n${d.frame}` : "");
|
|
35
|
+
return err;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Start a long-lived `afwc serve` process and talk to it over a framed
|
|
40
|
+
* stdin/stdout protocol (see crates/afw_cli/src/main.rs `serve`). One process
|
|
41
|
+
* compiles every module, so the toolchain pays the binary-startup cost once
|
|
42
|
+
* instead of spawning a subprocess per file — the dominant dev-server cost.
|
|
43
|
+
*
|
|
44
|
+
* `compile(id, source, component, target)` resolves to the emitted JS or rejects
|
|
45
|
+
* with the compiler diagnostic (`target` is `"csr"` | `"ssg"` | `"hydrate"`).
|
|
46
|
+
* With `{ sourceMap: true }`, success resolves to `{ code, map }`. Older
|
|
47
|
+
* binaries still compile, returning `map: null`. The request framing is unchanged.
|
|
48
|
+
* Requests are serialized through a FIFO queue: the server
|
|
49
|
+
* is single-threaded, replies arrive in request order, so the head of the queue
|
|
50
|
+
* always pairs with the next frame. The child is killed when this process exits.
|
|
51
|
+
*/
|
|
52
|
+
// Every compiler child started in this process, so a one-shot command can shut them
|
|
53
|
+
// all down. It has to: an open reader on a child's stdout keeps the runtime alive, so
|
|
54
|
+
// a prerender step that simply returned would hang after its output is written.
|
|
55
|
+
const compilers = new Set();
|
|
56
|
+
|
|
57
|
+
/** Stop every `afwc serve` child. Called at the end of the one-shot commands. */
|
|
58
|
+
export async function closeCompilers() {
|
|
59
|
+
await Promise.all([...compilers].map((close) => close()));
|
|
60
|
+
compilers.clear();
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export function startCompilerServer(afwc, { sourceMap = false, spawn } = {}) {
|
|
64
|
+
if (typeof spawn !== "function") throw new TypeError("startCompilerServer: a host `spawn` function is required");
|
|
65
|
+
const enc = new TextEncoder();
|
|
66
|
+
const dec = new TextDecoder();
|
|
67
|
+
const queue = []; // { resolve, reject } in request order
|
|
68
|
+
let buf = new Uint8Array(0);
|
|
69
|
+
let pumping = false;
|
|
70
|
+
let dead = false;
|
|
71
|
+
let started = null;
|
|
72
|
+
|
|
73
|
+
const append = (a, b) => {
|
|
74
|
+
const out = new Uint8Array(a.length + b.length);
|
|
75
|
+
out.set(a);
|
|
76
|
+
out.set(b, a.length);
|
|
77
|
+
return out;
|
|
78
|
+
};
|
|
79
|
+
const die = (err) => {
|
|
80
|
+
dead = true;
|
|
81
|
+
while (queue.length) queue.shift().reject(err);
|
|
82
|
+
idle();
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
// Spawning is async here, so the child is started on the first compile rather than
|
|
86
|
+
// when the plugin is constructed — a build that never touches a `.jsx` never pays
|
|
87
|
+
// for it. Nothing awaits the child's exit, so it holds nothing open; when this
|
|
88
|
+
// process goes, the child sees EOF on its stdin and stops.
|
|
89
|
+
let reading = null; // the stdout reader, so `close` can release it
|
|
90
|
+
// The child holds its parent process open only while a compile is in flight
|
|
91
|
+
// (hosts that can — Node — expose `ref`/`unref`). An idle compiler must not keep a
|
|
92
|
+
// build or test process alive when the toolchain never calls `close`.
|
|
93
|
+
let child = null;
|
|
94
|
+
const idle = () => child?.unref?.();
|
|
95
|
+
|
|
96
|
+
function start() {
|
|
97
|
+
started ??= Promise.resolve(spawn(afwc, sourceMap ? ["serve", "--sourcemap"] : ["serve"])).then((proc) => {
|
|
98
|
+
reading = proc.stdout.getReader();
|
|
99
|
+
child = proc;
|
|
100
|
+
return { proc, writer: proc.stdin.getWriter(), reader: reading };
|
|
101
|
+
});
|
|
102
|
+
return started;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
// Drain reply frames as they arrive, resolving queued requests in order. A frame
|
|
106
|
+
// is `<status> <byteLen>\n` followed by exactly `byteLen` bytes of payload.
|
|
107
|
+
async function pump(reader) {
|
|
108
|
+
if (pumping) return;
|
|
109
|
+
pumping = true;
|
|
110
|
+
try {
|
|
111
|
+
while (queue.length) {
|
|
112
|
+
let nl = buf.indexOf(10);
|
|
113
|
+
while (nl === -1) {
|
|
114
|
+
const { value, done } = await reader.read();
|
|
115
|
+
if (done) return die(new Error("afwc serve exited"));
|
|
116
|
+
buf = append(buf, value);
|
|
117
|
+
nl = buf.indexOf(10);
|
|
118
|
+
}
|
|
119
|
+
const [status, lenStr] = dec.decode(buf.subarray(0, nl)).split(" ");
|
|
120
|
+
const len = Number(lenStr);
|
|
121
|
+
while (buf.length < nl + 1 + len) {
|
|
122
|
+
const { value, done } = await reader.read();
|
|
123
|
+
if (done) return die(new Error("afwc serve exited"));
|
|
124
|
+
buf = append(buf, value);
|
|
125
|
+
}
|
|
126
|
+
const payload = dec.decode(buf.subarray(nl + 1, nl + 1 + len));
|
|
127
|
+
buf = buf.slice(nl + 1 + len);
|
|
128
|
+
const job = queue.shift();
|
|
129
|
+
if (status === "MAP") job.resolve(JSON.parse(payload));
|
|
130
|
+
// Older packaged binaries ignore --sourcemap and return plain OK frames.
|
|
131
|
+
// Keep them usable; they cannot provide mappings until upgraded.
|
|
132
|
+
else if (status === "OK") job.resolve(sourceMap ? { code: payload, map: null } : payload);
|
|
133
|
+
else job.reject(compileError(payload));
|
|
134
|
+
if (!queue.length) idle();
|
|
135
|
+
}
|
|
136
|
+
} finally {
|
|
137
|
+
pumping = false;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
// Replies are paired with requests by position, so the frames must reach the child
|
|
142
|
+
// in the order their promises were queued. Writing to a `WritableStream` is async,
|
|
143
|
+
// so the writes are chained rather than merely awaited per call — two concurrent
|
|
144
|
+
// `compile()`s would otherwise interleave their header and payload bytes.
|
|
145
|
+
let writes = Promise.resolve();
|
|
146
|
+
|
|
147
|
+
function compile(id, source, component, target = "csr") {
|
|
148
|
+
if (dead) return Promise.reject(new Error("afwc serve is not running"));
|
|
149
|
+
return new Promise((resolve, reject) => {
|
|
150
|
+
queue.push({ resolve, reject });
|
|
151
|
+
writes = writes
|
|
152
|
+
.then(async () => {
|
|
153
|
+
const { proc, writer, reader } = await start();
|
|
154
|
+
proc.ref?.();
|
|
155
|
+
const idB = enc.encode(id);
|
|
156
|
+
const srcB = enc.encode(source);
|
|
157
|
+
await writer.write(enc.encode(`${idB.length} ${srcB.length} ${component ? 1 : 0} ${target}\n`));
|
|
158
|
+
await writer.write(idB);
|
|
159
|
+
await writer.write(srcB);
|
|
160
|
+
pump(reader);
|
|
161
|
+
})
|
|
162
|
+
.catch(die);
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
async function close() {
|
|
167
|
+
compilers.delete(close);
|
|
168
|
+
if (dead) return;
|
|
169
|
+
dead = true;
|
|
170
|
+
if (!started) return;
|
|
171
|
+
try {
|
|
172
|
+
const { proc, writer } = await started;
|
|
173
|
+
try {
|
|
174
|
+
await writer.close();
|
|
175
|
+
} catch {}
|
|
176
|
+
// Releasing the reader matters as much as killing the child: an outstanding
|
|
177
|
+
// reader on a child's stdout is itself a reason for the runtime to stay up.
|
|
178
|
+
try {
|
|
179
|
+
await reading?.cancel();
|
|
180
|
+
} catch {}
|
|
181
|
+
proc.kill();
|
|
182
|
+
} catch {}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
compilers.add(close);
|
|
186
|
+
return { compile, close };
|
|
187
|
+
}
|
package/document.js
ADDED
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
// The HTML document, shared by every toolchain's server rendering: the shell helpers
|
|
2
|
+
// that place rendered markup, head tags and data payloads into the app's
|
|
3
|
+
// `index.html`, and `renderDocument`, which renders one URL into a complete document.
|
|
4
|
+
// Static generation (prerender.js) and per-request SSR both go through it, so a
|
|
5
|
+
// prerendered page and a server-rendered one are byte-for-byte the same document.
|
|
6
|
+
//
|
|
7
|
+
// Pure string work: nothing here touches a file system or the AFW runtime directly.
|
|
8
|
+
// `render` is the server render API (`renderRoute`, `renderHead` from
|
|
9
|
+
// `@opentf/afw/server`), passed in by the caller.
|
|
10
|
+
|
|
11
|
+
/** Inject `snippet` just before `</body>` (or append when there is none). */
|
|
12
|
+
export function injectBeforeBody(html, snippet) {
|
|
13
|
+
// Function replacer so `$` in `snippet` is literal (String.replace treats `$1`,
|
|
14
|
+
// `$&`, … in a string replacement as back-references — e.g. a "$189.00" price).
|
|
15
|
+
return html.includes("</body>") ? html.replace("</body>", () => `${snippet}</body>`) : html + snippet;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** Inject pre-rendered markup into the shell's empty `#app` container. */
|
|
19
|
+
export function injectMarkup(shellHtml, markup) {
|
|
20
|
+
// Function replacer: `markup` may contain `$` (currency, etc.) — keep it literal.
|
|
21
|
+
return shellHtml.replace(/(<div id="app"[^>]*>)\s*(<\/div>)/, (_m, open, close) => `${open}${markup}${close}`);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Embed the island hydration payload (`renderRoute().hydration`) as a
|
|
26
|
+
* `<script type="application/json" id="__afw_h">` the client reads at upgrade so
|
|
27
|
+
* components resume from rich JS props (compiler-driven data hydration). Placed before
|
|
28
|
+
* `</body>`; a deferred module bundle runs after parse, so the payload is always in the
|
|
29
|
+
* DOM first. `json` is already `<`-escaped by the server collector, so it can't break out
|
|
30
|
+
* of the script. No-op for an empty payload. Uses a function replacer so `$` in the JSON
|
|
31
|
+
* stays literal.
|
|
32
|
+
*/
|
|
33
|
+
export function injectHydrationData(shellHtml, json) {
|
|
34
|
+
if (!json) return shellHtml;
|
|
35
|
+
return injectBeforeBody(shellHtml, `<script type="application/json" id="__afw_h">${json}</script>`);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** The reserved per-route data filename/URL suffix (mirrors the runtime's
|
|
39
|
+
* `DATA_FILE` in `@opentf/afw` runtime/route-data.js). */
|
|
40
|
+
export const DATA_FILE = "__data.json";
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Embed a route loader's data (docs/DATA.md) as a `<script type="application/json"
|
|
44
|
+
* id="__afw_data">` the client router reads on first paint (instead of fetching
|
|
45
|
+
* `<path>/__data.json`). A separate script from the island payload above — the two
|
|
46
|
+
* channels have independent shapes and readers. `json` comes `<`-escaped from
|
|
47
|
+
* `serializeRouteData`; no-op for an empty payload (route without a loader, or an
|
|
48
|
+
* undefined loader result).
|
|
49
|
+
*/
|
|
50
|
+
export function injectRouteData(shellHtml, json) {
|
|
51
|
+
if (!json) return shellHtml;
|
|
52
|
+
return injectBeforeBody(shellHtml, `<script type="application/json" id="__afw_data">${json}</script>`);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Stamp the `data-afw-hydrate` sentinel onto the shell's `#app` container, telling
|
|
57
|
+
* the client to *adopt* the server-rendered DOM on first paint instead of rebuilding
|
|
58
|
+
* it (`runtime/router.js` `mountApp`). Used when the client bundle was built for the
|
|
59
|
+
* hydrate target and there is server markup to adopt (SSR, and SSG pre-render).
|
|
60
|
+
* Idempotent — a no-op if the sentinel is already present.
|
|
61
|
+
*/
|
|
62
|
+
export function stampHydrateSentinel(shellHtml) {
|
|
63
|
+
return shellHtml.replace(/<div id="app"([^>]*)>/, (m, attrs) =>
|
|
64
|
+
/\bdata-afw-hydrate\b/.test(attrs) ? m : `<div id="app"${attrs} data-afw-hydrate>`,
|
|
65
|
+
);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Record the route a prerendered page was rendered for on its hydrate sentinel
|
|
70
|
+
* (`data-afw-hydrate="/docs/x"`), so the client adopts the markup only at that URL
|
|
71
|
+
* and builds the requested route when a host serves this file for another path.
|
|
72
|
+
* A no-op when the shell carries no sentinel (a CSR-only shell).
|
|
73
|
+
*/
|
|
74
|
+
export function stampRenderedPath(shellHtml, path) {
|
|
75
|
+
const value = String(path).replace(/&/g, "&").replace(/"/g, """);
|
|
76
|
+
return shellHtml.replace(/(<div id="app"[^>]*?\sdata-afw-hydrate)(?:="[^"]*")?/, (_m, attr) => `${attr}="${value}"`);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Inject per-route `<head>` tags before `</head>`, dropping the shell's default
|
|
81
|
+
* `<title>` when the route supplies its own (so each page gets a unique,
|
|
82
|
+
* non-duplicated title). Shared by SSG pre-render and the SSR server.
|
|
83
|
+
*/
|
|
84
|
+
export function injectHead(shellHtml, headHtml) {
|
|
85
|
+
if (!headHtml) return shellHtml;
|
|
86
|
+
let out = stripRouteHead(shellHtml);
|
|
87
|
+
if (/<title[\s>]/i.test(headHtml)) out = out.replace(/<title>[\s\S]*?<\/title>\s*/i, "");
|
|
88
|
+
// Function replacer so `$` in `headHtml` (e.g. a price in a meta description) is literal.
|
|
89
|
+
return out.replace(/<\/head>/i, () => `${headHtml}\n</head>`);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const ROUTE_HEAD_TAG = /<(meta|link)\b[^>]*>\s*|<script\b([^>]*)>[\s\S]*?<\/script>\s*/gi;
|
|
93
|
+
|
|
94
|
+
/** The attribute `name`'s value in an opening tag, lower-cased; "" if absent. */
|
|
95
|
+
function attrOf(tag, name) {
|
|
96
|
+
const m = tag.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i"));
|
|
97
|
+
return (m ? (m[1] ?? m[2] ?? m[3]) : "").toLowerCase();
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Remove the shell's route-owned SEO tags (description, robots, `og:`/`twitter:`/`article:`,
|
|
102
|
+
* canonical, JSON-LD, anything marked `data-afw-head`) so the page's own head replaces them.
|
|
103
|
+
* This is the set the client's `updateRouteHead` (runtime/head.js) removes on navigation,
|
|
104
|
+
* so a prerendered page and a client-navigated one end up with the same head.
|
|
105
|
+
*/
|
|
106
|
+
function stripRouteHead(shellHtml) {
|
|
107
|
+
const head = shellHtml.match(/<head\b[^>]*>([\s\S]*?)<\/head>/i);
|
|
108
|
+
if (!head) return shellHtml;
|
|
109
|
+
const inner = head[1].replace(ROUTE_HEAD_TAG, (tag, el) => {
|
|
110
|
+
if (/\sdata-afw-head\b/i.test(tag)) return "";
|
|
111
|
+
if (el?.toLowerCase() === "meta") {
|
|
112
|
+
const name = attrOf(tag, "name");
|
|
113
|
+
const property = attrOf(tag, "property");
|
|
114
|
+
if (name === "description" || name === "robots" || name.startsWith("twitter:")) return "";
|
|
115
|
+
if (property.startsWith("og:") || property.startsWith("article:")) return "";
|
|
116
|
+
} else if (el?.toLowerCase() === "link") {
|
|
117
|
+
if (attrOf(tag, "rel") === "canonical") return "";
|
|
118
|
+
} else if (attrOf(tag, "type") === "application/ld+json") return "";
|
|
119
|
+
return tag;
|
|
120
|
+
});
|
|
121
|
+
const start = head.index + head[0].indexOf(">") + 1;
|
|
122
|
+
return shellHtml.slice(0, start) + inner + shellHtml.slice(start + head[1].length);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** Set/replace the shell's `<html lang>` for a localized page (i18n; docs/I18N.md §6). */
|
|
126
|
+
export function withHtmlLang(shellHtml, locale) {
|
|
127
|
+
if (!locale) return shellHtml;
|
|
128
|
+
if (/<html[^>]*\slang=/i.test(shellHtml)) {
|
|
129
|
+
return shellHtml.replace(/(<html[^>]*\slang=)(["'])[^"']*\2/i, `$1$2${locale}$2`);
|
|
130
|
+
}
|
|
131
|
+
return shellHtml.replace(/<html\b/i, `<html lang="${locale}"`);
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** `<link rel="modulepreload">` tags for a route's chunk hrefs (`""` when there are none). */
|
|
135
|
+
export function modulepreloadTags(hrefs) {
|
|
136
|
+
if (!hrefs || hrefs.length === 0) return "";
|
|
137
|
+
return hrefs.map((h) => `<link rel="modulepreload" href="${h}">`).join("\n");
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Escape text for an XML/HTML attribute or text node. */
|
|
141
|
+
export function escapeXml(s) {
|
|
142
|
+
return String(s).replace(/[&<>'"]/g, (c) =>
|
|
143
|
+
c === "&" ? "&" : c === "<" ? "<" : c === ">" ? ">" : c === "'" ? "'" : """,
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** The locale settings, or `null` when i18n is off. */
|
|
148
|
+
export function i18nSettings(i18n) {
|
|
149
|
+
if (!i18n || !Array.isArray(i18n.locales) || !i18n.locales.length) return null;
|
|
150
|
+
return { locales: i18n.locales, defaultLocale: i18n.defaultLocale ?? i18n.locales[0] };
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** Prefix a locale-agnostic path with `locale` (bare for the default locale). */
|
|
154
|
+
export function localizePath(path, locale, defaultLocale) {
|
|
155
|
+
if (!locale || locale === defaultLocale) return path;
|
|
156
|
+
return path === "/" ? `/${locale}` : `/${locale}${path}`;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** Split a URL path into its locale and locale-agnostic path. */
|
|
160
|
+
export function splitLocale(pathname, i18n) {
|
|
161
|
+
const settings = i18nSettings(i18n);
|
|
162
|
+
if (!settings) return { locale: null, path: pathname };
|
|
163
|
+
const m = pathname.match(/^\/([^/]+)(\/.*|)$/);
|
|
164
|
+
if (m && m[1] !== settings.defaultLocale && settings.locales.includes(m[1])) return { locale: m[1], path: m[2] || "/" };
|
|
165
|
+
return { locale: settings.defaultLocale, path: pathname };
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** `rel="alternate" hreflang` links for a path across every locale, plus x-default. */
|
|
169
|
+
export function alternateLinks(path, i18n) {
|
|
170
|
+
const settings = i18nSettings(i18n);
|
|
171
|
+
if (!settings) return [];
|
|
172
|
+
const links = settings.locales.map((l) => ({ rel: "alternate", hreflang: l, href: localizePath(path, l, settings.defaultLocale) }));
|
|
173
|
+
links.push({ rel: "alternate", hreflang: "x-default", href: localizePath(path, settings.defaultLocale, settings.defaultLocale) });
|
|
174
|
+
return links;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* Render one URL into a complete HTML document.
|
|
179
|
+
*
|
|
180
|
+
* `render` is `{ renderRoute, renderHead }` from the server bundle. `url` is the
|
|
181
|
+
* request path (locale prefix included); `params` overrides the matched route's
|
|
182
|
+
* params (static generation from `getStaticPaths`). With `loaders` (a
|
|
183
|
+
* `createLoaderRegistry`), the route's loader runs with `loaderContext`
|
|
184
|
+
* (`{ request, query, locals }`); a loader calling `notFound()` renders the 404 page.
|
|
185
|
+
* `shell` is the client's `index.html`; a hydrating build marks it with
|
|
186
|
+
* `stampHydrateSentinel` first. `preload` is extra head markup (modulepreload tags).
|
|
187
|
+
* `modifiedTime` adds `article:modified_time` on article pages. `notFound`: what a
|
|
188
|
+
* loader's `notFound()` does — `"render"` the 404 page (a request server), or
|
|
189
|
+
* `"throw"` it to the caller (static generation, which reports the path as failed).
|
|
190
|
+
*
|
|
191
|
+
* @returns {Promise<{ status: number, html: string, dataJson: string, loaded: boolean, metadata: object } | null>}
|
|
192
|
+
* `null` when no page and no 404 page match.
|
|
193
|
+
*/
|
|
194
|
+
export async function renderDocument(render, {
|
|
195
|
+
shell, url, params = null, search = "", loaders = null, loaderContext = {}, baseUrl = "", i18n = null,
|
|
196
|
+
preload = "", modifiedTime = null, notFound = "render",
|
|
197
|
+
} = {}) {
|
|
198
|
+
const { locale, path } = splitLocale(url, i18n);
|
|
199
|
+
const match = loaders?.match(url);
|
|
200
|
+
let data;
|
|
201
|
+
let dataJson = "";
|
|
202
|
+
if (match) {
|
|
203
|
+
try {
|
|
204
|
+
({ data, json: dataJson } = await loaders.loadSerialized(match, { query: {}, ...loaderContext }));
|
|
205
|
+
} catch (e) {
|
|
206
|
+
if (e?.afwNotFound !== true || notFound === "throw") throw e;
|
|
207
|
+
return renderNotFound(render, { shell, baseUrl, preload });
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
const result = await render.renderRoute(url, params, search, { data });
|
|
211
|
+
if (!result) return null;
|
|
212
|
+
const { html, metadata = {}, hydration = "", status = 200 } = result;
|
|
213
|
+
const alternates = alternateLinks(path, i18n);
|
|
214
|
+
const meta = alternates.length ? { ...metadata, links: [...(metadata.links || []), ...alternates] } : metadata;
|
|
215
|
+
let head = render.renderHead(status === 404 ? { robots: "noindex", ...meta } : meta, { path: url, baseUrl, managed: true });
|
|
216
|
+
if (preload) head += `\n${preload}`;
|
|
217
|
+
// Article tags only on an article: `og:type` "article", or a page with a publish
|
|
218
|
+
// `date`. An index or a landing page is a website; a modified time there describes nothing.
|
|
219
|
+
const published = typeof metadata?.date === "string" ? metadata.date.trim() : "";
|
|
220
|
+
const article = metadata?.openGraph?.type === "article" || Boolean(published);
|
|
221
|
+
if (article && modifiedTime) head += `\n<meta data-afw-head="" property="article:modified_time" content="${escapeXml(modifiedTime)}">`;
|
|
222
|
+
if (published) head += `\n<meta data-afw-head="" property="article:published_time" content="${escapeXml(published)}">`;
|
|
223
|
+
const document = injectRouteData(
|
|
224
|
+
injectHydrationData(
|
|
225
|
+
injectMarkup(injectHead(withHtmlLang(stampRenderedPath(shell, url), locale), head), html),
|
|
226
|
+
hydration,
|
|
227
|
+
),
|
|
228
|
+
dataJson,
|
|
229
|
+
);
|
|
230
|
+
return { status, html: document, dataJson, loaded: !!match, metadata };
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** The 404 page as a document (`noindex`), or `null` when the app has none. */
|
|
234
|
+
export async function renderNotFound(render, { shell, baseUrl = "", preload = "" } = {}) {
|
|
235
|
+
const result = await render.renderRoute("/__afw_404__");
|
|
236
|
+
if (!result) return null;
|
|
237
|
+
let head = render.renderHead({ robots: "noindex", ...result.metadata }, { baseUrl, managed: true });
|
|
238
|
+
if (preload) head += `\n${preload}`;
|
|
239
|
+
return {
|
|
240
|
+
status: 404,
|
|
241
|
+
html: injectHydrationData(injectMarkup(injectHead(shell, head), result.html), result.hydration),
|
|
242
|
+
dataJson: "",
|
|
243
|
+
loaded: false,
|
|
244
|
+
metadata: result.metadata ?? {},
|
|
245
|
+
};
|
|
246
|
+
}
|
package/host.js
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
// The host interface: everything `@opentf/afw-build` needs from the platform it runs
|
|
2
|
+
// on. This package never imports `runtime:*` or `node:*`; each toolchain integration
|
|
3
|
+
// (`@opentf/esdev-plugin-afw` on ES-Runtime, `@opentf/vite-plugin-afw` on Node)
|
|
4
|
+
// supplies one of these objects, so the build logic is written once.
|
|
5
|
+
//
|
|
6
|
+
// Paths are absolute and `/`-separated in everything the host returns.
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* @typedef {object} DirEntry
|
|
10
|
+
* @property {string} name
|
|
11
|
+
* @property {boolean} isFile
|
|
12
|
+
* @property {boolean} isDir
|
|
13
|
+
* @property {boolean} [isSymlink]
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* @typedef {object} ChildProcess
|
|
18
|
+
* @property {WritableStream<Uint8Array>} stdin
|
|
19
|
+
* @property {ReadableStream<Uint8Array>} stdout
|
|
20
|
+
* @property {() => void} kill
|
|
21
|
+
* @property {() => void} [ref] Keep the parent process alive (a compile is in flight).
|
|
22
|
+
* @property {() => void} [unref] Let the parent exit while the child idles.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* @typedef {object} BuildHost
|
|
27
|
+
* @property {(path: string) => Promise<string>} readText Read a UTF-8 file.
|
|
28
|
+
* @property {(path: string) => Promise<DirEntry[]>} readDir List a directory.
|
|
29
|
+
* @property {(path: string, text: string) => Promise<void>} writeText
|
|
30
|
+
* Write a UTF-8 file, creating missing parent directories.
|
|
31
|
+
* @property {(path: string) => Promise<"file" | "dir" | null>} kind
|
|
32
|
+
* What is at `path` (symlinks followed), or `null` when nothing is, or it is unreadable.
|
|
33
|
+
* @property {(program: string, args: string[]) => Promise<ChildProcess>} spawn
|
|
34
|
+
* Start a long-lived child with piped stdin/stdout and inherited stderr.
|
|
35
|
+
* @property {(program: string, args: string[], options?: { cwd?: string, inherit?: boolean }) => Promise<{ ok: boolean, code: number | null }>} run
|
|
36
|
+
* Run a command to completion. A missing program resolves `{ ok: false }`.
|
|
37
|
+
* @property {() => string} cwd
|
|
38
|
+
* @property {Record<string, string | undefined>} env
|
|
39
|
+
* @property {{ join: (...parts: string[]) => string, dirname: (path: string) => string, resolve: (...parts: string[]) => string }} path
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
/** The host methods every caller of a module here may need, checked up front so a
|
|
43
|
+
* missing method fails with its name instead of "undefined is not a function". */
|
|
44
|
+
export function assertHost(host, methods) {
|
|
45
|
+
if (!host || typeof host !== "object") throw new TypeError("afw-build: a host object is required");
|
|
46
|
+
for (const name of methods) {
|
|
47
|
+
const value = name === "path" ? host.path : host[name];
|
|
48
|
+
if (value == null) throw new TypeError(`afw-build: the host is missing \`${name}\``);
|
|
49
|
+
}
|
|
50
|
+
return host;
|
|
51
|
+
}
|
package/index.js
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// `@opentf/afw-build` — the toolchain-neutral half of AFW's build: the compiler
|
|
2
|
+
// client, compile-target rules, compiler resolution and file-convention routing.
|
|
3
|
+
// Toolchain integrations (`@opentf/esdev-plugin-afw`, `@opentf/vite-plugin-afw`)
|
|
4
|
+
// pass a host object (host.js) and wire these into their own plugin APIs.
|
|
5
|
+
|
|
6
|
+
export { assertHost } from "./host.js";
|
|
7
|
+
export { compileError, closeCompilers, startCompilerServer } from "./compiler-client.js";
|
|
8
|
+
export {
|
|
9
|
+
FRAMEWORK_IMPORT, MODES, SOURCE_FILTER, TARGETS,
|
|
10
|
+
chooseTarget, compileModule, errorStub, isRouteModule, usesServerEntry, validateOptions,
|
|
11
|
+
} from "./compile.js";
|
|
12
|
+
export { ensureCompiler, findUp, resolveCompiler } from "./resolve-compiler.js";
|
|
13
|
+
export {
|
|
14
|
+
ROUTES_ID,
|
|
15
|
+
discoverLoaders, discoverPages, findGuard, isUnpublishedPage, isUnpublishedSource,
|
|
16
|
+
resolveAppRoot, routeKey, routesModule,
|
|
17
|
+
} from "./routes.js";
|
|
18
|
+
export { SERVER_ID, discoverServerFiles, hasServerFiles, serverConflicts, serverModule } from "./server.js";
|
|
19
|
+
export {
|
|
20
|
+
DATA_FILE, alternateLinks, escapeXml, i18nSettings, injectBeforeBody, injectHead, injectHydrationData,
|
|
21
|
+
injectMarkup, injectRouteData, localizePath, modulepreloadTags, renderDocument, renderNotFound, splitLocale,
|
|
22
|
+
stampHydrateSentinel, stampRenderedPath, withHtmlLang,
|
|
23
|
+
} from "./document.js";
|
|
24
|
+
export { prerender, robotsTxt, sitemapXml } from "./prerender.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@opentf/afw-build",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "The toolchain-neutral core of AFW's build: compiler client, compile targets and file-based routing.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"scripts": {
|
|
7
|
+
"build": "cp ../../LICENSE LICENSE"
|
|
8
|
+
},
|
|
9
|
+
"exports": {
|
|
10
|
+
".": "./index.js",
|
|
11
|
+
"./document": "./document.js"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"index.js",
|
|
15
|
+
"host.js",
|
|
16
|
+
"compiler-client.js",
|
|
17
|
+
"compile.js",
|
|
18
|
+
"resolve-compiler.js",
|
|
19
|
+
"routes.js",
|
|
20
|
+
"server.js",
|
|
21
|
+
"document.js",
|
|
22
|
+
"prerender.js"
|
|
23
|
+
],
|
|
24
|
+
"keywords": [
|
|
25
|
+
"afw",
|
|
26
|
+
"opentf",
|
|
27
|
+
"build",
|
|
28
|
+
"compiler",
|
|
29
|
+
"routing"
|
|
30
|
+
],
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "https://github.com/Open-Tech-Foundation/afw.git",
|
|
34
|
+
"directory": "packages/afw-build"
|
|
35
|
+
},
|
|
36
|
+
"homepage": "https://afw.opentechf.org/docs",
|
|
37
|
+
"bugs": "https://github.com/Open-Tech-Foundation/afw/issues",
|
|
38
|
+
"license": "MIT",
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public"
|
|
41
|
+
}
|
|
42
|
+
}
|
package/prerender.js
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
// Static generation, shared by every toolchain: render each route of a built server
|
|
2
|
+
// bundle to `index.html` files (plus `__data.json` for loader routes), a `404.html`,
|
|
3
|
+
// and `sitemap.xml` / `robots.txt`. Each page is rendered by `renderDocument`, the
|
|
4
|
+
// same function a request server uses.
|
|
5
|
+
|
|
6
|
+
import { DATA_FILE, escapeXml, i18nSettings, localizePath, modulepreloadTags, renderDocument, renderNotFound } from "./document.js";
|
|
7
|
+
|
|
8
|
+
// "/" → <out>/index.html, "/post/1" → <out>/post/1/index.html.
|
|
9
|
+
function htmlPathFor(host, outDir, route) {
|
|
10
|
+
return route === "/" ? host.path.join(outDir, "index.html") : host.path.join(outDir, route, "index.html");
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
function absoluteUrl(baseUrl, path) {
|
|
14
|
+
if (!baseUrl) return "";
|
|
15
|
+
return baseUrl.replace(/\/+$/, "") + (path === "/" ? "/" : path);
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** `sitemap.xml` for the rendered paths, with `<lastmod>` where known. */
|
|
19
|
+
export function sitemapXml(baseUrl, paths, lastUpdated = {}) {
|
|
20
|
+
const urls = paths
|
|
21
|
+
.map((p) => {
|
|
22
|
+
const lastmod = lastUpdated[p] ? `<lastmod>${escapeXml(lastUpdated[p])}</lastmod>` : "";
|
|
23
|
+
return ` <url><loc>${escapeXml(absoluteUrl(baseUrl, p))}</loc>${lastmod}</url>`;
|
|
24
|
+
})
|
|
25
|
+
.join("\n");
|
|
26
|
+
return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** A permissive `robots.txt`, pointing at the sitemap when there is one. */
|
|
30
|
+
export function robotsTxt(baseUrl, hasSitemap) {
|
|
31
|
+
let body = "User-agent: *\nAllow: /\n";
|
|
32
|
+
if (baseUrl && hasSitemap) body += `Sitemap: ${absoluteUrl(baseUrl, "/sitemap.xml")}\n`;
|
|
33
|
+
return body;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Pre-render the app into `outDir`.
|
|
38
|
+
*
|
|
39
|
+
* `render` is the server bundle's render API (`renderRoute`, `renderHead`,
|
|
40
|
+
* `collectRoutePaths`, `resolveMetadata`). `shellHtml` is the client's `index.html`
|
|
41
|
+
* (marked for hydration by the caller when the client hydrates). `loaders` is the
|
|
42
|
+
* loader registry, run at build time with no request and an empty query. A
|
|
43
|
+
* `public/sitemap.xml` or `public/robots.txt` in `publicDir` wins over the generated one.
|
|
44
|
+
*
|
|
45
|
+
* @returns {Promise<{ count: number, skipped: string[], failed: string[], siteDescription: string, paths: string[] }>}
|
|
46
|
+
* `siteDescription` is the site's own description (home route, else the root
|
|
47
|
+
* layout's metadata) for summaries such as `llms.txt`.
|
|
48
|
+
*/
|
|
49
|
+
export async function prerender(host, {
|
|
50
|
+
render, shellHtml, outDir, publicDir, baseUrl = "", lastUpdated = {}, i18n = null, loaders = null,
|
|
51
|
+
chunkManifest = null, onRender,
|
|
52
|
+
}) {
|
|
53
|
+
const settings = i18nSettings(i18n);
|
|
54
|
+
const locales = settings ? settings.locales : [null];
|
|
55
|
+
const defaultLocale = settings?.defaultLocale ?? null;
|
|
56
|
+
const { paths, skipped } = await render.collectRoutePaths();
|
|
57
|
+
const preloadFor = (route) => modulepreloadTags(chunkManifest?.routes?.[route]);
|
|
58
|
+
|
|
59
|
+
const failed = [];
|
|
60
|
+
const rendered = [];
|
|
61
|
+
let count = 0;
|
|
62
|
+
let siteDescription = "";
|
|
63
|
+
for (const { path, params, route } of paths) {
|
|
64
|
+
onRender?.(++count, paths.length);
|
|
65
|
+
for (const locale of locales) {
|
|
66
|
+
const url = localizePath(path, locale, defaultLocale);
|
|
67
|
+
try {
|
|
68
|
+
const doc = await renderDocument(render, {
|
|
69
|
+
shell: shellHtml, url, params, loaders, baseUrl, i18n, notFound: "throw",
|
|
70
|
+
preload: preloadFor(route), modifiedTime: lastUpdated[path] ?? null,
|
|
71
|
+
});
|
|
72
|
+
if (path === "/" && (!locale || locale === defaultLocale) && typeof doc?.metadata?.description === "string") {
|
|
73
|
+
siteDescription = doc.metadata.description;
|
|
74
|
+
}
|
|
75
|
+
// Static hosts decode requested URLs when locating files. Decode generated
|
|
76
|
+
// segments once; leave literal static folder names unchanged.
|
|
77
|
+
const outputPath = Object.keys(params ?? {}).length ? url.split("/").map(decodeURIComponent).join("/") : url;
|
|
78
|
+
const file = htmlPathFor(host, outDir, outputPath);
|
|
79
|
+
await host.writeText(file, doc?.html ?? shellHtml);
|
|
80
|
+
// The static data file SPA navigation fetches on a plain static host —
|
|
81
|
+
// byte-identical to the inline payload ("null" for an undefined result).
|
|
82
|
+
if (doc?.loaded) await host.writeText(host.path.join(host.path.dirname(file), DATA_FILE), doc.dataJson || "null");
|
|
83
|
+
rendered.push(url);
|
|
84
|
+
} catch (e) {
|
|
85
|
+
failed.push(url);
|
|
86
|
+
const why = e?.afwNotFound ? "loader called notFound()" : (e?.message ?? e);
|
|
87
|
+
console.error(`✗ pre-render failed for ${url}: ${why}`);
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
// Any unmatched path is served the 404 page by static hosts.
|
|
93
|
+
try {
|
|
94
|
+
const notFound = await renderNotFound(render, { shell: shellHtml, baseUrl, preload: modulepreloadTags(chunkManifest?.notFound) });
|
|
95
|
+
if (notFound) await host.writeText(host.path.join(outDir, "404.html"), notFound.html);
|
|
96
|
+
} catch {
|
|
97
|
+
/* no 404 page */
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
let hasSitemap = false;
|
|
101
|
+
if (!(await host.kind(host.path.join(publicDir, "sitemap.xml")))) {
|
|
102
|
+
if (baseUrl) {
|
|
103
|
+
await host.writeText(host.path.join(outDir, "sitemap.xml"), sitemapXml(baseUrl, rendered, lastUpdated));
|
|
104
|
+
hasSitemap = true;
|
|
105
|
+
} else {
|
|
106
|
+
console.warn("⚠ sitemap.xml skipped: no site URL (set a base URL)");
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
if (!(await host.kind(host.path.join(publicDir, "robots.txt")))) {
|
|
110
|
+
await host.writeText(host.path.join(outDir, "robots.txt"), robotsTxt(baseUrl, hasSitemap));
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// No "/" route (or it declared no description): fall back to the layout chain's
|
|
114
|
+
// route-independent metadata — the site-wide description every route inherits.
|
|
115
|
+
if (!siteDescription) {
|
|
116
|
+
try {
|
|
117
|
+
const siteMeta = await render.resolveMetadata({ route: "/", entry: null });
|
|
118
|
+
if (typeof siteMeta?.description === "string") siteDescription = siteMeta.description;
|
|
119
|
+
} catch {
|
|
120
|
+
/* no root layout metadata */
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
return { count: rendered.length, skipped, failed, siteDescription, paths: rendered };
|
|
124
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
// Locate the `afwc` binary: `AFWC_BIN`, else the prebuilt binary from
|
|
2
|
+
// `@opentf/afw-compiler`, else — in a source checkout of this repository — the cargo
|
|
3
|
+
// build, compiled on demand. Failures throw; the toolchain decides how to report them.
|
|
4
|
+
|
|
5
|
+
/** Nearest ancestor directory of `from` (inclusive) that contains `name`. */
|
|
6
|
+
export async function findUp(host, name, from) {
|
|
7
|
+
let dir = from;
|
|
8
|
+
for (;;) {
|
|
9
|
+
if (await host.kind(host.path.join(dir, name))) return dir;
|
|
10
|
+
const parent = host.path.dirname(dir);
|
|
11
|
+
if (parent === dir) return null;
|
|
12
|
+
dir = parent;
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
async function hasLocalCompilerWorkspace(host, workspace) {
|
|
17
|
+
return !!workspace && (await host.kind(host.path.join(workspace, "crates", "afw_cli", "Cargo.toml"))) === "file";
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** Build `afwc` from the source checkout at `workspace` unless it already exists. */
|
|
21
|
+
export async function ensureCompiler(host, afwc, workspace) {
|
|
22
|
+
if (await host.kind(afwc)) return;
|
|
23
|
+
if (!workspace) throw new Error(`afwc compiler not found at ${afwc}`);
|
|
24
|
+
console.log("building compiler (cargo build -p afw_cli)…");
|
|
25
|
+
const cargo = await host.run("cargo", ["--version"], { cwd: workspace });
|
|
26
|
+
if (!cargo.ok) {
|
|
27
|
+
throw new Error(
|
|
28
|
+
`cannot build afwc because cargo is not available.\n` +
|
|
29
|
+
` This source checkout needs Rust/Cargo to build ${afwc}.\n` +
|
|
30
|
+
` Install Rust in the build environment, set AFWC_BIN to an existing afwc binary,\n` +
|
|
31
|
+
` or install the published packages so @opentf/afw-compiler can use its prebuilt binary.`,
|
|
32
|
+
);
|
|
33
|
+
}
|
|
34
|
+
const built = await host.run("cargo", ["build", "-p", "afw_cli"], { cwd: workspace, inherit: true });
|
|
35
|
+
if (!built.ok) throw new Error(`cargo build -p afw_cli failed (exit ${built.code ?? "unknown"})`);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Resolve the compiler binary. `cliDir` is the calling package's directory: a copy
|
|
40
|
+
* installed under `node_modules` never builds from source, a workspace checkout may.
|
|
41
|
+
* `resolvePackagedCompiler` is the platform's `afwcPath` from `@opentf/afw-compiler`.
|
|
42
|
+
* `findWorkspace` and `ensure` are injectable for tests.
|
|
43
|
+
*
|
|
44
|
+
* @returns {Promise<{ afwc: string, workspace: string | null }>}
|
|
45
|
+
*/
|
|
46
|
+
export async function resolveCompiler(host, {
|
|
47
|
+
cliDir,
|
|
48
|
+
env = host.env,
|
|
49
|
+
resolvePackagedCompiler,
|
|
50
|
+
findWorkspace = (name, from) => findUp(host, name, from),
|
|
51
|
+
ensure = (afwc, workspace) => ensureCompiler(host, afwc, workspace),
|
|
52
|
+
} = {}) {
|
|
53
|
+
if (env.AFWC_BIN) return { afwc: env.AFWC_BIN, workspace: null };
|
|
54
|
+
|
|
55
|
+
let packagedError = null;
|
|
56
|
+
try {
|
|
57
|
+
if (typeof resolvePackagedCompiler !== "function") throw new Error("no packaged compiler resolver");
|
|
58
|
+
return { afwc: await resolvePackagedCompiler(), workspace: null };
|
|
59
|
+
} catch (e) {
|
|
60
|
+
packagedError = e;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const installedPackage = !!cliDir && cliDir.split(/[\\/]/).includes("node_modules");
|
|
64
|
+
const workspace = installedPackage || !cliDir ? null : await findWorkspace("Cargo.toml", cliDir);
|
|
65
|
+
if (await hasLocalCompilerWorkspace(host, workspace)) {
|
|
66
|
+
const afwc = host.path.join(workspace, "target", "debug", "afwc");
|
|
67
|
+
await ensure(afwc, workspace);
|
|
68
|
+
return { afwc, workspace };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
throw new Error(
|
|
72
|
+
`${packagedError?.message ?? "cannot resolve @opentf/afw-compiler prebuilt binary"}\n` +
|
|
73
|
+
` No local afwc compiler workspace was found to build from source.`,
|
|
74
|
+
);
|
|
75
|
+
}
|
package/routes.js
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
// File-convention routing shared by every toolchain: crawl `app/` for page, layout,
|
|
2
|
+
// 404 and loader files and generate the `@afw/routes` module an entry imports:
|
|
3
|
+
//
|
|
4
|
+
// import { mountApp } from "@opentf/afw";
|
|
5
|
+
// import { guard, pages, loaderRoutes } from "@afw/routes";
|
|
6
|
+
//
|
|
7
|
+
// Route keys keep their `/app/...` shape because the runtime's `routeFromPath`
|
|
8
|
+
// anchors on it; layouts compose by path (`layout.jsx` wraps its directory).
|
|
9
|
+
|
|
10
|
+
/** The specifier entries import. */
|
|
11
|
+
export const ROUTES_ID = "@afw/routes";
|
|
12
|
+
|
|
13
|
+
const PAGE_FILE = /^(page|layout|404)\.(mdx|md|jsx|tsx)$/;
|
|
14
|
+
const LOADER_FILE = /^loader\.(js|ts)$/;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Whether Markdown source is unpublished: frontmatter `draft: true`, or a `date`
|
|
18
|
+
* later than `now` (scheduled). Production builds leave such pages out of the route
|
|
19
|
+
* table, so their text never reaches a bundle; dev servers keep them. The same rule
|
|
20
|
+
* as `@opentf/afw-docs` publish.js, which drives the post list, feeds and docs nav.
|
|
21
|
+
*/
|
|
22
|
+
export function isUnpublishedSource(source, now = Date.now()) {
|
|
23
|
+
const block = source.match(/^?---\r?\n([\s\S]*?)\r?\n---/)?.[1];
|
|
24
|
+
if (!block) return false;
|
|
25
|
+
const field = (key) => {
|
|
26
|
+
const m = block.match(new RegExp(`^\\s*${key}\\s*:\\s*(.*?)\\s*$`, "m"));
|
|
27
|
+
return m ? m[1].replace(/^(["'])(.*)\1$/, "$2") : null;
|
|
28
|
+
};
|
|
29
|
+
if (field("draft") === "true") return true;
|
|
30
|
+
const date = field("date");
|
|
31
|
+
if (!date) return false;
|
|
32
|
+
const at = new Date(date).getTime();
|
|
33
|
+
return !Number.isNaN(at) && at > now;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** {@link isUnpublishedSource} for a file; non-Markdown and unreadable files are published. */
|
|
37
|
+
export async function isUnpublishedPage(host, path, now = Date.now()) {
|
|
38
|
+
if (!/\.(mdx|md)$/.test(path)) return false;
|
|
39
|
+
let source;
|
|
40
|
+
try {
|
|
41
|
+
source = await host.readText(path);
|
|
42
|
+
} catch {
|
|
43
|
+
return false;
|
|
44
|
+
}
|
|
45
|
+
return isUnpublishedSource(source, now);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Every file under `dir` whose name matches `pattern`, as `/`-separated paths
|
|
50
|
+
* relative to `dir`, sorted. Dot directories and `node_modules` are skipped, and
|
|
51
|
+
* so are excluded subtrees (`exclude` holds paths relative to `dir`).
|
|
52
|
+
*/
|
|
53
|
+
async function walk(host, dir, pattern, exclude) {
|
|
54
|
+
const found = [];
|
|
55
|
+
async function visit(abs, rel) {
|
|
56
|
+
let entries;
|
|
57
|
+
try {
|
|
58
|
+
entries = await host.readDir(abs);
|
|
59
|
+
} catch {
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
for (const entry of entries) {
|
|
63
|
+
const childRel = rel ? `${rel}/${entry.name}` : entry.name;
|
|
64
|
+
if ([...exclude].some((name) => childRel === name || childRel.startsWith(`${name}/`))) continue;
|
|
65
|
+
const childAbs = host.path.join(abs, entry.name);
|
|
66
|
+
let isDir = entry.isDir;
|
|
67
|
+
let isFile = entry.isFile;
|
|
68
|
+
if (entry.isSymlink) {
|
|
69
|
+
const kind = await host.kind(childAbs);
|
|
70
|
+
isDir = kind === "dir";
|
|
71
|
+
isFile = kind === "file";
|
|
72
|
+
}
|
|
73
|
+
if (isDir) {
|
|
74
|
+
if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
|
|
75
|
+
await visit(childAbs, childRel);
|
|
76
|
+
} else if (isFile && pattern.test(entry.name)) {
|
|
77
|
+
found.push(childRel);
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
await visit(dir, "");
|
|
82
|
+
return found.sort();
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Page, layout and 404 files under `dir`, as absolute paths. A Markdown 404 is an
|
|
87
|
+
* error (the runtime has no Markdown fallback route). Without `drafts`,
|
|
88
|
+
* unpublished Markdown pages are left out.
|
|
89
|
+
*/
|
|
90
|
+
export async function discoverPages(host, dir, { exclude = [], drafts = true } = {}) {
|
|
91
|
+
const out = [];
|
|
92
|
+
for (const rel of await walk(host, dir, PAGE_FILE, new Set(exclude))) {
|
|
93
|
+
const abs = host.path.join(dir, rel);
|
|
94
|
+
if (/(^|\/)404\.(mdx|md)$/.test(rel)) {
|
|
95
|
+
throw new Error(`Unsupported Markdown 404 route: ${abs}. Use 404.jsx or 404.tsx instead.`);
|
|
96
|
+
}
|
|
97
|
+
if (!drafts && (await isUnpublishedPage(host, abs))) continue;
|
|
98
|
+
out.push(abs);
|
|
99
|
+
}
|
|
100
|
+
return out;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** Loader files under `dir` as `[route, absPath]` pairs, sorted by route. A route
|
|
104
|
+
* with both `loader.js` and `loader.ts` is an error. */
|
|
105
|
+
export async function discoverLoaders(host, dir, { exclude = [] } = {}) {
|
|
106
|
+
const routes = new Map();
|
|
107
|
+
for (const rel of await walk(host, dir, LOADER_FILE, new Set(exclude))) {
|
|
108
|
+
const pattern = rel.replace(/(^|\/)loader\.(js|ts)$/, "") || "/";
|
|
109
|
+
const route = pattern.startsWith("/") ? pattern : `/${pattern}`;
|
|
110
|
+
const abs = host.path.join(dir, rel);
|
|
111
|
+
if (routes.has(route)) throw new Error(`Conflicting loaders for ${route}: ${routes.get(route)} and ${abs}`);
|
|
112
|
+
routes.set(route, abs);
|
|
113
|
+
}
|
|
114
|
+
return [...routes].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function stripAppPrefix(filePath, appDir) {
|
|
118
|
+
if (appDir) {
|
|
119
|
+
const base = appDir.replace(/\/+$/, "");
|
|
120
|
+
if (filePath.startsWith(base + "/")) return filePath.slice(base.length);
|
|
121
|
+
}
|
|
122
|
+
return filePath.replace(/^.*\/app(?=\/)/, "");
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** The route-table key for a route file — keeps `/app` so `routeFromPath` resolves it. */
|
|
126
|
+
export function routeKey(filePath, appDir) {
|
|
127
|
+
return `/app${stripAppPrefix(filePath, appDir)}`;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** The optional `app/routeGuard.{js,ts}`, or null. */
|
|
131
|
+
export async function findGuard(host, appDir) {
|
|
132
|
+
for (const name of ["routeGuard.js", "routeGuard.ts"]) {
|
|
133
|
+
const path = host.path.join(appDir, name);
|
|
134
|
+
if ((await host.kind(path)) === "file") return path;
|
|
135
|
+
}
|
|
136
|
+
return null;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* The app directory for an entry. A leaf `appDir` ("app") anchors at the importing
|
|
141
|
+
* entry's site root — the nearest ancestor holding that folder — so one option value
|
|
142
|
+
* serves every app in a repository. A nested path ("website/app") resolves against
|
|
143
|
+
* the working directory.
|
|
144
|
+
*/
|
|
145
|
+
export async function resolveAppRoot(host, appDir, importer) {
|
|
146
|
+
if (appDir.includes("/") || !importer) return host.path.resolve(host.cwd(), appDir);
|
|
147
|
+
let dir = host.path.dirname(importer);
|
|
148
|
+
for (;;) {
|
|
149
|
+
if ((await host.kind(host.path.join(dir, appDir))) === "dir") return host.path.join(dir, appDir);
|
|
150
|
+
const up = host.path.dirname(dir);
|
|
151
|
+
if (up === dir) return host.path.resolve(host.cwd(), appDir);
|
|
152
|
+
dir = up;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* Generate the `@afw/routes` module for the app at `root`: lazy page imports, the
|
|
158
|
+
* loader route patterns (never the loader modules — they are server-only), and the
|
|
159
|
+
* optional route guard. `files` lists every file the module was derived from, so a
|
|
160
|
+
* toolchain can rebuild it when one changes.
|
|
161
|
+
*
|
|
162
|
+
* @returns {Promise<{ code: string, files: string[] }>}
|
|
163
|
+
*/
|
|
164
|
+
export async function routesModule(host, root, { exclude = [], drafts = true } = {}) {
|
|
165
|
+
const pages = await discoverPages(host, root, { exclude, drafts });
|
|
166
|
+
const loaders = await discoverLoaders(host, root, { exclude });
|
|
167
|
+
const guard = await findGuard(host, root);
|
|
168
|
+
const map = pages
|
|
169
|
+
.map((p) => ` [${JSON.stringify(routeKey(p, root))}]: () => import(${JSON.stringify(p)}),`)
|
|
170
|
+
.join("\n");
|
|
171
|
+
const code =
|
|
172
|
+
`export const pages = {\n${map}\n};\n` +
|
|
173
|
+
`export const loaderRoutes = ${JSON.stringify(loaders.map(([route]) => route))};\n` +
|
|
174
|
+
(guard ? `export { default as guard } from ${JSON.stringify(guard)};\n` : `export const guard = undefined;\n`);
|
|
175
|
+
return { code, files: [...pages, ...loaders.map(([, file]) => file), ...(guard ? [guard] : [])] };
|
|
176
|
+
}
|
package/server.js
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
// The server half of file-based routing, shared by every toolchain: discover API
|
|
2
|
+
// routes (`route.*`), middleware (`_middleware.*`) and loaders (`loader.*`) under
|
|
3
|
+
// `app/`, check how they sit beside pages, and generate the `@afw/server` module that
|
|
4
|
+
// composes them into one Fetch handler:
|
|
5
|
+
//
|
|
6
|
+
// import { createHandler, createPageRenderer } from "@afw/server";
|
|
7
|
+
// const handle = createHandler({
|
|
8
|
+
// files: serveBuiltFile, // optional: built assets
|
|
9
|
+
// renderPage: createPageRenderer({ shell }), // optional: server-rendered pages
|
|
10
|
+
// fallback: () => new Response("Not Found", { status: 404 }),
|
|
11
|
+
// });
|
|
12
|
+
// const response = await handle(request);
|
|
13
|
+
// // middleware → API routes → loader data → files → page render → fallback
|
|
14
|
+
|
|
15
|
+
import { discoverPages, routeKey } from "./routes.js";
|
|
16
|
+
|
|
17
|
+
/** The specifier a server entry imports. */
|
|
18
|
+
export const SERVER_ID = "@afw/server";
|
|
19
|
+
|
|
20
|
+
const ROUTE_FILE = /^route\.(jsx?|tsx?)$/;
|
|
21
|
+
const MIDDLEWARE_FILE = /^_middleware\.(jsx?|tsx?)$/;
|
|
22
|
+
const LOADER_FILE = /^loader\.(js|ts)$/;
|
|
23
|
+
const PAGE_FILE = /^page\.(mdx|md|jsx|tsx)$/;
|
|
24
|
+
|
|
25
|
+
async function walk(host, dir, exclude, visitFile) {
|
|
26
|
+
async function visit(abs, rel) {
|
|
27
|
+
let entries;
|
|
28
|
+
try {
|
|
29
|
+
entries = await host.readDir(abs);
|
|
30
|
+
} catch {
|
|
31
|
+
return;
|
|
32
|
+
}
|
|
33
|
+
for (const entry of entries) {
|
|
34
|
+
const childRel = rel ? `${rel}/${entry.name}` : entry.name;
|
|
35
|
+
if ([...exclude].some((name) => childRel === name || childRel.startsWith(`${name}/`))) continue;
|
|
36
|
+
const childAbs = host.path.join(abs, entry.name);
|
|
37
|
+
let isDir = entry.isDir;
|
|
38
|
+
let isFile = entry.isFile;
|
|
39
|
+
if (entry.isSymlink) {
|
|
40
|
+
const kind = await host.kind(childAbs);
|
|
41
|
+
isDir = kind === "dir";
|
|
42
|
+
isFile = kind === "file";
|
|
43
|
+
}
|
|
44
|
+
if (isDir) {
|
|
45
|
+
if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
|
|
46
|
+
await visit(childAbs, childRel);
|
|
47
|
+
} else if (isFile) {
|
|
48
|
+
visitFile(entry.name, childAbs, rel);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
await visit(dir, "");
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Server files under `dir`, as sorted absolute paths, plus each folder's page (for
|
|
57
|
+
* the conflict checks).
|
|
58
|
+
*
|
|
59
|
+
* @returns {Promise<{ routes: string[], middleware: string[], loaders: string[], pages: Map<string, string> }>}
|
|
60
|
+
*/
|
|
61
|
+
export async function discoverServerFiles(host, dir, { exclude = [] } = {}) {
|
|
62
|
+
const routes = [], middleware = [], loaders = [];
|
|
63
|
+
const pages = new Map(); // folder (relative, "" for the root) → page file
|
|
64
|
+
await walk(host, dir, new Set(exclude), (name, abs, folder) => {
|
|
65
|
+
if (ROUTE_FILE.test(name)) routes.push(abs);
|
|
66
|
+
else if (MIDDLEWARE_FILE.test(name)) middleware.push(abs);
|
|
67
|
+
else if (LOADER_FILE.test(name)) loaders.push(abs);
|
|
68
|
+
else if (PAGE_FILE.test(name)) pages.set(folder, abs);
|
|
69
|
+
});
|
|
70
|
+
return { routes: routes.sort(), middleware: middleware.sort(), loaders: loaders.sort(), pages };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** Whether the app has anything for a server to run. */
|
|
74
|
+
export function hasServerFiles({ routes, middleware, loaders }) {
|
|
75
|
+
return routes.length + middleware.length + loaders.length > 0;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const folderOf = (host, dir, file) => {
|
|
79
|
+
const parent = host.path.dirname(file);
|
|
80
|
+
return parent === dir ? "" : parent.slice(dir.length + 1);
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Layout mistakes the server cannot route around: a page and an API route in the
|
|
85
|
+
* same folder (both answer one URL), and a loader with no page beside it.
|
|
86
|
+
*
|
|
87
|
+
* @returns {string[]} one message per problem; empty when the layout is sound.
|
|
88
|
+
*/
|
|
89
|
+
export function serverConflicts(host, dir, files) {
|
|
90
|
+
const problems = [];
|
|
91
|
+
for (const route of files.routes) {
|
|
92
|
+
const folder = folderOf(host, dir, route);
|
|
93
|
+
if (files.pages.has(folder)) {
|
|
94
|
+
problems.push(`a page and an API route answer /${folder}: ${files.pages.get(folder)} and ${route}. Move one to another folder.`);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
for (const loader of files.loaders) {
|
|
98
|
+
const folder = folderOf(host, dir, loader);
|
|
99
|
+
if (files.pages.has(folder)) continue;
|
|
100
|
+
const beside = files.routes.some((r) => folderOf(host, dir, r) === folder);
|
|
101
|
+
problems.push(
|
|
102
|
+
`${loader} ${beside ? "sits next to a route.* API endpoint (endpoints take a Request; loaders feed pages)" : "has no sibling page.* to feed"}.`,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
return problems;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Generate the `@afw/server` module for the app at `root`. It exports the composed
|
|
110
|
+
* pieces (`apiHandler`, `apiRoutes`, `middleware`, `loaders`) and `createHandler`,
|
|
111
|
+
* whose Fetch handler runs middleware around API routes and loader data, then the
|
|
112
|
+
* optional `files` and `renderPage` steps, then `fallback`. Throws on a layout conflict.
|
|
113
|
+
*
|
|
114
|
+
* With `pages`, the module also registers every page (compiled for the server) and
|
|
115
|
+
* exports `render` (the render API static generation needs) and
|
|
116
|
+
* `createPageRenderer({ shell, baseUrl })`, a `renderPage` step built on
|
|
117
|
+
* `renderDocument`. `drafts: false` leaves unpublished Markdown pages out.
|
|
118
|
+
*
|
|
119
|
+
* @param {{ exclude?: string[], i18n?: { locales: string[], defaultLocale?: string } | null,
|
|
120
|
+
* pages?: boolean, drafts?: boolean }} [options]
|
|
121
|
+
* @returns {Promise<{ code: string, files: string[] }>}
|
|
122
|
+
*/
|
|
123
|
+
export async function serverModule(host, root, { exclude = [], i18n = null, pages = false, drafts = true } = {}) {
|
|
124
|
+
const files = await discoverServerFiles(host, root, { exclude });
|
|
125
|
+
const problems = serverConflicts(host, root, files);
|
|
126
|
+
if (problems.length) throw new Error(`AFW server routes:\n ${problems.join("\n ")}`);
|
|
127
|
+
const group = (list, prefix) => ({
|
|
128
|
+
imports: list.map((p, i) => `import * as ${prefix}${i} from ${JSON.stringify(p)};`).join("\n"),
|
|
129
|
+
map: list.map((p, i) => ` [${JSON.stringify(p)}]: ${prefix}${i},`).join("\n"),
|
|
130
|
+
});
|
|
131
|
+
const r = group(files.routes, "r"), m = group(files.middleware, "m"), l = group(files.loaders, "l");
|
|
132
|
+
const options = { appDir: root };
|
|
133
|
+
if (i18n && Array.isArray(i18n.locales) && i18n.locales.length) {
|
|
134
|
+
options.i18n = { locales: i18n.locales, defaultLocale: i18n.defaultLocale ?? i18n.locales[0] };
|
|
135
|
+
}
|
|
136
|
+
const pageFiles = pages ? await discoverPages(host, root, { exclude, drafts }) : [];
|
|
137
|
+
const p = group(pageFiles, "p");
|
|
138
|
+
const renderPart = pages
|
|
139
|
+
? `import { collectRoutePaths, configureI18n, registerRoutes, renderHead, renderRoute, resolveMetadata } from "@opentf/afw/server";\n` +
|
|
140
|
+
`import { renderDocument } from "@opentf/afw-build/document";\n` +
|
|
141
|
+
(p.imports ? `${p.imports}\n` : "") +
|
|
142
|
+
(options.i18n ? `configureI18n(options.i18n);\n` : "") +
|
|
143
|
+
`registerRoutes({\n${pageFiles.map((f, i) => ` [${JSON.stringify(routeKey(f, root))}]: p${i},`).join("\n")}\n});\n` +
|
|
144
|
+
`export const render = { renderRoute, renderHead, collectRoutePaths, resolveMetadata };\n` +
|
|
145
|
+
`/** A \`renderPage\` step: server-render page requests (\`GET\`/\`HEAD\`) into \`shell\`. */\n` +
|
|
146
|
+
`export function createPageRenderer({ shell, baseUrl = "" }) {\n` +
|
|
147
|
+
` return async (request, { locals = {} } = {}) => {\n` +
|
|
148
|
+
` const method = request.method.toUpperCase();\n` +
|
|
149
|
+
` if (method !== "GET" && method !== "HEAD") return null;\n` +
|
|
150
|
+
` const url = new URL(request.url);\n` +
|
|
151
|
+
` const doc = await renderDocument(render, {\n` +
|
|
152
|
+
` shell, url: url.pathname, search: url.search, loaders, baseUrl, i18n: options.i18n ?? null,\n` +
|
|
153
|
+
` loaderContext: { request, query: Object.fromEntries(url.searchParams), locals },\n` +
|
|
154
|
+
` });\n` +
|
|
155
|
+
` if (!doc) return null;\n` +
|
|
156
|
+
` return new Response(method === "HEAD" ? null : doc.html, {\n` +
|
|
157
|
+
` status: doc.status, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" },\n` +
|
|
158
|
+
` });\n` +
|
|
159
|
+
` };\n` +
|
|
160
|
+
`}\n`
|
|
161
|
+
: "";
|
|
162
|
+
const code =
|
|
163
|
+
`import { createApiHandler, createFetchHandler, createLoaderRegistry, createMiddleware } from "@opentf/afw/server";\n` +
|
|
164
|
+
[r.imports, m.imports, l.imports].filter(Boolean).join("\n") + "\n" +
|
|
165
|
+
`const options = ${JSON.stringify(options)};\n` +
|
|
166
|
+
`const routeModules = {\n${r.map}\n};\n` +
|
|
167
|
+
`const middlewareModules = {\n${m.map}\n};\n` +
|
|
168
|
+
`const loaderModules = {\n${l.map}\n};\n` +
|
|
169
|
+
`export const apiHandler = createApiHandler(routeModules, middlewareModules, options);\n` +
|
|
170
|
+
`export const apiRoutes = createApiHandler(routeModules, {}, options);\n` +
|
|
171
|
+
`export const middleware = createMiddleware(middlewareModules, options);\n` +
|
|
172
|
+
`export const loaders = createLoaderRegistry(loaderModules, options);\n` +
|
|
173
|
+
`export const loaderRoutes = ${JSON.stringify(loaderRoutePatterns(host, root, files.loaders))};\n` +
|
|
174
|
+
renderPart +
|
|
175
|
+
`/**\n` +
|
|
176
|
+
` * A Fetch handler. Inside the middleware: API routes, loader data (\`<path>/__data.json\`),\n` +
|
|
177
|
+
` * then \`files(request)\` and \`renderPage(request, { locals })\` when given (each may\n` +
|
|
178
|
+
` * return null to pass). Then \`fallback\`.\n` +
|
|
179
|
+
` */\n` +
|
|
180
|
+
`export function createHandler({ files, renderPage, fallback } = {}) {\n` +
|
|
181
|
+
` const terminal = async (request, env, ctx, init) => {\n` +
|
|
182
|
+
` const locals = init?.locals ?? {};\n` +
|
|
183
|
+
` return (await apiRoutes(request, env, ctx, init)) ??\n` +
|
|
184
|
+
` (await loaders.handle(request, { locals })) ??\n` +
|
|
185
|
+
` (files ? await files(request) : null) ??\n` +
|
|
186
|
+
` (renderPage ? await renderPage(request, { locals }) : null);\n` +
|
|
187
|
+
` };\n` +
|
|
188
|
+
` return createFetchHandler(terminal, { middleware, fallback });\n` +
|
|
189
|
+
`}\n`;
|
|
190
|
+
return { code, files: [...files.routes, ...files.middleware, ...files.loaders, ...pageFiles] };
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function loaderRoutePatterns(host, root, loaders) {
|
|
194
|
+
return loaders.map((file) => {
|
|
195
|
+
const folder = folderOf(host, root, file);
|
|
196
|
+
return folder ? `/${folder}` : "/";
|
|
197
|
+
}).sort();
|
|
198
|
+
}
|