@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 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 and a blog, prerendered, with search, RSS/Atom feeds, `sitemap.xml` and `llms.txt` |
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.4.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.36.0",
26
- "@opentf/afw-docs": "0.34.0",
27
- "@opentf/afw-form": "1.31.0",
28
- "@opentf/afw-test": "1.31.0",
29
- "@opentf/vite-plugin-afw": "0.4.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 and a blog, prerendered, with search and feeds.
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 a blog, search and feeds (afw-docs)",
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>Documentation and a blog, written in MDX.</p>
441
+ <p>${blog ? "Documentation and a blog" : "Documentation"}, written in MDX.</p>
441
442
  <p>
442
- <Link href="/docs">Read the docs</Link> · <Link href="/blog">Visit the blog</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.36.0",
3
- "@opentf/afw-docs": "^0.34.0",
4
- "@opentf/afw-test": "^1.31.0",
5
- "@opentf/vite-plugin-afw": "^0.4.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
  }