@opentf/create-afw 0.1.0 → 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/templates.js CHANGED
@@ -1,11 +1,34 @@
1
- // The Vite + Node project templates. Each template is generated from one source for
2
- // both JavaScript and TypeScript, so the two never drift apart.
1
+ // The Vite + Node project templates. Each is generated from one source for both
2
+ // JavaScript and TypeScript, and for both stylings, so the variants never drift apart.
3
+ //
4
+ // Choices are independent where the framework allows it:
5
+ // app — rendering (spa / ssr / ssg) × server (API routes, middleware, loaders,
6
+ // server functions) × styling (css / tailwind). SSR always has a server.
7
+ // docs — an afw-docs site: MDX docs and a blog, prerendered, with search and feeds.
8
+ // library — a package of components published as JSX source, with a dev preview.
9
+
10
+ import { escapeHTML } from "@opentf/std";
3
11
 
4
12
  export const TEMPLATES = {
13
+ app: "An app: choose how pages render and whether it has a server",
14
+ docs: "A documentation site with a blog, search and feeds (afw-docs)",
15
+ library: "A component library published as JSX source",
16
+ };
17
+
18
+ export const RENDERINGS = {
5
19
  spa: "Single-page app, rendered in the browser",
6
- fullstack: "SPA plus API routes, middleware and loaders on a Node server",
7
- ssr: "Server-rendered pages on a Node server, hydrated in the browser",
8
- ssg: "Every page prerendered to static HTML at build time",
20
+ ssr: "Server-rendered per request, hydrated in the browser",
21
+ ssg: "Prerendered to static HTML at build time",
22
+ };
23
+
24
+ export const STYLINGS = { css: "CSS", tailwind: "Tailwind CSS" };
25
+
26
+ /** The template names of earlier releases, kept as shorthands. */
27
+ export const LEGACY_TEMPLATES = {
28
+ spa: { template: "app", render: "spa", server: false },
29
+ fullstack: { template: "app", render: "spa", server: true },
30
+ ssr: { template: "app", render: "ssr", server: true },
31
+ ssg: { template: "app", render: "ssg", server: false },
9
32
  };
10
33
 
11
34
  // The third-party tools a new project starts on. AFW's own packages take the
@@ -15,97 +38,130 @@ export const TOOL_VERSIONS = {
15
38
  vitest: "^5.0.5",
16
39
  "happy-dom": "^21.0.4",
17
40
  typescript: "^6.0.3",
41
+ tailwindcss: "^4.3.3",
42
+ "@tailwindcss/vite": "^4.3.3",
18
43
  };
19
44
 
20
- const MODE = { spa: "spa", fullstack: "spa", ssr: "ssr", ssg: "ssg" };
21
- const hasServer = (template) => template === "fullstack" || template === "ssr";
22
-
23
45
  /**
24
46
  * The files of a new project, as `{ relativePath: contents }`.
25
47
  *
26
- * @param {{ name: string, template: keyof TEMPLATES, typescript: boolean, versions: Record<string, string> }} options
48
+ * @param {{ name: string, template: keyof TEMPLATES, render?: keyof RENDERINGS, server?: boolean,
49
+ * styling?: keyof STYLINGS, typescript: boolean, versions: Record<string, string> }} options
27
50
  */
