@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/LICENSE +21 -0
- package/README.md +37 -13
- package/index.js +274 -80
- package/package.json +11 -4
- package/templates.js +483 -118
- package/versions.js +51 -13
- package/versions.json +6 -0
package/templates.js
CHANGED
|
@@ -1,11 +1,34 @@
|
|
|
1
|
-
// The Vite + Node project templates. Each
|
|
2
|
-
//
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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,
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
const
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
"@opentf/
|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
},
|
|
83
|
-
|
|
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
|
-
|
|
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>${
|
|
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
|
-
|
|
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
|
-
|
|
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>${
|
|
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
|
-
|
|
178
|
-
|
|
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
|
-
|
|
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
|
-
|
|
192
|
-
|
|
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
|
-
|
|
195
|
-
|
|
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
|
-
|
|
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
|
-
{
|
|
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
|
-
|
|
216
|
-
import { render, userEvent } from "@opentf/afw-test";
|
|
217
|
-
import Counter from "../app/Counter.${jsx}";
|
|
393
|
+
// ---------------------------------------------------------------------------- docs
|
|
218
394
|
|
|
219
|
-
|
|
220
|
-
const {
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
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
|
-
|
|
434
|
+
export const metadata = { title: "${escapeJs(ctx.name)}", description: "Documentation and blog." };
|
|
228
435
|
|
|
229
|
-
|
|
230
|
-
|
|
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
|
-
|
|
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
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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
|
-
|
|
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
|
-
|
|
247
|
-
|
|
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
|
-
|
|
251
|
-
|
|
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
|
-
|
|
255
|
-
|
|
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
|
}
|