@opentf/create-afw 0.4.0 → 0.5.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 +4 -2
- package/index.js +16 -5
- package/package.json +6 -6
- package/templates.js +43 -33
- package/versions.json +4 -4
package/README.md
CHANGED
|
@@ -16,13 +16,14 @@ dev server is shown. Nothing is started for you.
|
|
|
16
16
|
| Rendering | `app` | `spa` (in the browser), `ssr` (per request, hydrated), `ssg` (prerendered) |
|
|
17
17
|
| Server | `app`, unless `ssr` | API routes, middleware, loaders and server functions on Node: yes or no |
|
|
18
18
|
| Styling | `app`, `library` | CSS, or Tailwind CSS |
|
|
19
|
+
| Blog | `docs` | Posts with RSS and Atom feeds: yes or no (default) |
|
|
19
20
|
| Language | every project | TypeScript (default), JavaScript |
|
|
20
21
|
|
|
21
22
|
Or pass the choices:
|
|
22
23
|
|
|
23
24
|
```sh
|
|
24
25
|
npm create @opentf/afw@latest my-app -- --template app --render ssg --server --tailwind
|
|
25
|
-
npm create @opentf/afw@latest my-docs -- --template docs-js
|
|
26
|
+
npm create @opentf/afw@latest my-docs -- --template docs-js --blog
|
|
26
27
|
```
|
|
27
28
|
|
|
28
29
|
| Option | Values |
|
|
@@ -31,6 +32,7 @@ npm create @opentf/afw@latest my-docs -- --template docs-js
|
|
|
31
32
|
| `-r`, `--render` | `spa` (default), `ssr`, `ssg` — `app` only |
|
|
32
33
|
| `--server`, `--no-server` | Add a Node server, or not (default) — `app` only; `ssr` always has one |
|
|
33
34
|
| `-s`, `--styling` | `css` (default) or `tailwind`; `--tailwind` for short — `app` and `library` |
|
|
35
|
+
| `--blog`, `--no-blog` | Add a blog, or not (default) — `docs` only |
|
|
34
36
|
| `-l`, `--language` | `ts` (default) or `js` |
|
|
35
37
|
| `--overwrite` | Remove the files in a non-empty target directory first |
|
|
36
38
|
| `--no-install` | Skip installing dependencies |
|
|
@@ -39,7 +41,7 @@ npm create @opentf/afw@latest my-docs -- --template docs-js
|
|
|
39
41
|
| Template | What you get |
|
|
40
42
|
| --- | --- |
|
|
41
43
|
| `app` | File-based pages and a component test; with a server, an API route, middleware, a loader and server functions |
|
|
42
|
-
| `docs` | An [`@opentf/afw-docs`](https://afw.opentechf.org/packages/afw-docs) site: MDX docs
|
|
44
|
+
| `docs` | An [`@opentf/afw-docs`](https://afw.opentechf.org/packages/afw-docs) site: MDX docs, prerendered, with search, `sitemap.xml` and `llms.txt`; with `--blog`, a blog with RSS/Atom feeds |
|
|
43
45
|
| `library` | Components published as JSX source (`index.js` and `src/`), `@opentf/afw` as a peer dependency, a preview app and a test |
|
|
44
46
|
|
|
45
47
|
The names of earlier releases still work: `spa`, `fullstack` (`app --server`), `ssr`
|
package/index.js
CHANGED
|
@@ -35,6 +35,8 @@ Options:
|
|
|
35
35
|
--server app: add ${SERVER_HINT}
|
|
36
36
|
--no-server app: no server (not with --render ssr, which always has one)
|
|
37
37
|
-s, --styling <name> app and library: ${Object.keys(STYLINGS).join(", ")} (--tailwind for short)
|
|
38
|
+
--blog docs: add a blog, with RSS and Atom feeds
|
|
39
|
+
--no-blog docs: no blog (the default)
|
|
38
40
|
-l, --language <lang> ts or js
|
|
39
41
|
--overwrite Remove the files in a non-empty target directory first
|
|
40
42
|
--no-install Skip installing dependencies
|
|
@@ -54,7 +56,7 @@ For the esdev + ES-Runtime workflow, use \`esdev create\`.`;
|
|
|
54
56
|
/** Parse the command line. Throws on an unknown option or value, or conflicting ones. */
|
|
55
57
|
export function parseArgs(args) {
|
|
56
58
|
const options = {
|
|
57
|
-
directory: undefined, template: undefined, render: undefined, server: undefined, styling: undefined,
|
|
59
|
+
directory: undefined, template: undefined, render: undefined, server: undefined, styling: undefined, blog: undefined,
|
|
58
60
|
language: undefined, overwrite: false, install: true, interactive: undefined, help: false,
|
|
59
61
|
};
|
|
60
62
|
const value = (i, flag) => {
|
|
@@ -72,6 +74,8 @@ export function parseArgs(args) {
|
|
|
72
74
|
else if (flag === "--no-server") options.server = false;
|
|
73
75
|
else if (flag === "-s" || flag === "--styling") options.styling = inline ?? value(i++, flag);
|
|
74
76
|
else if (flag === "--tailwind") options.styling = "tailwind";
|
|
77
|
+
else if (flag === "--blog") options.blog = true;
|
|
78
|
+
else if (flag === "--no-blog") options.blog = false;
|
|
75
79
|
else if (flag === "-l" || flag === "--language") options.language = inline ?? value(i++, flag);
|
|
76
80
|
else if (flag === "--ts" || flag === "--typescript") options.language = "ts";
|
|
77
81
|
else if (flag === "--js") options.language = "js";
|
|
@@ -118,6 +122,9 @@ export function parseArgs(args) {
|
|
|
118
122
|
if (options.render !== undefined) throw new Error(`--render applies to the app template, not ${options.template}`);
|
|
119
123
|
if (options.server !== undefined) throw new Error(`--server applies to the app template, not ${options.template}`);
|
|
120
124
|
}
|
|
125
|
+
if (options.template && options.template !== "docs" && options.blog !== undefined) {
|
|
126
|
+
throw new Error(`--${options.blog ? "" : "no-"}blog applies to the docs template, not ${options.template}`);
|
|
127
|
+
}
|
|
121
128
|
if (options.template === "docs" && options.styling !== undefined) {
|
|
122
129
|
throw new Error("--styling applies to the app and library templates; the docs template uses the afw-docs theme");
|
|
123
130
|
}
|
|
@@ -155,7 +162,7 @@ async function emptyDir(dir) {
|
|
|
155
162
|
* (default), `"remove"` its files first, or `"ignore"` and write beside them.
|
|
156
163
|
*/
|
|
157
164
|
export async function create({
|
|
158
|
-
directory = DEFAULT_DIRECTORY, template = "app", render = "spa", server = false, styling = "css", language = "ts",
|
|
165
|
+
directory = DEFAULT_DIRECTORY, template = "app", render = "spa", server = false, blog = false, styling = "css", language = "ts",
|
|
159
166
|
packageName, existing = "error", cwd: base = cwd(),
|
|
160
167
|
} = {}) {
|
|
161
168
|
const target = resolve(base, directory);
|
|
@@ -165,7 +172,7 @@ export async function create({
|
|
|
165
172
|
if (existing === "remove") await emptyDir(target);
|
|
166
173
|
else if (existing !== "ignore") throw new Error(`${target} is not empty. Use --overwrite to remove its files.`);
|
|
167
174
|
}
|
|
168
|
-
const files = projectFiles({ name, template, render, server, styling, typescript: language === "ts", versions: await afwVersions() });
|
|
175
|
+
const files = projectFiles({ name, template, render, server, blog, styling, typescript: language === "ts", versions: await afwVersions() });
|
|
169
176
|
for (const [path, contents] of Object.entries(files)) {
|
|
170
177
|
const file = join(target, path);
|
|
171
178
|
await mkdir(dirname(file), { recursive: true });
|
|
@@ -277,6 +284,10 @@ export async function main(args = argv.slice(2)) {
|
|
|
277
284
|
const server = isApp && (render === "ssr" || (options.server ?? (interactive
|
|
278
285
|
? await ask(prompts.confirm({ message: `Add a server? (${SERVER_HINT})`, initialValue: false }))
|
|
279
286
|
: false)));
|
|
287
|
+
// A docs site has no blog unless asked for one.
|
|
288
|
+
const blog = template === "docs" && (options.blog ?? (interactive
|
|
289
|
+
? await ask(prompts.confirm({ message: "Add a blog? (posts with RSS and Atom feeds)", initialValue: false }))
|
|
290
|
+
: false));
|
|
280
291
|
const styling = template === "docs" ? undefined : (options.styling ?? (interactive
|
|
281
292
|
? await ask(prompts.select({ message: "Select a styling:", options: Object.entries(STYLINGS).map(([value, label]) => ({ value, label })) }))
|
|
282
293
|
: "css"));
|
|
@@ -288,10 +299,10 @@ export async function main(args = argv.slice(2)) {
|
|
|
288
299
|
: "ts");
|
|
289
300
|
|
|
290
301
|
const where = relative(cwd(), target) || ".";
|
|
291
|
-
const summary = [isApp && render, server && "server", styling && STYLINGS[styling], LANGUAGES[language]].filter(Boolean).join(", ");
|
|
302
|
+
const summary = [isApp && render, server && "server", blog && "blog", styling && STYLINGS[styling], LANGUAGES[language]].filter(Boolean).join(", ");
|
|
292
303
|
prompts.log.step(`Scaffolding ${template} (${summary}) in ${styleText("cyan", target)}`);
|
|
293
304
|
try {
|
|
294
|
-
await create({ directory: target, template, render, server, styling, language, packageName, existing });
|
|
305
|
+
await create({ directory: target, template, render, server, blog, styling, language, packageName, existing });
|
|
295
306
|
} catch (error) {
|
|
296
307
|
prompts.cancel(error.message);
|
|
297
308
|
exit(1);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@opentf/create-afw",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Create an AFW app on Vite and Node: npm create @opentf/afw.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -22,11 +22,11 @@
|
|
|
22
22
|
"node": ">=22"
|
|
23
23
|
},
|
|
24
24
|
"devDependencies": {
|
|
25
|
-
"@opentf/afw": "0.
|
|
26
|
-
"@opentf/afw-docs": "0.
|
|
27
|
-
"@opentf/afw-form": "1.
|
|
28
|
-
"@opentf/afw-test": "1.
|
|
29
|
-
"@opentf/vite-plugin-afw": "0.
|
|
25
|
+
"@opentf/afw": "0.37.0",
|
|
26
|
+
"@opentf/afw-docs": "0.35.0",
|
|
27
|
+
"@opentf/afw-form": "1.32.0",
|
|
28
|
+
"@opentf/afw-test": "1.32.0",
|
|
29
|
+
"@opentf/vite-plugin-afw": "0.5.0",
|
|
30
30
|
"@tailwindcss/vite": "4.3.3",
|
|
31
31
|
"happy-dom": "21.0.4",
|
|
32
32
|
"tailwindcss": "4.3.3",
|
package/templates.js
CHANGED
|
@@ -4,14 +4,15 @@
|
|
|
4
4
|
// Choices are independent where the framework allows it:
|
|
5
5
|
// app — rendering (spa / ssr / ssg) × server (API routes, middleware, loaders,
|
|
6
6
|
// server functions) × styling (css / tailwind). SSR always has a server.
|
|
7
|
-
// docs — an afw-docs site: MDX docs
|
|
7
|
+
// docs — an afw-docs site: MDX docs, prerendered, with search; a blog with feeds
|
|
8
|
+
// only when asked for.
|
|
8
9
|
// library — a package of components published as JSX source, with a dev preview.
|
|
9
10
|
|
|
10
11
|
import { escapeHTML } from "@opentf/std";
|
|
11
12
|
|
|
12
13
|
export const TEMPLATES = {
|
|
13
14
|
app: "An app: choose how pages render and whether it has a server",
|
|
14
|
-
docs: "A documentation site with
|
|
15
|
+
docs: "A documentation site with search, and optionally a blog (afw-docs)",
|
|
15
16
|
library: "A component library published as JSX source",
|
|
16
17
|
};
|
|
17
18
|
|
|
@@ -48,7 +49,7 @@ export const TOOL_VERSIONS = {
|
|
|
48
49
|
* @param {{ name: string, template: keyof TEMPLATES, render?: keyof RENDERINGS, server?: boolean,
|
|
49
50
|
* styling?: keyof STYLINGS, typescript: boolean, versions: Record<string, string> }} options
|
|
50
51
|
*/
|
|
51
|
-
export function projectFiles({ name, template, render = "spa", server = false, styling = "css", typescript, versions }) {
|
|
52
|
+
export function projectFiles({ name, template, render = "spa", server = false, blog = false, styling = "css", typescript, versions }) {
|
|
52
53
|
if (!TEMPLATES[template]) throw new Error(`Unknown template "${template}". Choose one of: ${Object.keys(TEMPLATES).join(", ")}`);
|
|
53
54
|
if (!RENDERINGS[render]) throw new Error(`Unknown rendering "${render}". Choose one of: ${Object.keys(RENDERINGS).join(", ")}`);
|
|
54
55
|
if (!STYLINGS[styling]) throw new Error(`Unknown styling "${styling}". Choose one of: ${Object.keys(STYLINGS).join(", ")}`);
|
|
@@ -56,7 +57,7 @@ export function projectFiles({ name, template, render = "spa", server = false, s
|
|
|
56
57
|
name, versions, ts: typescript, js: typescript ? "ts" : "js", jsx: typescript ? "tsx" : "jsx",
|
|
57
58
|
tailwind: styling === "tailwind",
|
|
58
59
|
};
|
|
59
|
-
if (template === "docs") return docsFiles(ctx);
|
|
60
|
+
if (template === "docs") return docsFiles({ ...ctx, blog });
|
|
60
61
|
if (template === "library") return libraryFiles(ctx);
|
|
61
62
|
return appFiles({ ...ctx, render, server: render === "ssr" || server });
|
|
62
63
|
}
|
|
@@ -393,7 +394,7 @@ export default function Todos() {
|
|
|
393
394
|
// ---------------------------------------------------------------------------- docs
|
|
394
395
|
|
|
395
396
|
function docsFiles(ctx) {
|
|
396
|
-
const { ts, js, jsx } = ctx;
|
|
397
|
+
const { ts, js, jsx, blog } = ctx;
|
|
397
398
|
const files = {};
|
|
398
399
|
files["package.json"] = json({
|
|
399
400
|
name: ctx.name, private: true, type: "module", scripts: scripts(ctx, { server: false }),
|
|
@@ -408,17 +409,17 @@ function docsFiles(ctx) {
|
|
|
408
409
|
files["afw.config.js"] = `import { defineDocsConfig } from "@opentf/afw-docs/config";
|
|
409
410
|
|
|
410
411
|
export default defineDocsConfig({
|
|
411
|
-
// Your site's URL: canonical links, sitemap.xml, feeds and llms.txt use it.
|
|
412
|
+
// Your site's URL: canonical links, sitemap.xml${blog ? ", feeds" : ""} and llms.txt use it.
|
|
412
413
|
site: { url: "https://example.com" },
|
|
413
414
|
docs: {
|
|
414
415
|
title: "${escapeJs(ctx.name)}",
|
|
415
416
|
nav: [
|
|
416
|
-
{ label: "Docs", href: "/docs" }
|
|
417
|
-
{ label: "Blog", href: "/blog" }
|
|
417
|
+
{ label: "Docs", href: "/docs" },${blog ? `
|
|
418
|
+
{ label: "Blog", href: "/blog" },` : ""}
|
|
418
419
|
],
|
|
419
420
|
search: { provider: "afw" },
|
|
420
|
-
}
|
|
421
|
-
blog: { dir: "blog", title: "${escapeJs(ctx.name)} Blog" }
|
|
421
|
+
},${blog ? `
|
|
422
|
+
blog: { dir: "blog", title: "${escapeJs(ctx.name)} Blog" },` : ""}
|
|
422
423
|
});
|
|
423
424
|
`;
|
|
424
425
|
files["index.html"] = indexHtml(ctx, { title: ctx.name, css: false });
|
|
@@ -431,15 +432,15 @@ export default defineDocsConfig({
|
|
|
431
432
|
`;
|
|
432
433
|
files[`app/page.${jsx}`] = `import { Link } from "@opentf/afw";
|
|
433
434
|
|
|
434
|
-
export const metadata = { title: "${escapeJs(ctx.name)}", description: "Documentation and blog." };
|
|
435
|
+
export const metadata = { title: "${escapeJs(ctx.name)}", description: "${blog ? "Documentation and blog." : "Documentation."}" };
|
|
435
436
|
|
|
436
437
|
export default function Home() {
|
|
437
438
|
return (
|
|
438
439
|
<main class="afwd-prose">
|
|
439
440
|
<h1>${escapeHTML(ctx.name)}</h1>
|
|
440
|
-
<p
|
|
441
|
+
<p>${blog ? "Documentation and a blog" : "Documentation"}, written in MDX.</p>
|
|
441
442
|
<p>
|
|
442
|
-
<Link href="/docs">Read the docs</Link
|
|
443
|
+
<Link href="/docs">Read the docs</Link>${blog ? ` · <Link href="/blog">Visit the blog</Link>` : ""}
|
|
443
444
|
</p>
|
|
444
445
|
</main>
|
|
445
446
|
);
|
|
@@ -506,6 +507,35 @@ Markdown with components, like this list of steps.
|
|
|
506
507
|
|
|
507
508
|
</Steps>
|
|
508
509
|
`;
|
|
510
|
+
if (blog) Object.assign(files, blogFiles(ctx));
|
|
511
|
+
files[`tests/Home.test.${js}`] = `import { expect, test } from "vitest";
|
|
512
|
+
import { render } from "@opentf/afw-test";
|
|
513
|
+
import Home from "../app/page.${jsx}";
|
|
514
|
+
|
|
515
|
+
test("the home page links to the docs${blog ? " and the blog" : ""}", () => {
|
|
516
|
+
const { getByRole } = render(Home);
|
|
517
|
+
expect(getByRole("heading", { level: 1 }).textContent).toBe("${escapeJs(ctx.name)}");
|
|
518
|
+
expect(getByRole("link", { name: "Read the docs" }).getAttribute("href")).toBe("/docs");${blog ? `
|
|
519
|
+
expect(getByRole("link", { name: "Visit the blog" }).getAttribute("href")).toBe("/blog");` : ""}
|
|
520
|
+
});
|
|
521
|
+
`;
|
|
522
|
+
files[".gitignore"] = "node_modules\ndist\n";
|
|
523
|
+
files["README.md"] = readme(ctx, {
|
|
524
|
+
summary: `A documentation site${blog ? " and blog" : ""} built with [AFW](https://afw.opentechf.org) and \`@opentf/afw-docs\` on Vite.`,
|
|
525
|
+
commands: commandRows(ctx, { server: false }),
|
|
526
|
+
notes: [
|
|
527
|
+
`Docs pages live in \`app/docs/\`${blog ? ", posts in \`app/blog/\`" : ""}; \`app/docs/_meta.js\` orders the sidebar.`,
|
|
528
|
+
`\`npm run build\` prerenders every page and writes the search index, \`sitemap.xml\`${blog ? ", RSS and Atom feeds" : ""} and \`llms.txt\`.`,
|
|
529
|
+
"Set your site's URL in `afw.config.js`.",
|
|
530
|
+
],
|
|
531
|
+
});
|
|
532
|
+
return files;
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
/** The blog of a docs site: its layout, the post list and a first post. */
|
|
536
|
+
function blogFiles(ctx) {
|
|
537
|
+
const { ts, jsx } = ctx;
|
|
538
|
+
const files = {};
|
|
509
539
|
files[`app/blog/layout.${jsx}`] = `import { BlogLayout } from "@opentf/afw-docs";
|
|
510
540
|
import { posts } from "@opentf/afw-docs/posts";
|
|
511
541
|
import config from "../../afw.config.js";
|
|
@@ -539,26 +569,6 @@ author: ${escapeHTML(ctx.name)}
|
|
|
539
569
|
|
|
540
570
|
Posts live in \`app/blog/\`; each one appears in the post list and the RSS and Atom feeds.
|
|
541
571
|
`;
|
|
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
572
|
return files;
|
|
563
573
|
}
|
|
564
574
|
|
package/versions.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"@opentf/afw": "^0.
|
|
3
|
-
"@opentf/afw-docs": "^0.
|
|
4
|
-
"@opentf/afw-test": "^1.
|
|
5
|
-
"@opentf/vite-plugin-afw": "^0.
|
|
2
|
+
"@opentf/afw": "^0.37.0",
|
|
3
|
+
"@opentf/afw-docs": "^0.35.0",
|
|
4
|
+
"@opentf/afw-test": "^1.32.0",
|
|
5
|
+
"@opentf/vite-plugin-afw": "^0.5.0"
|
|
6
6
|
}
|