create-packkit 2.5.0 → 2.6.0

package/README.md

@@ -28,29 +28,114 @@ Then `cd`, and you already have a working project — `build`, `test`, and `lint
 
 No install needed: **[danmat.github.io/create-packkit](https://danmat.github.io/create-packkit/)** — tick the options, preview the file tree, and **download a zip** (or copy the equivalent `npx create-packkit` command). Everything runs in your browser.
 
-## What you can pick
-
-| Area | Options |
-|---|---|
-| **Language** | TypeScript (strict) · JavaScript (ESM) |
-| **Module format** | **ESM-only (default)** · dual (ESM + CJS) · CJS — proper `exports` map |
-| **Target** | Library · CLI tool · **HTTP service (Hono)** · **App (Vite SPA)** · any combination |
-| **Framework** | None · **React** · **Vue** · **Svelte** (component libraries or apps) |
-| **Storybook** | optional, for React / Vue / Svelte component libraries |
-| **Bundler** | tsup · tsdown · unbuild · rollup · none (tsc) · optional **minify** |
-| **Tests** | Vitest · Jest · node:test · none (+ coverage) |
-| **Lint/format** | ESLint + Prettier · Biome · oxlint · none |
-| **Git hooks** | simple-git-hooks · husky + lint-staged · lefthook · none |
-| **Release** | Changesets · release-it · np · none |
-| **GitHub Actions** | CI · npm publish (provenance) · Pages · CodeQL · Codecov · stale bot |
-| **Deps** | Renovate · Dependabot · none |
-| **Repo** | LICENSE · community files · **AGENTS.md + CLAUDE.md** · VS Code · `.editorconfig` |
-| **Monorepo** | optional pnpm/npm/yarn workspace with **Turborepo** + Changesets + example packages |
-| **Package manager** | npm · pnpm · yarn · bun |
+## Options reference
+
+Every flag, its values (**default** in bold), and what it's for. Prefer the interactive [web configurator](https://danmat.github.io/create-packkit/) — the same descriptions appear as you hover. _This table is generated from the schema (`npm run gen:reference`)._
+
+<!-- OPTIONS:START -->
+
+### Package
+
+| Flag | Values | What it does |
+|---|---|---|
+| `--name` | — | The npm package name. Scoped names like `@you/pkg` are fine. |
+| `--description` | — | One-line summary — used in package.json and the README heading. |
+| `--author` | — | Your name (and optionally email/URL). Populates package.json + LICENSE. |
+| `--keywords` | — | Comma-separated npm keywords to help people discover the package. |
+| `--repo` | — | Git repository URL. Wires up repository/bugs/homepage links and CI badges. |
+
+### Core
+
+| Flag | Values | What it does |
+|---|---|---|
+| `--language` | **ts** · js | TypeScript (strict, recommended) or plain ESM JavaScript. TS gives you types, editor help, and generated .d.ts for consumers. |
+| `--module` | **esm** · dual · cjs | How the package is consumed. ESM-only (default) is the modern, leanest choice — Node 20.19+/22.12+ can `require()` ESM. Pick dual only if you must support older CJS-only consumers; cjs-only is rarely needed. |
+| `--server` | **hono** · fastify · express | For the service target: Hono (fast, web-standard, tiny — default), Fastify (batteries-included, plugins, schema validation), or Express (ubiquitous, huge ecosystem). |
+| `--target` | **library** · cli · service · app | What you are building — mix and match: a library (importable package), a CLI (ships a bin), an HTTP service, or an app (Vite SPA). |
+| `--monorepo` | on / off (default: **off**) | Generate a pnpm + Turborepo workspace with two linked example packages and Changesets. Only worth it when ≥2 packages share code. |
+| `--framework` | **none** · react · vue · svelte | UI framework for component libraries and apps: React, Vue, or Svelte (or none for a plain package). |
+| `--pm` | **npm** · pnpm · yarn · bun | Which package manager the scripts, lockfile, and CI target: npm, pnpm, yarn, or bun. |
+| `--node` | 22 · **24** · 26 | Minimum Node line to support. Choices track Node’s own release schedule (Active LTS is the default); this sets engines + .nvmrc. |
+
+### Build
+
+| Flag | Values | What it does |
+|---|---|---|
+| `--bundler` | **tsup** · tsdown · unbuild · rollup · none | How the library is built. tsup (default, esbuild-fast) and tsdown suit most libs; unbuild for zero-config; rollup for full control; none = tsc-only (or no build). |
+| `--minify` | on / off (default: **off**) | Minify the build output. Best for CLIs and browser bundles; usually unnecessary for libraries (consumers minify). |
+| `--no-sourcemaps` | on / off (default: **on**) | Ship source + JS/declaration maps so consumers can step into and go-to-definition on your original code when debugging. On by default for libraries. |
+
+### Quality
+
+| Flag | Values | What it does |
+|---|---|---|
+| `--test` | **vitest** · jest · node · none | Test runner: Vitest (fast, Vite-native, default), Jest (classic, huge ecosystem), or Node’s built-in node:test (zero deps). |
+| `--no-coverage` | on / off (default: **on**) | Collect code-coverage reports (v8) and add a `coverage` script. Pairs with the Codecov workflow. |
+| `--storybook` | on / off (default: **off**) | Add Storybook to develop and document components in isolation. Component libraries only. |
+| `--e2e` | on / off (default: **off**) | Add Playwright end-to-end tests for app targets: a config that boots your dev server, an example spec, and a CI job. |
+| `--env` | on / off (default: **off**) | Type-safe environment variables: a Zod-validated `src/env.ts` that fails fast on misconfig, plus a `.env.example`. For services and CLIs. |
+| `--pkg-checks` | on / off (default: **off**) | Verify the published package is correct with publint + are-the-types-wrong (exports map, types resolution, ESM/CJS). Highly recommended for libraries. |
+| `--knip` | on / off (default: **off**) | Find unused files, dependencies, and exports so the project doesn’t accumulate dead weight. |
+| `--size-limit` | on / off (default: **off**) | Add a bundle-size budget (size-limit) that measures your built entry and fails CI if it exceeds the limit — catches accidental bloat. |
+| `--doctor` | on / off (default: **off**) | Add an env doctor (`npm run doctor`) that warns when the local Node / package manager don’t match what the project expects. Warn-only. |
+| `--lint` | **eslint-prettier** · biome · oxlint · none | Linter + formatter: ESLint + Prettier (default, most compatible), Biome (one fast tool for both), or oxlint (Rust-fast linting). |
+| `--hooks` | **simple-git-hooks** · husky · lefthook · none | Pre-commit hooks that run lint-staged: simple-git-hooks (tiny, default), husky (popular), or lefthook (fast, parallel). |
+
+### Release
+
+| Flag | Values | What it does |
+|---|---|---|
+| `--canary` | on / off (default: **off**) | Add a workflow that publishes snapshot builds (x.y.z-canary-<hash>) to a `canary` dist-tag so people can test unreleased changes. Requires Changesets. |
+| `--release` | **changesets** · release-it · np · none | How you version + publish: Changesets (default, great for libraries and monorepos), release-it, np, or none. |
+| `--jsr` | on / off (default: **off**) | Also publish to JSR, the TypeScript-first registry. For plain ESM TypeScript libraries. |
+
+### CI / CD
+
+| Flag | Values | What it does |
+|---|---|---|
+| `--workflows` | **ci** · **npm-publish** · pages · codeql · codecov · stale | GitHub Actions to include: ci (lint/test/build), npm-publish (provenance), pages (deploy Storybook/site), codeql (security), codecov (coverage), stale. |
+| `--deps` | **renovate** · dependabot · none | Automated dependency updates: Renovate (default, powerful) or Dependabot (built into GitHub). |
+
+### Repository
+
+| Flag | Values | What it does |
+|---|---|---|
+| `--license` | **MIT** · Apache-2.0 · ISC · none | Open-source license for the LICENSE file and package.json (MIT recommended), or none. |
+| `--no-community` | on / off (default: **on**) | Community health files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, and issue/PR templates. |
+| `--no-agents` | on / off (default: **on**) | AI-agent instructions (AGENTS.md + CLAUDE.md) so coding agents know how to build, test, and work in the repo. |
+| `--no-vscode` | on / off (default: **on**) | VS Code workspace settings + recommended-extensions so the repo is set up consistently on open. |
+| `--no-editorconfig` | on / off (default: **on**) | An .editorconfig so every editor uses the same indentation and line endings. |
+| `--no-git` | on / off (default: **on**) | Run `git init` and make an initial commit after scaffolding. |
+| `--no-install` | on / off (default: **on**) | Install dependencies automatically after scaffolding. |
+
+<!-- OPTIONS:END -->
 
 ## Presets
 
-`ts-lib` · `js-lib` · `ts-cli` / `cli` · `react-lib` · `react-lib-js` · `react-app` · `vue-lib` · `vue-app` · `svelte-lib` · `svelte-app` · `node-service` · `monorepo` · `oss` · `minimal` · `full` — named bundles of the options above. See the [roadmap](ROADMAP.md) for what's next.
+Named bundles of the options above — `npx packkit <preset> <name> -y`.
+
+<!-- PRESETS:START -->
+
+| Preset | Shortcut | What you get |
+|---|---|---|
+| `ts-lib` | `lib` | TypeScript library — ESM-only, tsup, Vitest, ESLint. |
+| `js-lib` | `jslib` | JavaScript (ESM) library — tsup, Vitest, ESLint. |
+| `ts-cli` | — | TypeScript CLI + library — ESM, ships a bin. |
+| `cli` | — | TypeScript CLI tool — ESM, ships a bin. |
+| `react-lib` | `rlib` | React component library (TS) — JSX, peer deps, jsdom tests. |
+| `react-lib-js` | — | React component library (JS) — JSX, peer deps, jsdom tests. |
+| `react-app` | `rapp` | React SPA — Vite dev server, build, Testing Library. |
+| `vue-lib` | `vlib` | Vue component library — Vite lib build (SFCs), ESM + types. |
+| `vue-app` | `vapp` | Vue SPA — Vite dev server, build, Testing Library. |
+| `svelte-lib` | `slib` | Svelte component library — ships source, peer svelte, jsdom tests. |
+| `svelte-app` | `sapp` | Svelte SPA — Vite dev server, build, Testing Library. |
+| `node-service` | `svc`, `service` | Node HTTP service (Hono) — tsx dev, tsup build, Dockerfile. |
+| `monorepo` | — | pnpm + Turborepo workspace — two example packages, Changesets, CI. |
+| `oss` | — | Full open-source library — coverage, CodeQL, Codecov, Renovate, Changesets. |
+| `minimal` | — | Bare TS library — tsup only, no tests/lint/CI. |
+| `full` | — | Everything on — library + CLI, all workflows and extras. |
+
+<!-- PRESETS:END -->
 
 **Team profiles:** save a partial config as `packkit.config.json` (or any file) and reuse it with `npx create-packkit my-lib --from ./packkit.config.json` — flags still override the file.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-packkit",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Highly configurable scaffolder for modern npm packages and CLIs — pick your stack (TS/JS, bundler, tests, linter, CI, releases) from a CLI or a web configurator.",
   "type": "module",
   "bin": {
@@ -27,7 +27,8 @@
     "check:deps": "node scripts/check-template-deps.mjs",
     "integration": "node scripts/integration.mjs",
     "build:web": "esbuild src/core/index.js --bundle --format=esm --outfile=docs/packkit-core.js",
-    "update:node": "node scripts/update-node-versions.mjs"
+    "update:node": "node scripts/update-node-versions.mjs",
+    "gen:reference": "node scripts/gen-reference.mjs"
   },
   "repository": {
     "type": "git",

package/src/cli/index.js

@@ -2,7 +2,7 @@ import { resolve, basename } from 'node:path';
 import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
-import { generate, fromPreset, normalizeConfig, PRESET_NAMES, OPTIONS, PRESET_INFO, PRESET_ALIASES } from '../core/index.js';
+import { generate, fromPreset, normalizeConfig, PRESET_NAMES, OPTIONS, OPTION_HELP, PRESET_INFO, PRESET_ALIASES } from '../core/index.js';
 import { engineFloor, meetsNodeFloor } from '../core/node.js';
 import { parseCliArgs } from './args.js';
 import { runWizard } from './wizard.js';
@@ -18,48 +18,75 @@ const pkgVersion = () => {
 };
 
 const HELP = `
