@monospaced/create-set 0.20.2 → 0.22.0

package/README.md

@@ -6,17 +6,28 @@ Project scaffolding for Set. Bootstraps a site or app with Set's components, too
 pnpm create @monospaced/set my-site
 ```
 
-Prompts for a package name, site title and description, each showing its default, which Enter accepts. Each has a flag (`--name`, `--title`, `--description`), and `--defaults` takes every default without prompting, so it runs non-interactively too; without a terminal, anything unanswered is refused rather than guessed. Refuses a directory that isn't empty.
+Prompts for a package name, site title, description and variant (`html`, `prerender` or `react`), each showing its default, which Enter accepts. Each has a flag (`--name`, `--title`, `--description`, `--variant`), and `--defaults` takes every default without prompting, so it runs non-interactively too; without a terminal, anything unanswered is refused rather than guessed. Refuses a directory that isn't empty.
+
+## Variants
+
+Three ways to author, sharing everything else.
+
+- **`html`** (default): pages are HTML you write against Set's CSS variables and custom elements. The simplest possible Set site; the file you write is the file that ships.
+- **`prerender`**: pages are render functions in `src/pages`, prerendered to static HTML at build time by a small Vite plugin and hydrated by `defineSetComponents()`. One shared head in `src/document.ts`, per-page title and description, and nothing of the renderer ships to the browser.
+- **`react`**: an app rendered on the client from `@monospaced/set-react` components, with `@vitejs/plugin-react`, the React ESLint preset, and jsdom for component tests. `Root` takes its initial theme from the stored lightswitch choice.
+
+In `html` and `prerender`, a page is a folder with an `index.html` and its path is its URL; Vite discovers them, so adding a page is adding a folder.
 
 ## What you get
 
 A Vite and TypeScript project with a starter page built from Set components, a `src/styles.css` for your own styles, Set's ESLint and Stylelint presets, Prettier, Husky and lint-staged, VS Code settings, and Lightning CSS targets from Set's Baseline query.
 
-- Dependencies install live, so nothing in the template goes stale. Tools the config package declares as peers install at its declared ranges, so preset and tool agree.
+- Every version has an owner. Set packages install at latest; tools the config package declares as peers install at its declared ranges; the rest of the tooling installs at the monorepo's own ranges, so a scaffold gets the versions Set develops and tests with.
 - `scripts/sync-set.mjs` copies the token catalog, agent skills and favicons into place on every install.
 - Git is initialised first, with an initial commit at the end.
+- A GitHub Actions workflow runs the project's checks on every pull request, and Dependabot proposes grouped updates weekly with a three-day cooldown.
 
-The Node and pnpm versions written to `engines`, `packageManager` and `.node-version` are generated into `src/toolchain.mjs` from the monorepo's toolchain by `pnpm create:sync`; `pnpm create:verify` fails CI when they drift.
+The Node and pnpm versions written to `engines`, `packageManager` and `.node-version`, and the tooling ranges, are generated into `src/toolchain.mjs` from the monorepo's toolchain and pnpm catalog by `pnpm create:sync`; `pnpm create:verify` fails CI when they drift.
 
 ## Developing
 
@@ -27,11 +38,11 @@ pnpm create:test
 pnpm create:dev ../scratch/my-site
 ```
 
-`create:dev` builds core first and runs the CLI from source. The generated project installs the published Set packages, which is what a user gets. To scaffold against the workspace instead, pack the Set packages and point the CLI at them:
+`create:dev` builds core first and runs the CLI from source. The `scaffold` workflow (`.github/workflows/scaffold.yml`) does the end-to-end run in CI: both variants, against this checkout's packed packages on pull requests and pushes, and against the registry on demand. The generated project installs the published Set packages, which is what a user gets. To scaffold against the workspace instead, pack the Set packages and point the CLI at them:
 
 ```sh
-pnpm --filter "@monospaced/set-{assets,config,core,skills,tokens}" pack --pack-destination ../scratch/pack
+pnpm --filter @monospaced/set-assets --filter @monospaced/set-config --filter @monospaced/set-core --filter @monospaced/set-icons --filter @monospaced/set-react --filter @monospaced/set-skills --filter @monospaced/set-tokens pack --pack-destination ../scratch/pack
 CREATE_SET_PACK_DIR=../scratch/pack pnpm create:dev ../scratch/my-site
 ```
 