28
- export function projectFiles({ name, template, typescript, versions }) {
51
+ export function projectFiles({ name, template, render = "spa", server = false, styling = "css", typescript, versions }) {
29
52
  if (!TEMPLATES[template]) throw new Error(`Unknown template "${template}". Choose one of: ${Object.keys(TEMPLATES).join(", ")}`);
30
- const ts = typescript;
31
- const js = ts ? "ts" : "js";
32
- const jsx = ts ? "tsx" : "jsx";
33
- const server = hasServer(template);
34
- const mode = MODE[template];
35
- const files = {};
53
+ if (!RENDERINGS[render]) throw new Error(`Unknown rendering "${render}". Choose one of: ${Object.keys(RENDERINGS).join(", ")}`);
54
+ if (!STYLINGS[styling]) throw new Error(`Unknown styling "${styling}". Choose one of: ${Object.keys(STYLINGS).join(", ")}`);
55
+ const ctx = {
56
+ name, versions, ts: typescript, js: typescript ? "ts" : "js", jsx: typescript ? "tsx" : "jsx",
57
+ tailwind: styling === "tailwind",
58
+ };
59
+ if (template === "docs") return docsFiles(ctx);
60
+ if (template === "library") return libraryFiles(ctx);
61
+ return appFiles({ ...ctx, render, server: render === "ssr" || server });
62
+ }
63
+
64
+ // ---------------------------------------------------------------------------- shared
36
65
 
37
- const scripts = { dev: "vite", build: "vite build" };
38
- if (server) scripts.start = "node dist/server/index.js";
39
- else scripts.preview = "vite preview";
40
- scripts.test = "vitest run";
41
- if (ts) scripts.typecheck = "tsc";
42
- const devDependencies = {
43
- "@opentf/afw-test": versions["@opentf/afw-test"],
44
- "@opentf/vite-plugin-afw": versions["@opentf/vite-plugin-afw"],
66
+ const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
67
+ const escapeJs = (text) => String(text).replace(/[\\"]/g, "\\$&");
68
+ // ` class="…"` with Tailwind, nothing with plain CSS.
69
+ const tw = (ctx, classes) => (ctx.tailwind ? ` class="${classes}"` : "");
70
+
71
+ function devDependencies(ctx, extra = {}) {
72
+ return sortKeys({
73
+ "@opentf/afw-test": ctx.versions["@opentf/afw-test"],
74
+ "@opentf/vite-plugin-afw": ctx.versions["@opentf/vite-plugin-afw"],
45
75
  "happy-dom": TOOL_VERSIONS["happy-dom"],
46
- ...(ts ? { typescript: TOOL_VERSIONS.typescript } : {}),
76
+ ...(ctx.ts ? { typescript: TOOL_VERSIONS.typescript } : {}),
77
+ ...(ctx.tailwind ? { tailwindcss: TOOL_VERSIONS.tailwindcss, "@tailwindcss/vite": TOOL_VERSIONS["@tailwindcss/vite"] } : {}),
47
78
  vite: TOOL_VERSIONS.vite,
48
79
  vitest: TOOL_VERSIONS.vitest,
49
- };
50
- files["package.json"] = json({
51
- name, private: true, type: "module", scripts,
52
- dependencies: { "@opentf/afw": versions["@opentf/afw"] },
53
- devDependencies,
80
+ ...extra,
54
81
  });
82
+ }
83
+
84
+ function sortKeys(object) {
85
+ return Object.fromEntries(Object.entries(object).sort(([a], [b]) => a.localeCompare(b)));
86
+ }
55
87
 
56
- files[`vite.config.${js}`] = `import afw from "@opentf/vite-plugin-afw";
57
- ${ts ? 'import { defineConfig } from "vitest/config";\n' : ""}
58
- ${ts ? "export default defineConfig(" : "export default "}{
59
- plugins: [afw({ mode: "${mode}"${mode === "ssg" ? ', baseUrl: "" /* your site URL, e.g. "https://example.com", enables sitemap.xml */' : ""} })],
88
+ function viteConfig(ctx, { imports = [], plugins }) {
89
+ const lines = [
90
+ `import afw from "@opentf/vite-plugin-afw";`,
91
+ ...(ctx.tailwind ? [`import tailwindcss from "@tailwindcss/vite";`] : []),
92
+ ...imports,
93
+ ...(ctx.ts ? [`import { defineConfig } from "vitest/config";`] : []),
94
+ ];
95
+ const all = [...plugins, ...(ctx.tailwind ? ["tailwindcss()"] : [])];
96
+ return `${lines.join("\n")}
97
+
98
+ ${ctx.ts ? "export default defineConfig(" : "export default "}{
99
+ plugins: [${all.join(", ")}],
60
100
  test: {
61
101
  environment: "happy-dom",
62
102
  setupFiles: ["@opentf/afw-test/vitest"],
63
103
  },
64
- }${ts ? ")" : ""};
104
+ }${ctx.ts ? ")" : ""};
65
105
  `;
106
+ }
66
107
 
67
- if (ts) {
68
- files["tsconfig.json"] = json({
69
- compilerOptions: {
70
- target: "ESNext",
71
- module: "ESNext",
72
- moduleResolution: "bundler",
73
- lib: ["ESNext", "DOM", "DOM.Iterable"],
74
- jsx: "preserve",
75
- jsxImportSource: "@opentf/afw",
76
- types: ["@opentf/vite-plugin-afw/client"],
77
- strict: true,
78
- noEmit: true,
79
- isolatedModules: true,
80
- skipLibCheck: true,
81
- allowImportingTsExtensions: true,
82
- },
83
- include: ["app", "tests", "entry.ts", "vite.config.ts"],
84
- });
85
- }
108
+ function tsconfig(ctx, include, { allowJs = false } = {}) {
109
+ return json({
110
+ compilerOptions: {
111
+ target: "ESNext",
112
+ module: "ESNext",
113
+ moduleResolution: "bundler",
114
+ lib: ["ESNext", "DOM", "DOM.Iterable"],
115
+ jsx: "preserve",
116
+ jsxImportSource: "@opentf/afw",
117
+ types: ["@opentf/vite-plugin-afw/client"],
118
+ strict: true,
119
+ noEmit: true,
120
+ isolatedModules: true,
121
+ skipLibCheck: true,
122
+ allowImportingTsExtensions: true,
123
+ ...(allowJs ? { allowJs: true } : {}),
124
+ },
125
+ include,
126
+ });
127
+ }
86
128
 
87
- files["index.html"] = `<!doctype html>
129
+ function indexHtml(ctx, { title, css = true }) {
130
+ return `<!doctype html>
88
131
  <html lang="en">
89
132
  <head>
90
133
  <meta charset="utf-8" />
91
134
  <meta name="viewport" content="width=device-width, initial-scale=1" />
92
- <title>${escapeHtml(name)}</title>
93
- <link rel="stylesheet" href="/app/global.css" />
135
+ <title>${escapeHTML(title)}</title>${css ? `\n <link rel="stylesheet" href="/app/global.css" />` : ""}
94
136
  </head>
95
137
  <body>
96
138
  <div id="app"></div>
97
- <script type="module" src="/entry.${js}"></script>
139
+ <script type="module" src="/entry.${ctx.js}"></script>
98
140
  </body>
99
141
  </html>
100
142
  `;
143
+ }
101
144
 
102
- files[`entry.${js}`] = `import { mountApp } from "@opentf/afw";
145
+ function entry(ctx, { importCss = false } = {}) {
146
+ return `import { mountApp } from "@opentf/afw";
103
147
  import { guard, loaderRoutes, pages } from "@afw/routes";
104
-
105
- mountApp({ pages, guard, loaders: loaderRoutes, target: document.getElementById("app")${ts ? "!" : ""} });
148
+ ${importCss ? '\nimport "./app/global.css";\n' : ""}
149
+ mountApp({ pages, guard, loaders: loaderRoutes, target: document.getElementById("app")${ctx.ts ? "!" : ""} });
106
150
  `;
151
+ }
152
+
153
+ function globalCss(ctx) {
154
+ if (ctx.tailwind) {
155
+ return `@import "tailwindcss";
107
156
 
108
- files["app/global.css"] = `:root {
157
+ @layer base {
158
+ body {
159
+ @apply mx-auto max-w-3xl px-4 py-8 font-sans;
160
+ }
161
+ }
162
+ `;
163
+ }
164
+ return `:root {
109
165
  font-family: system-ui, sans-serif;
110
166
  color-scheme: light dark;
111
167
  }
@@ -122,6 +178,86 @@ nav {
122
178
  margin-bottom: 2rem;
123
179
  }
124
180
  `;
181
+ }
182
+
183
+ function counter(ctx) {
184
+ return `export default function Counter({ start = 0 }${ctx.ts ? ": { start?: number }" : ""}) {
185
+ let count = $state(start);
186
+ const doubled = $derived(count * 2);
187
+
188
+ return (
189
+ <p>
190
+ <button${tw(ctx, "rounded-md bg-sky-600 px-3 py-1 text-white")} onclick={() => count++}>Count: {count}</button> Doubled: {doubled}
191
+ </p>
192
+ );
193
+ }
194
+ `;
195
+ }
196
+
197
+ function counterTest(ctx, from) {
198
+ return `import { expect, test } from "vitest";
199
+ import { render, userEvent } from "@opentf/afw-test";
200
+ import ${from.startsWith("../index") ? "{ Counter }" : "Counter"} from "${from}";
201
+
202
+ test("counts clicks", async () => {
203
+ const { getByRole, getByText } = render(Counter, { start: 1 });
204
+ await userEvent.setup().click(getByRole("button", { name: "Count: 1" }));
205
+ expect(getByRole("button").textContent).toBe("Count: 2");
206
+ expect(getByText(/Doubled: 4/)).toBeTruthy();
207
+ });
208
+ `;
209
+ }
210
+
211
+ function readme(ctx, { summary, commands, notes = [] }) {
212
+ const rows = commands.map(([command, what]) => `| \`${command}\` | ${what} |`).join("\n");
213
+ return `# ${ctx.name}
214
+
215
+ ${summary}
216
+
217
+ | Command | What it does |
218
+ | --- | --- |
219
+ ${rows}
220
+ ${notes.length ? `\n${notes.map((note) => `- ${note}`).join("\n")}\n` : ""}`;
221
+ }
222
+
223
+ function scripts(ctx, { server }) {
224
+ return {
225
+ dev: "vite",
226
+ build: "vite build",
227
+ ...(server ? { start: "node dist/server/index.js" } : { preview: "vite preview" }),
228
+ test: "vitest run",
229
+ ...(ctx.ts ? { typecheck: "tsc" } : {}),
230
+ };
231
+ }
232
+
233
+ function commandRows(ctx, { server }) {
234
+ return [
235
+ ["npm run dev", "Start the dev server"],
236
+ ["npm run build", "Build for production"],
237
+ server ? ["npm start", "Run the built Node server (`PORT`, `HOST`)"] : ["npm run preview", "Preview the production build"],
238
+ ["npm run test", "Run the tests with Vitest"],
239
+ ...(ctx.ts ? [["npm run typecheck", "Check types"]] : []),
240
+ ];
241
+ }
242
+
243
+ // ---------------------------------------------------------------------------- app
244
+
245
+ function appFiles(ctx) {
246
+ const { ts, js, jsx, render, server } = ctx;
247
+ const files = {};
248
+ files["package.json"] = json({
249
+ name: ctx.name, private: true, type: "module", scripts: scripts(ctx, { server }),
250
+ dependencies: { "@opentf/afw": ctx.versions["@opentf/afw"] },
251
+ devDependencies: devDependencies(ctx),
252
+ });
253
+ const options = render === "ssg"
254
+ ? `{ mode: "ssg", baseUrl: "" /* your site URL, e.g. "https://example.com", enables sitemap.xml */ }`
255
+ : `{ mode: "${render}" }`;
256
+ files[`vite.config.${js}`] = viteConfig(ctx, { plugins: [`afw(${options})`] });
257
+ if (ts) files["tsconfig.json"] = tsconfig(ctx, ["app", "tests", "entry.ts", "vite.config.ts"]);
258
+ files["index.html"] = indexHtml(ctx, { title: ctx.name });
259
+ files[`entry.${js}`] = entry(ctx);
260
+ files["app/global.css"] = globalCss(ctx);
125
261
 
126
262
  const navLinks = [["/", "Home"], ["/about", "About"], ...(server ? [["/todos", "Todos"]] : [])];
127
263
  files[`app/layout.${jsx}`] = `import { Link } from "@opentf/afw";
@@ -129,7 +265,7 @@ nav {
129
265
  export default function Layout({ children }${ts ? ": { children: unknown }" : ""}) {
130
266
  return (
131
267
  <>
132
- <nav>
268
+ <nav${tw(ctx, "mb-8 flex gap-4 text-sky-700")}>
133
269
  ${navLinks.map(([href, label]) => ` <Link href="${href}">${label}</Link>`).join("\n")}
134
270
  </nav>
135
271
  <main>{children}</main>
@@ -137,34 +273,21 @@ ${navLinks.map(([href, label]) => ` <Link href="${href}">${label}</Link>`
137
273
  );
138
274
  }
139
275
  `;
140
-
141
276
  files[`app/page.${jsx}`] = `import Counter from "./Counter.${jsx}";
142
277
 
143
- export const metadata = { title: "${escapeJs(name)}" };
278
+ export const metadata = { title: "${escapeJs(ctx.name)}" };
144
279
 
145
280
  export default function Home() {
146
281
  return (
147
282
  <section>
148
- <h1>${escapeHtml(name)}</h1>
283
+ <h1${tw(ctx, "mb-4 text-3xl font-bold")}>${escapeHTML(ctx.name)}</h1>
149
284
  <p>Edit <code>app/page.${jsx}</code> and save: the page updates in place.</p>
150
285
  <Counter start={0} />
151
286
  </section>
152
287
  );
153
288
  }
154
289
  `;
155
-
156
- files[`app/Counter.${jsx}`] = `export default function Counter({ start = 0 }${ts ? ": { start?: number }" : ""}) {
157
- let count = $state(start);
158
- const doubled = $derived(count * 2);
159
-
160
- return (
161
- <p>
162
- <button onclick={() => count++}>Count: {count}</button> Doubled: {doubled}
163
- </p>
164
- );
165
- }
166
- `;
167
-
290
+ files[`app/Counter.${jsx}`] = counter(ctx);
168
291
  files["app/about/page.md"] = `---
169
292
  title: About
170
293
  ---
@@ -173,14 +296,36 @@ title: About
173
296
 
174
297
  This page is Markdown. The AFW compiler turns it into a page like any other.
175
298
  `;
299
+ if (server) Object.assign(files, serverFiles(ctx));
300
+ files[`tests/Counter.test.${js}`] = counterTest(ctx, `../app/Counter.${jsx}`);
301
+ files[".gitignore"] = "node_modules\ndist\n";
176
302
 
177
- if (server) {
178
- files[`app/api/hello/route.${js}`] = `// GET /api/hello?name=… — API routes run on Node, so any npm package works here.
303
+ const how = { spa: "rendered in the browser", ssr: "server-rendered on Node", ssg: "prerendered to static HTML" }[render];
304
+ files["README.md"] = readme(ctx, {
305
+ summary: `An [AFW](https://afw.opentechf.org) app on Vite${server ? " and Node" : ""}: pages ${how}${server ? ", with a Node server" : ""}.`,
306
+ commands: commandRows(ctx, { server }),
307
+ notes: [
308
+ `Pages live in \`app/\`: \`app/about/page.md\` is served at \`/about\`.`,
309
+ ...(server ? [
310
+ `On the server: API routes (\`app/api/hello/route.${js}\`), middleware (\`app/_middleware.${js}\`), a loader (\`app/todos/loader.${js}\`) and server functions (\`app/todos/todos.server.${js}\`), which components call like async functions.`,
311
+ ] : []),
312
+ ...(ctx.tailwind ? ["Styled with Tailwind CSS: utility classes go straight into `class`."] : []),
313
+ ],
314
+ });
315
+ return files;
316
+ }
317
+
318
+ function serverFiles(ctx) {
319
+ const { ts, js, jsx } = ctx;
320
+ const files = {};
321
+ files[`app/api/hello/route.${js}`] = `// GET /api/hello?name=… — API routes run on Node, so any npm package works here.
179
322
  export function GET(request${ts ? ": Request" : ""}, { query, locals }${ts ? ": { query: Record<string, string>; locals: Record<string, unknown> }" : ""}) {
180
323
  return Response.json({ message: \`Hello, \${query.name ?? "world"}!\`, requestId: locals.requestId });
181
324
  }
182
325
  `;
183
- files[`app/_middleware.${js}`] = `// Runs for every request: pages, API routes and loader data alike.
326
+ files[`app/_middleware.${js}`] = `// Runs for every request: pages, API routes, loader data and server functions alike.
327
+ // Authenticate here (set \`context.locals.user\`); each server function checks what
328
+ // that user may read or change.
184
329
  export default async function middleware(request${ts ? ": Request" : ""}, context${ts ? ": { locals: Record<string, unknown> }" : ""}, next${ts ? ": () => Promise<Response>" : ""}) {
185
330
  context.locals.requestId = crypto.randomUUID();
186
331
  const response = await next();
@@ -188,69 +333,289 @@ export default async function middleware(request${ts ? ": Request" : ""}, contex
188
333
  return response;
189
334
  }
190
335
  `;
191
- files[`app/todos/loader.${js}`] = `// Loaders run on the server and feed their page through \`router.data\`.
192
- const todos = ["Try the dev server", "Add an API route", "Deploy with npm start"];
336
+ files[`app/todos/todos.server.${js}`] = `// Server functions: this module runs only on the server. Components import the
337
+ // functions below and call them like async functions; the browser gets fetch stubs.
338
+ import { action, query } from "@opentf/afw/server";
193
339
 
194
- export default async function loader() {
195
- return { todos };
340
+ // In memory for the example: use your database here.
341
+ const todos${ts ? ": string[]" : ""} = ["Try the dev server", "Add an API route", "Deploy with npm start"];
342
+
343
+ export const listTodos = query(async () => todos);
344
+
345
+ export const addTodo = action(async ({ title }${ts ? ": { title: string }" : ""}) => {
346
+ const text = String(title ?? "").trim();
347
+ if (!text) throw new Response(null, { status: 400 });
348
+ todos.push(text);
349
+ return todos;
350
+ });
351
+ `;
352
+ files[`app/todos/loader.${js}`] = `// Loaders run on the server and feed their page through \`router.data\`. A server
353
+ // function called from server code runs directly, with no HTTP request.
354
+ import { listTodos } from "./todos.server.${js}";
355
+
356
+ export default async function loader({ locals }${ts ? ": { locals: Record<string, unknown> }" : ""}) {
357
+ return { todos: await listTodos(undefined, { locals }) };
196
358
  }
197
359
  `;
198
- files[`app/todos/page.${jsx}`] = `import { router } from "@opentf/afw";
360
+ files[`app/todos/page.${jsx}`] = `import { invalidate, router } from "@opentf/afw";
361
+ import { addTodo } from "./todos.server.${js}";
199
362
 
200
363
  export const metadata = { title: "Todos" };
201
364
 
202
365
  export default function Todos() {
366
+ let title = $state("");
367
+ const todos = $derived(${ts ? "(router.data as { todos?: string[] } | undefined)" : "router.data"}?.todos ?? []);
368
+
369
+ async function add(event${ts ? ": SubmitEvent" : ""}) {
370
+ event.preventDefault();
371
+ await addTodo({ title });
372
+ title = "";
373
+ await invalidate(); // reload this page's loader data
374
+ }
375
+
203
376
  return (
204
377
  <section>
205
- <h1>Todos</h1>
206
- <ul>
207
- {(${ts ? "(router.data as { todos?: string[] } | undefined)" : "router.data"}?.todos ?? []).map((todo${ts ? ": string" : ""}) => <li>{todo}</li>)}
378
+ <h1${tw(ctx, "mb-4 text-2xl font-bold")}>Todos</h1>
379
+ <ul${tw(ctx, "mb-4 list-disc pl-6")}>
380
+ {todos.map((todo${ts ? ": string" : ""}) => <li>{todo}</li>)}
208
381
  </ul>
382
+ <form onsubmit={add}>
383
+ <input${tw(ctx, "rounded-md border px-2 py-1")} value={title} oninput={(e${ts ? ": Event" : ""}) => (title = (e.target${ts ? " as HTMLInputElement" : ""}).value)} placeholder="New todo" />
384
+ <button${tw(ctx, "ml-2 rounded-md bg-sky-600 px-3 py-1 text-white")} type="submit">Add</button>
385
+ </form>
209
386
  </section>
210
387
  );
211
388
  }
212
389
  `;
213
- }
390
+ return files;
391
+ }
214
392
 
215
- files[`tests/Counter.test.${js}`] = `import { expect, test } from "vitest";
216
- import { render, userEvent } from "@opentf/afw-test";
217
- import Counter from "../app/Counter.${jsx}";
393
+ // ---------------------------------------------------------------------------- docs
218
394
 
219
- test("counts clicks", async () => {
220
- const { getByRole, getByText } = render(Counter, { start: 1 });
221
- await userEvent.setup().click(getByRole("button", { name: "Count: 1" }));
222
- expect(getByRole("button").textContent).toBe("Count: 2");
223
- expect(getByText(/Doubled: 4/)).toBeTruthy();
395
+ function docsFiles(ctx) {
396
+ const { ts, js, jsx } = ctx;
397
+ const files = {};
398
+ files["package.json"] = json({
399
+ name: ctx.name, private: true, type: "module", scripts: scripts(ctx, { server: false }),
400
+ dependencies: { "@opentf/afw": ctx.versions["@opentf/afw"], "@opentf/afw-docs": ctx.versions["@opentf/afw-docs"] },
401
+ devDependencies: devDependencies({ ...ctx, tailwind: false }),
402
+ });
403
+ files[`vite.config.${js}`] = viteConfig({ ...ctx, tailwind: false }, {
404
+ imports: [`import afwDocs from "@opentf/afw-docs/vite";`],
405
+ plugins: [`afw({ mode: "ssg" })`, "afwDocs()"],
406
+ });
407
+ if (ts) files["tsconfig.json"] = tsconfig(ctx, ["app", "tests", "entry.ts", "vite.config.ts", "afw.config.js"], { allowJs: true });
408
+ files["afw.config.js"] = `import { defineDocsConfig } from "@opentf/afw-docs/config";
409
+
410
+ export default defineDocsConfig({
411
+ // Your site's URL: canonical links, sitemap.xml, feeds and llms.txt use it.
412
+ site: { url: "https://example.com" },
413
+ docs: {
414
+ title: "${escapeJs(ctx.name)}",
415
+ nav: [
416
+ { label: "Docs", href: "/docs" },
417
+ { label: "Blog", href: "/blog" },
418
+ ],
419
+ search: { provider: "afw" },
420
+ },
421
+ blog: { dir: "blog", title: "${escapeJs(ctx.name)} Blog" },
224
422
  });
225
423
  `;
424
+ files["index.html"] = indexHtml(ctx, { title: ctx.name, css: false });
425
+ files[`entry.${js}`] = entry(ctx, { importCss: true });
426
+ files["app/global.css"] = `@import "@opentf/afw-docs/theme";
427
+ `;
428
+ files[`app/layout.${jsx}`] = `export default function Root({ children }${ts ? ": { children: unknown }" : ""}) {
429
+ return <div>{children}</div>;
430
+ }
431
+ `;
432
+ files[`app/page.${jsx}`] = `import { Link } from "@opentf/afw";
226
433
 
227
- files[".gitignore"] = "node_modules\ndist\n";
434
+ export const metadata = { title: "${escapeJs(ctx.name)}", description: "Documentation and blog." };
228
435
 
229
- const run = (script) => `npm run ${script}`;
230
- files["README.md"] = `# ${name}
436
+ export default function Home() {
437
+ return (
438
+ <main class="afwd-prose">
439
+ <h1>${escapeHTML(ctx.name)}</h1>
440
+ <p>Documentation and a blog, written in MDX.</p>
441
+ <p>
442
+ <Link href="/docs">Read the docs</Link> · <Link href="/blog">Visit the blog</Link>
443
+ </p>
444
+ </main>
445
+ );
446
+ }
447
+ `;
448
+ files[`app/docs/layout.${jsx}`] = `import { DocsLayout } from "@opentf/afw-docs";
449
+ import config from "../../afw.config.js";
231
450
 
232
- An [AFW](https://afw.opentechf.org) app on Vite and Node (${TEMPLATES[template].toLowerCase()}).
451
+ export default function Docs({ children }${ts ? ": { children: unknown }" : ""}) {
452
+ return <DocsLayout config={config.docs} siteUrl={config.site.url}>{children}</DocsLayout>;
453
+ }
454
+ `;
455
+ files["app/docs/_meta.js"] = `// Sidebar order and labels. Folders not listed here follow, alphabetically.
456
+ export default {
457
+ "getting-started": "Getting Started",
458
+ guides: "Guides",
459
+ };
460
+ `;
461
+ files["app/docs/page.mdx"] = `---
462
+ title: Introduction
463
+ description: What this project is and where to start.
464
+ ---
233
465
 
234
- | Command | What it does |
235
- | --- | --- |
236
- | \`${run("dev")}\` | Start the dev server |
237
- | \`${run("build")}\` | Build for production |
238
- | ${server ? `\`npm start\` | Run the built Node server (\`PORT\`, \`HOST\`)` : `\`${run("preview")}\` | Preview the production build`} |
239
- | \`${run("test")}\` | Run the tests with Vitest |
240
- ${ts ? `| \`${run("typecheck")}\` | Check types |\n` : ""}
241
- Pages live in \`app/\`: \`app/about/page.md\` is served at \`/about\`.${server ? " API routes (`route." + js + "`), middleware (`_middleware." + js + "`) and loaders (`loader." + js + "`) run on Node." : ""}
466
+ import { Callout } from "@opentf/afw-docs";
467
+
468
+ # Introduction
469
+
470
+ Welcome to the ${escapeHTML(ctx.name)} docs.
471
+
472
+ <Callout type="tip">
473
+ Every folder under \`app/docs/\` with a \`page.mdx\` becomes a page in the sidebar.
474
+ </Callout>
242
475
  `;
243
- return files;
476
+ files["app/docs/getting-started/page.mdx"] = `---
477
+ title: Getting Started
478
+ description: Install and run the project.
479
+ ---
480
+
481
+ # Getting Started
482
+
483
+ \`\`\`bash
484
+ npm install
485
+ npm run dev
486
+ \`\`\`
487
+ `;
488
+ files["app/docs/guides/writing-pages/page.mdx"] = `---
489
+ title: Writing Pages
490
+ description: MDX pages, components and code blocks.
491
+ ---
492
+
493
+ import { Steps } from "@opentf/afw-docs";
494
+
495
+ # Writing Pages
496
+
497
+ <Steps>
498
+
499
+ ### Add a folder
500
+
501
+ Create \`app/docs/my-topic/page.mdx\`.
502
+
503
+ ### Write MDX
504
+
505
+ Markdown with components, like this list of steps.
506
+
507
+ </Steps>
508
+ `;
509
+ files[`app/blog/layout.${jsx}`] = `import { BlogLayout } from "@opentf/afw-docs";
510
+ import { posts } from "@opentf/afw-docs/posts";
511
+ import config from "../../afw.config.js";
512
+
513
+ export default function Blog({ children }${ts ? ": { children: unknown }" : ""}) {
514
+ return <BlogLayout config={config.docs} posts={posts} siteUrl={config.site.url}>{children}</BlogLayout>;
244
515
  }
516
+ `;
517
+ files[`app/blog/page.${jsx}`] = `import { PostList } from "@opentf/afw-docs";
518
+ import { posts } from "@opentf/afw-docs/posts";
245
519
 
246
- function json(value) {
247
- return `${JSON.stringify(value, null, 2)}\n`;
520
+ export const metadata = { title: "Blog" };
521
+
522
+ export default function BlogIndex() {
523
+ return (
524
+ <section>
525
+ <h1>Blog</h1>
526
+ <PostList posts={posts} />
527
+ </section>
528
+ );
248
529
  }
530
+ `;
531
+ files["app/blog/hello-world/page.mdx"] = `---
532
+ title: Hello, world
533
+ description: The first post.
534
+ date: 2026-01-01
535
+ author: ${escapeHTML(ctx.name)}
536
+ ---
249
537
 
250
- function escapeHtml(text) {
251
- return String(text).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
538
+ # Hello, world
539
+
540
+ Posts live in \`app/blog/\`; each one appears in the post list and the RSS and Atom feeds.
541
+ `;
542
+ files[`tests/Home.test.${js}`] = `import { expect, test } from "vitest";
543
+ import { render } from "@opentf/afw-test";
544
+ import Home from "../app/page.${jsx}";
545
+
546
+ test("the home page links to the docs and the blog", () => {
547
+ const { getByRole } = render(Home);
548
+ expect(getByRole("heading", { level: 1 }).textContent).toBe("${escapeJs(ctx.name)}");
549
+ expect(getByRole("link", { name: "Read the docs" }).getAttribute("href")).toBe("/docs");
550
+ });
551
+ `;
552
+ files[".gitignore"] = "node_modules\ndist\n";
553
+ files["README.md"] = readme(ctx, {
554
+ summary: "A documentation site and blog built with [AFW](https://afw.opentechf.org) and `@opentf/afw-docs` on Vite.",
555
+ commands: commandRows(ctx, { server: false }),
556
+ notes: [
557
+ "Docs pages live in `app/docs/`, posts in `app/blog/`; `app/docs/_meta.js` orders the sidebar.",
558
+ "`npm run build` prerenders every page and writes the search index, `sitemap.xml`, RSS and Atom feeds and `llms.txt`.",
559
+ "Set your site's URL in `afw.config.js`.",
560
+ ],
561
+ });
562
+ return files;
252
563
  }
253
564
 
254
- function escapeJs(text) {
255
- return String(text).replace(/[\\"]/g, "\\$&");
565
+ // ---------------------------------------------------------------------------- library
566
+
567
+ function libraryFiles(ctx) {
568
+ const { ts, js, jsx } = ctx;
569
+ const files = {};
570
+ const afw = ctx.versions["@opentf/afw"];
571
+ files["package.json"] = json({
572
+ name: ctx.name,
573
+ version: "0.1.0",
574
+ type: "module",
575
+ // Published as source: the consuming app's AFW plugin compiles it.
576
+ exports: { ".": `./index.${js}` },
577
+ files: [`index.${js}`, "src"],
578
+ sideEffects: false,
579
+ scripts: { dev: "vite", test: "vitest run", ...(ts ? { typecheck: "tsc" } : {}) },
580
+ peerDependencies: { "@opentf/afw": afw },
581
+ devDependencies: devDependencies(ctx, { "@opentf/afw": afw }),
582
+ });
583
+ files[`vite.config.${js}`] = viteConfig(ctx, { plugins: ["afw()"] });
584
+ if (ts) files["tsconfig.json"] = tsconfig(ctx, ["index.ts", "src", "app", "tests", "entry.ts", "vite.config.ts"]);
585
+ files[`index.${js}`] = `// The package entry: export each component.
586
+ export { default as Counter } from "./src/Counter.${jsx}";
587
+ `;
588
+ files[`src/Counter.${jsx}`] = counter(ctx);
589
+ // The preview app (\`npm run dev\`): not published.
590
+ files["index.html"] = indexHtml(ctx, { title: `${ctx.name} preview` });
591
+ files[`entry.${js}`] = entry(ctx);
592
+ files["app/global.css"] = globalCss(ctx);
593
+ files[`app/page.${jsx}`] = `import { Counter } from "../index.${js}";
594
+
595
+ export default function Preview() {
596
+ return (
597
+ <section>
598
+ <h1${tw(ctx, "mb-4 text-2xl font-bold")}>${escapeHTML(ctx.name)}</h1>
599
+ <Counter start={1} />
600
+ </section>
601
+ );
602
+ }
603
+ `;
604
+ files[`tests/Counter.test.${js}`] = counterTest(ctx, `../index.${js}`);
605
+ files[".gitignore"] = "node_modules\ndist\n";
606
+ files["README.md"] = readme(ctx, {
607
+ summary: "A component library for [AFW](https://afw.opentechf.org), published as JSX source.",
608
+ commands: [
609
+ ["npm run dev", "Preview the components (`app/page." + jsx + "`)"],
610
+ ["npm run test", "Run the tests with Vitest"],
611
+ ...(ts ? [["npm run typecheck", "Check types"]] : []),
612
+ ["npm publish", "Publish `index." + js + "` and `src/`"],
613
+ ],
614
+ notes: [
615
+ `Export each component from \`index.${js}\`.`,
616
+ "Apps install it next to `@opentf/afw` (a peer dependency); their AFW plugin compiles it, with Vite or esdev.",
617
+ ...(ctx.tailwind ? ["Components use Tailwind classes: apps that use Tailwind add `@source \"../node_modules/" + ctx.name + "\";` to their stylesheet so the classes are generated."] : []),
618
+ ],
619
+ });
620
+ return files;
256
621
  }