-packkit — scaffold a modern npm package or CLI
+packkit — scaffold a modern npm package, CLI, service, or app
 
 Usage:
   npm create packkit@latest [name] [options]
   npx packkit [preset] [name] [options]
 
-Presets: ${PRESET_NAMES.join(', ')}
-
-Options:
-  --preset <name>     Use a preset (skips the wizard)
-  --from <file>       Load defaults from a JSON profile (or packkit.config.json)
-  --name <name>       Package name
-  --here              Scaffold into the current directory
-  -y, --yes           Accept defaults / preset, no prompts (one-shot)
-  --recommended       Alias for --yes — recommended defaults in one command
-  --monorepo          Generate a pnpm/Turborepo workspace
-  --no-install        Skip dependency install
-  --no-git            Skip git init
-  --pm <manager>      npm | pnpm | yarn | bun
-  --language <ts|js>  --module <esm|cjs|dual>  --framework <none|react|vue|svelte>
-  --target <library|cli|service|app>   (repeatable)   --storybook
-  --server <hono|fastify|express>   (HTTP service framework)
-  --bundler <tsup|tsdown|unbuild|rollup|none>   --minify
-  --test <vitest|jest|node|none>   --e2e (Playwright, for apps)
-  --env (type-safe env validation, services/CLIs)   --no-sourcemaps
+Run with no options for an interactive wizard, or add -y for recommended
+defaults in one shot. Every option is documented (with why-you'd-use-it) at:
+  https://danmat.github.io/create-packkit/   ·   and in the README reference.
+
+Presets:
+  ${PRESET_NAMES.join('  ')}
+  shortcuts: lib jslib rlib rapp vlib vapp slib sapp svc
+
+Getting started:
+  --preset <name>      Start from a preset (skips the wizard)
+  --from <file>        Load defaults from a JSON profile (or packkit.config.json)
+  -y, --yes            Accept defaults / preset, no prompts (one-shot)
+  --recommended        Alias for -y
+  --here               Scaffold into the current directory
+  --no-install         Skip dependency install
+  --no-git             Skip git init
+
+Stack:
+  --language <ts|js>
+  --module <esm|cjs|dual>                 ESM-only is the default
+  --framework <none|react|vue|svelte>
+  --target <library|cli|service|app>      repeatable
+  --server <hono|fastify|express>         HTTP service framework
+  --pm <npm|pnpm|yarn|bun>
+  --monorepo                              pnpm + Turborepo workspace
+
+Build & test:
+  --bundler <tsup|tsdown|unbuild|rollup|none>
+  --minify                                Minify the build output
+  --no-sourcemaps                         Don't ship source / sourcemaps
+  --test <vitest|jest|node|none>
+  --e2e                                   Playwright end-to-end tests (apps)
+  --size-limit                            Bundle-size budget + CI gate (libs)
+
+Quality:
   --lint <eslint-prettier|biome|oxlint|none>
-  --hooks <simple-git-hooks|husky|lefthook|none>  --release <changesets|release-it|np|none>
-  --workflows <ci|npm-publish|pages|codeql|codecov|stale>   (repeatable)
-  --deps <renovate|dependabot|none>  --license <MIT|Apache-2.0|ISC|none>
-  --pkg-checks (publint + are-the-types-wrong)   --knip   --jsr   --canary
-  --size-limit (bundle-size budget, libraries)   --doctor (env check)
+  --hooks <simple-git-hooks|husky|lefthook|none>
+  --pkg-checks                            publint + are-the-types-wrong
+  --knip                                  Find unused files / deps / exports
+  --doctor                                Warn on Node / pm mismatch
+  --env                                   Type-safe env validation (services/CLIs)
+
+Release & CI:
+  --release <changesets|release-it|np|none>
+  --canary                                Snapshot/canary release workflow
+  --jsr                                   Also publish to JSR
+  --workflows <ci|npm-publish|pages|codeql|codecov|stale>   repeatable
+  --deps <renovate|dependabot|none>
+
+Repo & extras:
+  --license <MIT|Apache-2.0|ISC|none>
+  --storybook                             Storybook (component libraries)
   --no-coverage  --no-community  --no-agents  --no-vscode  --no-editorconfig
-  --schema            Print the full option/preset schema as JSON (for tools/agents)
-  -h, --help          Show this help
-  -v, --version       Show version
 
-Preset shortcuts: lib, jslib, rlib, rapp, vlib, vapp, slib, sapp, svc
+Other:
+  --schema             Print the full option/preset schema as JSON (for agents)
+  -h, --help           Show this help          -v, --version   Show version
 
 Examples:
-  npx packkit ts-lib my-lib
-  npm create packkit@latest my-cli -- --preset cli
-  npx packkit --preset full my-pkg --pm pnpm
+  npx packkit ts-lib my-lib -y
+  npx packkit react-app my-app --e2e
+  npx packkit node-service api --server fastify --env
+  npm create packkit@latest my-pkg -- --preset oss --pm pnpm
 `;
 
 export async function run(argv = process.argv.slice(2)) {
@@ -68,7 +95,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (args.version) return void console.log(pkgVersion());
   if (args.schema) {
     // Machine-readable interface for tools/agents: every option, preset, and alias.
-    return void console.log(JSON.stringify({ version: pkgVersion(), options: OPTIONS, presets: PRESET_INFO, aliases: PRESET_ALIASES }, null, 2));
+    return void console.log(JSON.stringify({ version: pkgVersion(), options: OPTIONS, optionHelp: OPTION_HELP, presets: PRESET_INFO, aliases: PRESET_ALIASES }, null, 2));
   }
 
   // Only prompt when the user gave nothing to go on — a preset, --yes, a

package/src/core/index.js

@@ -2,14 +2,14 @@
 // generate(config) -> { config, files: { path: contents }, postCommands, summary }
 // The CLI writes `files` to disk; the web configurator zips them.
 
-import { normalizeConfig, OPTIONS, GROUPS, defaultConfig } from './options.js';
+import { normalizeConfig, OPTIONS, GROUPS, OPTION_HELP, defaultConfig } from './options.js';
 import { deepMerge, toJson } from './render.js';
 import { finalizePackageJson } from './pkg.js';
 import features from './features/index.js';
 import { buildMonorepo } from './monorepo.js';
 import { PRESETS, PRESET_NAMES, PRESET_INFO, PRESET_ALIASES, resolvePreset } from './presets.js';
 
-export { OPTIONS, GROUPS, defaultConfig, normalizeConfig, PRESETS, PRESET_NAMES, PRESET_INFO, PRESET_ALIASES, resolvePreset };
+export { OPTIONS, GROUPS, OPTION_HELP, defaultConfig, normalizeConfig, PRESETS, PRESET_NAMES, PRESET_INFO, PRESET_ALIASES, resolvePreset };
 
 /** Apply a named preset (or alias) over the defaults, returning a full config. */
 export function fromPreset(name, overrides = {}) {

package/src/core/options.js

@@ -197,6 +197,50 @@ export const GROUPS = [
   { id: 'repo', label: 'Repository' },
 ];
 
+// Plain-English "what it is / why you'd pick it" for every option. One source
+// of truth for the web tooltips, the README reference, and `--schema` (agents).
+export const OPTION_HELP = {
+  name: 'The npm package name. Scoped names like `@you/pkg` are fine.',
+  description: 'One-line summary — used in package.json and the README heading.',
+  author: 'Your name (and optionally email/URL). Populates package.json + LICENSE.',
+  keywords: 'Comma-separated npm keywords to help people discover the package.',
+  repo: 'Git repository URL. Wires up repository/bugs/homepage links and CI badges.',
+  language: 'TypeScript (strict, recommended) or plain ESM JavaScript. TS gives you types, editor help, and generated .d.ts for consumers.',
+  moduleFormat: 'How the package is consumed. ESM-only (default) is the modern, leanest choice — Node 20.19+/22.12+ can `require()` ESM. Pick dual only if you must support older CJS-only consumers; cjs-only is rarely needed.',
+  target: 'What you are building — mix and match: a library (importable package), a CLI (ships a bin), an HTTP service, or an app (Vite SPA).',
+  serviceFramework: 'For the service target: Hono (fast, web-standard, tiny — default), Fastify (batteries-included, plugins, schema validation), or Express (ubiquitous, huge ecosystem).',
+  monorepo: 'Generate a pnpm + Turborepo workspace with two linked example packages and Changesets. Only worth it when ≥2 packages share code.',
+  framework: 'UI framework for component libraries and apps: React, Vue, or Svelte (or none for a plain package).',
+  packageManager: 'Which package manager the scripts, lockfile, and CI target: npm, pnpm, yarn, or bun.',
+  nodeVersion: 'Minimum Node line to support. Choices track Node’s own release schedule (Active LTS is the default); this sets engines + .nvmrc.',
+  bundler: 'How the library is built. tsup (default, esbuild-fast) and tsdown suit most libs; unbuild for zero-config; rollup for full control; none = tsc-only (or no build).',
+  minify: 'Minify the build output. Best for CLIs and browser bundles; usually unnecessary for libraries (consumers minify).',
+  sourcemaps: 'Ship source + JS/declaration maps so consumers can step into and go-to-definition on your original code when debugging. On by default for libraries.',
+  test: 'Test runner: Vitest (fast, Vite-native, default), Jest (classic, huge ecosystem), or Node’s built-in node:test (zero deps).',
+  coverage: 'Collect code-coverage reports (v8) and add a `coverage` script. Pairs with the Codecov workflow.',
+  storybook: 'Add Storybook to develop and document components in isolation. Component libraries only.',
+  e2e: 'Add Playwright end-to-end tests for app targets: a config that boots your dev server, an example spec, and a CI job.',
+  sizeLimit: 'Add a bundle-size budget (size-limit) that measures your built entry and fails CI if it exceeds the limit — catches accidental bloat.',
+  doctor: 'Add an env doctor (`npm run doctor`) that warns when the local Node / package manager don’t match what the project expects. Warn-only.',
+  env: 'Type-safe environment variables: a Zod-validated `src/env.ts` that fails fast on misconfig, plus a `.env.example`. For services and CLIs.',
+  pkgChecks: 'Verify the published package is correct with publint + are-the-types-wrong (exports map, types resolution, ESM/CJS). Highly recommended for libraries.',
+  knip: 'Find unused files, dependencies, and exports so the project doesn’t accumulate dead weight.',
+  lint: 'Linter + formatter: ESLint + Prettier (default, most compatible), Biome (one fast tool for both), or oxlint (Rust-fast linting).',
+  gitHooks: 'Pre-commit hooks that run lint-staged: simple-git-hooks (tiny, default), husky (popular), or lefthook (fast, parallel).',
+  release: 'How you version + publish: Changesets (default, great for libraries and monorepos), release-it, np, or none.',
+  canary: 'Add a workflow that publishes snapshot builds (x.y.z-canary-<hash>) to a `canary` dist-tag so people can test unreleased changes. Requires Changesets.',
+  jsr: 'Also publish to JSR, the TypeScript-first registry. For plain ESM TypeScript libraries.',
+  workflows: 'GitHub Actions to include: ci (lint/test/build), npm-publish (provenance), pages (deploy Storybook/site), codeql (security), codecov (coverage), stale.',
+  deps: 'Automated dependency updates: Renovate (default, powerful) or Dependabot (built into GitHub).',
+  license: 'Open-source license for the LICENSE file and package.json (MIT recommended), or none.',
+  community: 'Community health files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, and issue/PR templates.',
+  agents: 'AI-agent instructions (AGENTS.md + CLAUDE.md) so coding agents know how to build, test, and work in the repo.',
+  vscode: 'VS Code workspace settings + recommended-extensions so the repo is set up consistently on open.',
+  editorconfig: 'An .editorconfig so every editor uses the same indentation and line endings.',
+  gitInit: 'Run `git init` and make an initial commit after scaffolding.',
+  install: 'Install dependencies automatically after scaffolding.',
+};
+
 /** Build a default config from the schema. */
 export function defaultConfig() {
   const cfg = {};