-`plan()` in `src/plan.mjs` is pure and returns every file for a set of answers; the tests snapshot it. `execute()` does the I/O: git, files, `pnpm add`, the sync script, the commit.
+`plan()` in `src/plan.mjs` is pure and returns every file for a set of answers; the tests snapshot both variants, and one test executes the generated prerender modules to check they render the same document as the `html` starter. `execute()` does the I/O: git, files, `pnpm add`, the sync script, the commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monospaced/create-set",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "description": "Project scaffolding for Set. Bootstraps a site or app with Set's components, tooling and defaults.",
   "repository": {
     "type": "git",
@@ -18,9 +18,10 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@monospaced/set-core": "0.20.2"
+    "@monospaced/set-core": "0.22.0"
   },
   "devDependencies": {
+    "prettier": "^3.8.3",
     "vitest": "^4.1.6"
   },
   "scripts": {

package/src/cli.mjs

@@ -9,6 +9,7 @@ import {
   toTitle,
   validatePackageName,
 } from "./answers.mjs";
+import { VARIANTS } from "./constants.mjs";
 import { execute, isEmptyDirectory } from "./execute.mjs";
 
 const { version } = createRequire(import.meta.url)("../package.json");
@@ -22,6 +23,9 @@ Options:
   --name <name>         Package name (default: the directory name)
   --title <title>       Site title (default: from the package name)
   --description <text>  Site description (default: "<title>, built with Set.")
+  --variant <variant>   html: pages are HTML you write (default)
+                        prerender: pages are render functions, built to HTML
+                        react: an app rendered by React
   --defaults            Take every default without prompting
   -h, --help            Show this help
   -v, --version         Show the version
@@ -33,9 +37,20 @@ const OPTIONS = {
   help: { short: "h", type: "boolean" },
   name: { type: "string" },
   title: { type: "string" },
+  variant: { type: "string" },
   version: { short: "v", type: "boolean" },
 };
 
+const VARIANT_OPTIONS = [
+  { hint: "pages are HTML you write", label: "HTML", value: "html" },
+  {
+    hint: "pages are render functions, built to HTML",
+    label: "Prerender",
+    value: "prerender",
+  },
+  { hint: "an app rendered by React", label: "React", value: "react" },
+];
+
 /** Prompts, or returns `undefined` when the user cancels. */
 async function prompt(promise) {
   const value = await promise;
@@ -44,9 +59,10 @@ async function prompt(promise) {
 
 /**
  * Answers a question from its flag, its default (with `--defaults`), or a
- * prompt whose hint is the default.
+ * prompt: a text field whose hint is the default, or a select when `options`
+ * are given.
  */
-async function answer(values, key, fallback, { missing, ...options }) {
+async function answer(values, key, fallback, { missing, options, ...rest }) {
   if (values[key] !== undefined) return values[key];
   if (values.defaults) return fallback;
   if (!process.stdin.isTTY) {
@@ -56,7 +72,9 @@ async function answer(values, key, fallback, { missing, ...options }) {
   }
 
   return prompt(
-    p.text({ defaultValue: fallback, placeholder: fallback, ...options }),
+    options
+      ? p.select({ initialValue: fallback, options, ...rest })
+      : p.text({ defaultValue: fallback, placeholder: fallback, ...rest }),
   );
 }
 
@@ -100,7 +118,18 @@ async function ask(values, positional) {
   );
   if (description === undefined) return;
 
-  return { description, dir, name, title };
+  const variant = await answer(values, "variant", VARIANTS[0], {
+    message: "How are pages authored?",
+    options: VARIANT_OPTIONS,
+  });
+  if (variant === undefined) return;
+
+  if (!VARIANTS.includes(variant)) {
+    p.cancel(`${variant} is not a variant. Use ${VARIANTS.join(" or ")}.`);
+    return;
+  }
+
+  return { description, dir, name, title, variant };
 }
 
 export async function run(argv) {
@@ -146,17 +175,13 @@ export async function run(argv) {
     return;
   }
 
-  const spinner = p.spinner();
-  spinner.start("Creating project");
-
   try {
-    const root = execute(answers, {
-      step: (message) => spinner.message(message),
+    const root = await execute(answers, {
+      step: (message) => p.log.step(message),
       warn: (message) => p.log.warn(message),
     });
-    spinner.stop(`Created ${root}`);
+    p.log.success(`Created ${root}`);
   } catch (error) {
-    spinner.stop("Failed", 1);
     p.log.error(error.message);
     process.exitCode = 1;
     return;

package/src/constants.mjs

@@ -2,19 +2,24 @@
 export const OG_IMAGE =
   "https://res.cloudinary.com/monospaced/image/upload/v1789307953/2018-04-20_15.28.26--cyan--og--mid.png";
 
+/** How pages are authored. The first is the default. */
+export const VARIANTS = ["html", "prerender", "react"];
+
 /** Installed live at generation time, so nothing in the template goes stale. */
 export const RUNTIME_DEPENDENCIES = [
   "@monospaced/set-assets",
   "@monospaced/set-core",
 ];
 
-export const DEV_DEPENDENCIES = [
+/** The React variant's extra Set package. */
+export const REACT_RUNTIME_DEPENDENCIES = ["@monospaced/set-react"];
+
+/**
+ * Set's own dev packages, at latest like the runtime ones. The rest of the
+ * tooling installs at the monorepo's ranges, from `toolchain.mjs`.
+ */
+export const SET_DEV_DEPENDENCIES = [
   "@monospaced/set-config",
   "@monospaced/set-skills",
   "@monospaced/set-tokens",
-  "husky",
-  "lint-staged",
-  "prettier",
-  "vite",
-  "vitest",
 ];

package/src/execute.mjs

@@ -1,9 +1,20 @@
-import { spawnSync } from "node:child_process";
-import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import {
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
-import { DEV_DEPENDENCIES, RUNTIME_DEPENDENCIES } from "./constants.mjs";
+import {
+  REACT_RUNTIME_DEPENDENCIES,
+  RUNTIME_DEPENDENCIES,
+  SET_DEV_DEPENDENCIES,
+} from "./constants.mjs";
 import { plan } from "./plan.mjs";
+import { REACT, TOOLING } from "./toolchain.mjs";
 
 /** True when `dir` does not exist or holds nothing. */
 export function isEmptyDirectory(dir) {
@@ -15,21 +26,29 @@ export function isEmptyDirectory(dir) {
   }
 }
 
+/** Runs a command to completion, off the event loop so Ctrl-C still works. */
 function run(command, args, cwd) {
-  const result = spawnSync(command, args, {
-    cwd,
-    encoding: "utf8",
-    shell: process.platform === "win32",
-    stdio: "pipe",
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      shell: process.platform === "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let output = "";
+    child.stdout.on("data", (chunk) => (output += chunk));
+    child.stderr.on("data", (chunk) => (output += chunk));
+    child.on("error", reject);
+    child.on("close", (status) => {
+      if (status === 0) resolve(output);
+      else {
+        reject(
+          new Error(
+            `\`${command} ${args.join(" ")}\` failed:\n${output.trim()}`,
+          ),
+        );
+      }
+    });
   });
-
-  if (result.error) throw result.error;
-  if (result.status !== 0) {
-    const output = `${result.stdout}\n${result.stderr}`.trim();
-    throw new Error(`\`${command} ${args.join(" ")}\` failed:\n${output}`);
-  }
-
-  return result.stdout;
 }
 
 const pnpm = (args, cwd) => run("pnpm", args, cwd);
@@ -39,19 +58,46 @@ const pnpm = (args, cwd) => run("pnpm", args, cwd);
  * `pnpm pack` tarballs in that directory instead of the registry, so the CLI
  * can be exercised against unreleased packages. Users always get the registry.
  */
-function setSpec(name) {
-  const packDir = process.env.CREATE_SET_PACK_DIR;
-  if (!packDir || !name.startsWith("@monospaced/")) return name;
-
-  const stem = `${name.slice(1).replace("/", "-")}-`;
-  const tarball = readdirSync(packDir).find(
-    (file) => file.startsWith(stem) && file.endsWith(".tgz"),
+const packDir = process.env.CREATE_SET_PACK_DIR;
+
+/** Packed Set packages, by name, from the tarball filenames. */
+function packed() {
+  if (!packDir) return {};
+
+  return Object.fromEntries(
+    readdirSync(packDir)
+      .filter((file) => file.endsWith(".tgz"))
+      .map((file) => [
+        `@${file.replace(/-\d+\.\d+\.\d+.*\.tgz$/, "").replace("-", "/")}`,
+        resolve(packDir, file),
+      ]),
   );
+}
 
-  return tarball ? resolve(packDir, tarball) : name;
+function setSpec(name) {
+  return packed()[name] ?? name;
+}
+
+/**
+ * The packed packages also as pnpm overrides, so a packed core resolves the
+ * packed icons it depends on rather than a registry version that may not be
+ * published yet. Appended to the generated workspace file in harness mode.
+ */
+function packOverrides() {
+  const entries = Object.entries(packed());
+  if (entries.length === 0) return "";
+
+  return `
+# Dev harness: Set packages from CREATE_SET_PACK_DIR, transitively too.
+overrides:
+${entries.map(([name, tarball]) => `  "${name}": "file:${tarball}"`).join("\n")}
+`;
 }
 const git = (args, cwd) => run("git", args, cwd);
 
+const specs = (dependencies) =>
+  Object.entries(dependencies).map(([name, range]) => `${name}@${range}`);
+
 /**
  * The tools the config package drives, as `name@range` specs. Its presets
  * declare them as peers, so they install at the range it supports rather
@@ -65,9 +111,7 @@ function configPeerSpecs(root) {
     ),
   );
 
-  return Object.entries(manifest.peerDependencies).map(
-    ([name, range]) => `${name}@${range}`,
-  );
+  return specs(manifest.peerDependencies);
 }
 
 /**
@@ -77,13 +121,14 @@ function configPeerSpecs(root) {
  * @param {{ dir: string } & import("./plan.mjs").Answers} answers
  * @param {{ step(message: string): void, warn(message: string): void }} report
  */
-export function execute({ dir, ...answers }, report) {
+export async function execute({ dir, ...answers }, report) {
   const root = resolve(dir);
   const files = plan(answers);
+  const react = answers.variant === "react";
 
   report.step("Initialising git");
   mkdirSync(root, { recursive: true });
-  git(["init", "--initial-branch=main"], root);
+  await git(["init", "--initial-branch=main"], root);
 
   report.step("Writing files");
   for (const [path, content] of Object.entries(files)) {
@@ -91,32 +136,49 @@ export function execute({ dir, ...answers }, report) {
     mkdirSync(dirname(target), { recursive: true });
     writeFileSync(target, content);
   }
+  appendFileSync(join(root, "pnpm-workspace.yaml"), packOverrides());
 
   // Lifecycle scripts wait until everything `prepare` needs is installed.
   report.step("Installing Set");
-  pnpm(["add", "--ignore-scripts", ...RUNTIME_DEPENDENCIES.map(setSpec)], root);
+  await pnpm(
+    [
+      "add",
+      "--ignore-scripts",
+      ...RUNTIME_DEPENDENCIES.map(setSpec),
+      ...(react ? REACT_RUNTIME_DEPENDENCIES.map(setSpec) : []),
+      ...(react ? specs(REACT.dependencies) : []),
+    ],
+    root,
+  );
 
   report.step("Installing tooling");
-  pnpm(
-    ["add", "--ignore-scripts", "--save-dev", ...DEV_DEPENDENCIES.map(setSpec)],
+  await pnpm(
+    [
+      "add",
+      "--ignore-scripts",
+      "--save-dev",
+      ...SET_DEV_DEPENDENCIES.map(setSpec),
+      ...specs(TOOLING),
+      ...(react ? specs(REACT.devDependencies) : []),
+    ],
     root,
   );
-  pnpm(
+  await pnpm(
     ["add", "--ignore-scripts", "--save-dev", ...configPeerSpecs(root)],
     root,
   );
 
   // Explicit: `pnpm install` skips lifecycle scripts when nothing changed.
   report.step("Syncing Set artifacts and git hooks");
-  pnpm(["run", "prepare"], root);
+  await pnpm(["run", "prepare"], root);
 
   report.step("Formatting");
-  pnpm(["exec", "prettier", "--write", "."], root);
+  await pnpm(["exec", "prettier", "--write", "."], root);
 
   report.step("Committing");
-  git(["add", "--all"], root);
+  await git(["add", "--all"], root);
   try {
-    git(
+    await git(
       ["commit", "--message", "chore: bootstrap with @monospaced/create-set"],
       root,
     );

package/src/page.mjs

@@ -1,7 +1,6 @@
 import {
   renderSetBox,
   renderSetContainer,
-  renderSetDivider,
   renderSetHeading,
   renderSetInline,
   renderSetLightswitch,
@@ -26,19 +25,18 @@ export const escapeHtml = (value) =>
  * root's first child: earlier and the root doesn't exist yet, later and
  * content above it may already have painted in the wrong theme.
  */
-const themeBootstrap = `<script>try{var t=localStorage.getItem(${JSON.stringify(
+export const themeBootstrap = `<script>try{var t=localStorage.getItem(${JSON.stringify(
   SET_LIGHTSWITCH_STORAGE_KEY,
 )});if(t==="light"||t==="dark")document.currentScript.closest(".set").setAttribute("data-set-theme",t)}catch(e){}</script>`;
 
 /**
- * The hello-world page: Root → Page with a header, a heading, a paragraph and
- * a Lightswitch, built from Set components only. Rendered with core at
- * generation time, so the markup is always what the installed core expects.
+ * The starter page, built from Set components only and rendered with core at
+ * generation time. The `prerender` variant writes the same composition as
+ * `src/document.ts` and `src/pages/index.ts`.
  */
-export function renderHelloPage({ title }) {
-  const safeTitle = escapeHtml(title);
-
+export function renderHelloPage({ editHint, title }) {
   const header = renderSetContainer({
+    maxInlineSize: "none",
     children: renderSetBox({
       background: "transparent",
       paddingBlock: "2xs",
@@ -47,7 +45,7 @@ export function renderHelloPage({ title }) {
         gap: "sm",
         justify: "between",
         children:
-          renderSetHeading({ children: safeTitle, size: "md" }) +
+          renderSetHeading({ children: escapeHtml(title), size: "md" }) +
           renderSetLightswitch({ size: "sm" }),
       }),
     }),
@@ -69,31 +67,18 @@ export function renderHelloPage({ title }) {
           }) +
           renderSetText({
             as: "p",
-            children: `${safeTitle} is built with <a href="https://set.monospaced.com">Set</a>. Edit <code>index.html</code> to begin.`,
+            children: `Edit <code>${editHint}</code> to begin.`,
             responsive: true,
+            size: "sm",
           }),
       }),
     }),
   });
 
-  const footer =
-    renderSetDivider({ tone: "subtle" }) +
-    renderSetContainer({
-      children: renderSetBox({
-        paddingBlock: "xs",
-        paddingInline: "none",
-        children: renderSetText({
-          as: "p",
-          children: "Built with Set.",
-          size: "sm",
-          tone: "muted",
-        }),
-      }),
-    });
-
+  // Page always renders its footer region; the starter leaves it empty.
   const page = renderSetPage({
     children: main,
-    footer,
+    footer: "",
     header,
     headerBorder: "always",
     headerSize: "sm",

package/src/plan.mjs

@@ -6,6 +6,7 @@ import { NODE_MAJOR, PNPM_VERSION } from "./toolchain.mjs";
  * @property {string} name Package name.
  * @property {string} title Site title.
  * @property {string} description Site description.
+ * @property {"html" | "prerender"} variant How pages are authored.
  */
 
 /**
@@ -23,8 +24,10 @@ export function plan(answers) {
     pnpmVersion: PNPM_VERSION,
   };
 
-  return {
+  const shared = {
     ".editorconfig": templates.editorconfig(),
+    ".github/dependabot.yml": templates.dependabotYml(),
+    ".github/workflows/ci.yml": templates.ciYml(),
     ".gitignore": templates.gitignore(),
     ".husky/pre-commit": "pnpm exec lint-staged\n",
     ".node-version": `${NODE_MAJOR}\n`,
@@ -33,15 +36,40 @@ export function plan(answers) {
     ".vscode/extensions.json": templates.vscodeExtensions(),
     ".vscode/settings.json": templates.vscodeSettings(),
     "README.md": templates.readme(context),
-    "eslint.config.mjs": templates.eslintConfig(),
-    "index.html": templates.indexHtml(context),
+    "eslint.config.mjs": templates.eslintConfig(context),
     "package.json": templates.packageJson(context),
     "pnpm-workspace.yaml": templates.pnpmWorkspace(),
     "public/manifest.webmanifest": templates.manifest(context),
     "scripts/sync-set.mjs": templates.syncSet(),
-    "src/main.ts": templates.mainTs(),
     "src/styles.css": templates.stylesCss(),
-    "tsconfig.json": templates.tsconfig(),
-    "vite.config.ts": templates.viteConfig(),
+    "tsconfig.json": templates.tsconfig(context),
+    "vite.config.ts": templates.viteConfig(context),
   };
+
+  const variants = {
+    html: {
+      "index.html": templates.indexHtml(context),
+      "src/main.ts": templates.mainTs(),
+    },
+    prerender: {
+      "index.html": templates.routeStub(),
+      "src/document.ts": templates.documentTs(),
+      "src/main.ts": templates.mainTs(),
+      "src/pages.ts": templates.pagesTs(),
+      "src/pages/index.ts": templates.indexPageTs(),
+      "src/site.ts": templates.siteTs(context),
+    },
+    react: {
+      "index.html": templates.indexHtml(context),
+      "src/App.tsx": templates.appTsx(context),
+      "src/main.tsx": templates.mainTsx(),
+    },
+  };
+  const variant = variants[answers.variant];
+
+  return Object.fromEntries(
+    Object.entries({ ...shared, ...variant }).sort(([a], [b]) =>
+      a.localeCompare(b),
+    ),
+  );
 }

package/src/templates.mjs

@@ -1,5 +1,5 @@
 import { OG_IMAGE } from "./constants.mjs";
-import { escapeHtml, renderHelloPage } from "./page.mjs";
+import { escapeHtml, renderHelloPage, themeBootstrap } from "./page.mjs";
 
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
 
@@ -34,12 +34,12 @@ export const packageJson = ({ description, name, nodeMajor, pnpmVersion }) => {
     "lint-staged": {
       "*": "prettier --ignore-unknown --write",
       "*.css": "stylelint --fix",
-      "*.{js,mjs,ts}": "eslint --fix",
+      "*.{js,jsx,mjs,ts,tsx}": "eslint --fix",
     },
   });
 };
 
-export const indexHtml = ({ description, title }) => `<!doctype html>
+export const indexHtml = ({ description, title, variant }) => `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
@@ -67,8 +67,13 @@ export const indexHtml = ({ description, title }) => `<!doctype html>
     <link rel="manifest" href="/manifest.webmanifest" />
   </head>
   <body>
-    ${renderHelloPage({ title })}
-    <script type="module" src="/src/main.ts"></script>
+${
+  variant === "react"
+    ? `    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>`
+    : `    ${renderHelloPage({ editHint: "index.html", title })}
+    <script type="module" src="/src/main.ts"></script>`
+}
   </body>
 </html>
 `;
@@ -107,20 +112,315 @@ export const stylesCss =
    its own CSS, write it here with Set tokens. */
 `;
 
-export const viteConfig =
-  () => `import target from "@monospaced/set-config/browserslist/esbuild";
-import targets from "@monospaced/set-config/browserslist/lightningcss";
-import { defineConfig } from "vite";
+export const viteConfig = ({ variant }) => {
+  const prerender = variant === "prerender";
+  const react = variant === "react";
+
+  return `import { globSync } from "node:fs";
 
+import target from "@monospaced/set-config/browserslist/esbuild";
+import targets from "@monospaced/set-config/browserslist/lightningcss";
+${react ? 'import react from "@vitejs/plugin-react";\n' : ""}import { defineConfig${prerender ? ", type Plugin" : ""} } from "${react ? "vitest/config" : "vite"}";
+${
+  prerender
+    ? `
+import { renderDocument } from "./src/document.ts";
+import { pages } from "./src/pages.ts";
+`
+    : ""
+}
+// Every index.html is a page; its folder is its route.
+const input = globSync("**/index.html", {
+  exclude: ["dist/**", "node_modules/**"],
+});
+${
+  prerender
+    ? `
+// Renders each route's document from src/pages at dev and build time, so the
+// render functions never ship to the browser. The page modules are imported
+// above, so the dev server restarts when one changes.
+const prerender: Plugin = {
+  name: "set-prerender",
+  transformIndexHtml: {
+    order: "pre",
+    handler: (_html, { path }) => {
+      const route = path.replace(/index\\.html$/, "");
+      const page = pages[route];
+      if (!page) throw new Error(\`No page for \${route}. Add it to src/pages.ts.\`);
+      return renderDocument(page, route);
+    },
+  },
+};
+`
+    : ""
+}
 export default defineConfig({
-  build: { cssMinify: "lightningcss", target },
-  css: { lightningcss: { targets }, transformer: "lightningcss" },
+  build: { cssMinify: "lightningcss", rollupOptions: { input }, target },
+  css: { lightningcss: { targets }, transformer: "lightningcss" },${
+    prerender ? "\n  plugins: [prerender]," : ""
+  }${react ? '\n  plugins: [react()],\n  test: { environment: "jsdom" },' : ""}
 });
 `;
+};
+
+export const mainTsx = () => `import "@monospaced/set-assets/fonts.css";
+import "@monospaced/set-core/styles.css";
+import "./styles.css";
+
+import { SET_LIGHTSWITCH_STORAGE_KEY } from "@monospaced/set-core";
+import { defineSetAll } from "@monospaced/set-react";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { App } from "./App.tsx";
+
+defineSetAll();
+
+// A stored lightswitch override paints from the first render; Lightswitch
+// keeps it in sync after mount.
+function storedTheme(): "light" | "dark" | undefined {
+  try {
+    const theme = localStorage.getItem(SET_LIGHTSWITCH_STORAGE_KEY);
+    return theme === "light" || theme === "dark" ? theme : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const container = document.getElementById("root");
+if (!container) throw new Error("#root not found");
+
+createRoot(container).render(
+  <StrictMode>
+    <App theme={storedTheme()} />
+  </StrictMode>,
+);
+`;
+
+export const appTsx = ({ title }) => `import {
+  Box,
+  Container,
+  Heading,
+  Inline,
+  Lightswitch,
+  Page,
+  Root,
+  Stack,
+  Text,
+} from "@monospaced/set-react";
+
+export function App({ theme }: { theme?: "light" | "dark" }) {
+  return (
+    <Root appOverscrollBehavior="none" appRoot theme={theme}>
+      <Page
+        footer={null}
+        header={
+          <Container maxInlineSize="none">
+            <Box background="transparent" paddingBlock="2xs" paddingInline="none">
+              <Inline gap="sm" justify="between">
+                <Heading size="md">${escapeHtml(title)}</Heading>
+                <Lightswitch size="sm" />
+              </Inline>
+            </Box>
+          </Container>
+        }
+        headerBorder="always"
+        headerSize="sm"
+      >
+        <Container>
+          <Box paddingBlock="lg" paddingInline="none" responsive>
+            <Stack gap="md">
+              <Heading level={1} responsive size="xl">
+                Hello, world
+              </Heading>
+              <Text as="p" responsive size="sm">
+                Edit <code>src/App.tsx</code> to begin.
+              </Text>
+            </Stack>
+          </Box>
+        </Container>
+      </Page>
+    </Root>
+  );
+}
+`;
+
+export const routeStub = () => `<!doctype html>
+<!-- Route marker. This page is rendered from src/pages.ts by the plugin in vite.config.ts. -->
+`;
+
+export const siteTs = ({ description, title }) => `export const site = {
+  name: ${JSON.stringify(title)},
+  description: ${JSON.stringify(description)},
+  // Set once the site has a domain; canonical and og:url derive from it.
+  url: "https://example.com",
+  ogImage: ${JSON.stringify(OG_IMAGE)},
+};
+`;
+
+export const documentTs = () => `import {
+  renderSetBox,
+  renderSetContainer,
+  renderSetHeading,
+  renderSetInline,
+  renderSetLightswitch,
+  renderSetPage,
+  renderSetRoot,
+} from "@monospaced/set-core";
+
+import { site } from "./site.ts";
+
+export interface Page {
+  /** Page title. The site name alone when omitted. */
+  title?: string;
+  /** Meta description. The site description when omitted. */
+  description?: string;
+  /** The main region, from Set's render functions. */
+  render: () => string | Promise<string>;
+}
+
+const escapeHtml = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+
+/*
+ * Stamps a stored lightswitch override onto the root before its content
+ * parses, so an overridden theme paints correctly on first load. Must be the
+ * root's first child: earlier and the root doesn't exist yet, later and
+ * content above it may already have painted in the wrong theme.
+ */
+const themeBootstrap = ${JSON.stringify(themeBootstrap)};
+
+const header = (): string =>
+  renderSetContainer({
+    maxInlineSize: "none",
+    children: renderSetBox({
+      background: "transparent",
+      paddingBlock: "2xs",
+      paddingInline: "none",
+      children: renderSetInline({
+        gap: "sm",
+        justify: "between",
+        children:
+          renderSetHeading({ children: escapeHtml(site.name), size: "md" }) +
+          renderSetLightswitch({ size: "sm" }),
+      }),
+    }),
+  });
+
+/** The full HTML document for \`page\` at \`route\`. */
+export async function renderDocument(page: Page, route: string): Promise<string> {
+  const title = page.title ? \`\${page.title} | \${site.name}\` : site.name;
+  const description = page.description ?? site.description;
+  const url = \`\${site.url}\${route}\`;
+
+  // Page always renders its footer region; the starter leaves it empty.
+  const body = renderSetRoot({
+    appOverscrollBehavior: "none",
+    appRoot: true,
+    children:
+      themeBootstrap +
+      renderSetPage({
+        children: await page.render(),
+        footer: "",
+        header: header(),
+        headerBorder: "always",
+        headerSize: "sm",
+      }),
+  });
+
+  return \`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="theme-color" content="#f8fbfb" media="(prefers-color-scheme: light)" />
+    <meta name="theme-color" content="#0e0f0f" media="(prefers-color-scheme: dark)" />
+    <title>\${escapeHtml(title)}</title>
+    <meta name="description" content="\${escapeHtml(description)}" />
+    <link rel="canonical" href="\${escapeHtml(url)}" />
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="\${escapeHtml(site.name)}" />
+    <meta property="og:title" content="\${escapeHtml(title)}" />
+    <meta property="og:description" content="\${escapeHtml(description)}" />
+    <meta property="og:url" content="\${escapeHtml(url)}" />
+    <meta property="og:image" content="\${site.ogImage}" />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="\${escapeHtml(title)}" />
+    <meta name="twitter:description" content="\${escapeHtml(description)}" />
+    <meta name="twitter:image" content="\${site.ogImage}" />
+    <link rel="icon" href="/favicons/favicon.ico" sizes="32x32" />
+    <link rel="icon" href="/favicons/favicon.svg" type="image/svg+xml" />
+    <link rel="apple-touch-icon" href="/favicons/apple-touch-icon.png" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+  </head>
+  <body>
+    \${body}
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+\`;
+}
+`;
+
+export const pagesTs = () => `import type { Page } from "./document.ts";
+import index from "./pages/index.ts";
+
+/** Routes to pages. A route is a folder holding an index.html; add both. */
+export const pages: Record<string, Page> = {
+  "/": index,
+};
+`;
 
-export const tsconfig = () =>
+export const indexPageTs = () => `import {
+  renderSetBox,
+  renderSetContainer,
+  renderSetHeading,
+  renderSetStack,
+  renderSetText,
+} from "@monospaced/set-core";
+
+import type { Page } from "../document.ts";
+
+const page: Page = {
+  render: () =>
+    renderSetContainer({
+      children: renderSetBox({
+        paddingBlock: "lg",
+        paddingInline: "none",
+        responsive: true,
+        children: renderSetStack({
+          gap: "md",
+          children:
+            renderSetHeading({
+              children: "Hello, world",
+              level: 1,
+              responsive: true,
+              size: "xl",
+            }) +
+            renderSetText({
+              as: "p",
+              children: "Edit <code>src/pages/index.ts</code> to begin.",
+              responsive: true,
+              size: "sm",
+            }),
+        }),
+      }),
+    }),
+};
+
+export default page;
+`;
+
+export const tsconfig = ({ variant }) =>
   json({
     compilerOptions: {
+      allowImportingTsExtensions: true,
+      ...(variant === "react" ? { jsx: "react-jsx" } : {}),
       lib: ["ES2022", "DOM", "DOM.Iterable"],
       module: "ESNext",
       moduleResolution: "Bundler",
@@ -128,13 +428,14 @@ export const tsconfig = () =>
       skipLibCheck: true,
       strict: true,
       target: "ES2022",
-      types: ["vite/client"],
+      types: ["node", "vite/client"],
     },
     include: ["src", "*.config.ts"],
   });
 
-export const eslintConfig =
-  () => `import setEslint from "@monospaced/set-config/eslint";
+export const eslintConfig = ({
+  variant,
+}) => `import setEslint from "@monospaced/set-config/eslint${variant === "react" ? "/react" : ""}";
 
 export default [...setEslint];
 `;
@@ -195,6 +496,9 @@ export const vscodeExtensions = () =>
 export const pnpmWorkspace =
   () => `# Minimum age of a release before it installs, in minutes (3 days).
 minimumReleaseAge: 4320
+# Set's own packages install as soon as they are released.
+minimumReleaseAgeExclude:
+  - "@monospaced/*"
 `;
 
 export const syncSet = () => `/*
@@ -232,7 +536,122 @@ if (existsSync(new URL(".git", \`file://\${root}\`))) {
 }
 `;
 
-export const readme = ({ description, title }) => `# ${title}
+export const ciYml = () => `name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Stylelint
+        run: pnpm run stylelint
+
+      - name: Format check
+        run: pnpm run format:check
+
+      - name: Typecheck
+        run: pnpm run typecheck
+
+      - name: Test
+        run: pnpm run test
+
+      - name: Build
+        run: pnpm run build
+`;
+
+export const dependabotYml = () => `version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    # Mirrors minimumReleaseAge in pnpm-workspace.yaml, so proposals stay
+    # installable under it.
+    cooldown:
+      default-days: 3
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+`;
+
+export const readme = ({ description, title, variant }) => {
+  const pages =
+    variant === "react"
+      ? `## Pages
+
+This variant is an app: one \`index.html\`, rendered on the client by React from \`src/main.tsx\`. \`src/App.tsx\` composes the page from \`@monospaced/set-react\` components, and \`Root\` takes its initial \`theme\` from the stored lightswitch choice so an overridden theme paints from the first render. Routes live in React, not in folders; for a site with pages as files, the \`prerender\` variant of \`@monospaced/create-set\` renders them from code.
+
+Component tests run in jsdom (\`test.environment\` in \`vite.config.ts\`).
+`
+      : variant === "prerender"
+        ? `## Pages
+
+A page is a folder with an \`index.html\` route marker and a module in \`src/pages\` that exports its title, description and a \`render()\` built from Set's render functions. \`src/pages.ts\` maps routes to modules, and \`src/document.ts\` wraps each page in the shared head and shell at build time. To add \`/about/\`:
+
+1. Copy \`index.html\` to \`about/index.html\`.
+2. Add \`src/pages/about.ts\` (or \`src/pages/about/index.ts\`, to keep content beside it).
+3. Register it in \`src/pages.ts\`.
+
+\`renderDocument\` in \`src/document.ts\` owns the shell around every page and receives the route, so a nav in its header can mark the current link (\`current: "page"\` on \`renderSetLink\`) by comparing hrefs to it.
+
+Page modules are imported by \`vite.config.ts\`, so the dev server restarts when one changes rather than hot-replacing. Keep them to render functions and data: no CSS imports and no DOM at the top level, so \`main.ts\` can import one to re-render on the client.
+
+For Markdown content, read the file beside the page and render it in \`Prose\` with \`@monospaced/set-markdown\` (\`pnpm add @monospaced/set-markdown\`):
+
+\`\`\`ts
+import { readFileSync } from "node:fs";
+
+import { renderSetProse } from "@monospaced/set-core";
+import { processMarkdown } from "@monospaced/set-markdown";
+
+const content = readFileSync(new URL("./content.md", import.meta.url), "utf8");
+
+export default {
+  title: "About",
+  render: () => renderSetProse({ children: processMarkdown(content) }),
+};
+\`\`\`
+`
+        : `## Pages
+
+A page is a folder with an \`index.html\`; its path is its URL (\`about/index.html\` is \`/about/\`). Vite discovers them, so adding a page is adding the folder. Each page carries its own head and its own \`<script type="module" src="/src/main.ts">\`; copy \`index.html\` to start one. When keeping the heads in step by hand becomes a chore, the \`prerender\` variant of \`@monospaced/create-set\` renders pages from code with one shared head.
+`;
+
+  return `# ${title}
 
 ${description}
 
@@ -247,11 +666,20 @@ Built with [Set](https://set.monospaced.com), scaffolded by \`@monospaced/create
 - \`pnpm typecheck\`
 - \`pnpm test\`
 
-Prettier, Stylelint and ESLint fixes run on staged files before every commit via Husky and lint-staged.
+Prettier, Stylelint and ESLint fixes run on staged files before every commit via Husky and lint-staged. CI runs the same checks plus typecheck, test and build on every pull request (\`.github/workflows/ci.yml\`), and Dependabot proposes grouped updates weekly.
 
+${pages}
 ## After bootstrapping
 
-- Set the canonical URL and \`og:url\` in \`index.html\` once the site has a domain.
+- ${
+    variant === "prerender"
+      ? "Set `url` in `src/site.ts` once the site has a domain; canonical URLs derive from it."
+      : "Set the canonical URL and `og:url` in `index.html` once the site has a domain."
+  }
 - \`.vscode/set.catalog.css\`, \`.claude/skills/\`, \`.agents/skills/\` and \`public/favicons/\` are copied from Set on every install by \`scripts/sync-set.mjs\`. Upgrade Set to refresh them rather than editing them by hand.
-- Markdown content? \`pnpm add @monospaced/set-markdown\` renders GFM to safe HTML that pairs with core's \`prose\` component.
-`;
+${
+  variant === "prerender"
+    ? ""
+    : "- Markdown content? `pnpm add @monospaced/set-markdown` renders GFM to safe HTML that pairs with core's `prose` component.\n"
+}`;
+};

package/src/toolchain.mjs

@@ -5,3 +5,24 @@ export const NODE_MAJOR = 26;
 
 /** pnpm version written to `packageManager`; `engines` takes its major. */
 export const PNPM_VERSION = "12.17.0";
+
+/** Tooling installed into every project, at the monorepo's ranges. */
+export const TOOLING = {
+  "@types/node": "^26.6.6",
+  husky: "^9.1.7",
+  "lint-staged": "^17.0.4",
+  prettier: "^3.8.3",
+  vite: "^7.3.2",
+  vitest: "^4.1.6",
+};
+
+/** What the React variant adds, at the monorepo's ranges. */
+export const REACT = {
+  dependencies: { react: "^19.2.6", "react-dom": "^19.2.6" },
+  devDependencies: {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    jsdom: "^29.1.1",
+  },
+};