@rshono/create 1.0.0-rc.1 → 1.0.0-rc.11

package/README.md

@@ -1,66 +1,113 @@
-# @rshono/create
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rshono/rshono/main/logo.svg" alt="" width="72" height="72" />
+</p>
 
-Scaffolds a new [rshono](https://github.com/rshono/rshono) app — Hono + Rspack + React Server Components.
+<h1 align="center">@rshono/create</h1>
+
+<p align="center">
+  Scaffolds a new <a href="https://github.com/rshono/rshono">rshono</a> app — Hono + Rspack + React Server Components.
+</p>
 
 ```bash
-npm  create @rshono@latest my-app
-pnpm create @rshono my-app
+npx  @rshono/create@latest my-app
+pnx  @rshono/create my-app
+bunx @rshono/create my-app
 yarn create @rshono my-app
-bun  create @rshono my-app
 ```
 
-The package manager that ran it is the one the project gets: it is read from `npm_config_user_agent`, used
-for the install, written into `packageManager` for Corepack, and used in every command the closing summary
-prints. Nothing asks you which one you meant.
+The package manager that ran it is the one the project gets: it is read from `npm_config_user_agent`, which
+every one of these runners sets, and it is used for the install, written into `packageManager` for Corepack,
+and used in every command the closing summary prints. Nothing asks you which one you meant.
+
+Yarn is the odd row out because `yarn dlx` is Berry-only, while `yarn create` works in either — and `pnx`
+arrived in pnpm 10.16, before which it is `pnpm dlx`.
 
 ## The questions
 
 Six, each with a default, and each answerable by a flag instead:
 
-| Question              | Default            | Flag                                                                |
-| --------------------- | ------------------ | ------------------------------------------------------------------- |
-| Where should it go?   | `my-rshono-app`    | first positional argument, or `.`                                   |
-| Where is it deployed? | `node`             | `--deploy node\|bun\|deno\|cloudflare\|vercel\|netlify\|aws-lambda` |
-| Styling               | plain CSS          | `--tailwind` / `--no-tailwind`                                      |
-| Formatting & linting  | Prettier + oxlint  | `--quality prettier-oxlint\|prettier-eslint\|biome\|oxc\|none`      |
-| Install dependencies? | yes                | `--no-install`                                                      |
-| Initialize git?       | yes, unless nested | `--no-git`                                                          |
-
-Plus `--formatter` and `--linter` to set either half of the quality preset on its own, `--force` to
-scaffold into a directory that is not empty, `--dry-run` to see the file list and write nothing, and `-y`
-to take the defaults for everything not given. **A non-interactive terminal implies `-y`**, so this is one
-command in CI or from an agent:
+| Question              | Default            | Flag                                                           |
+| --------------------- | ------------------ | -------------------------------------------------------------- |
+| Where should it go?   | `my-rshono-app`    | first positional argument, or `.`                              |
+| Where is it deployed? | `node`             | `-d, --deploy node\|cloudflare\|vercel\|aws-lambda`            |
+| Styling               | plain CSS          | `--tailwind` / `--no-tailwind`                                 |
+| Formatting & linting  | Prettier + oxlint  | `--quality prettier-oxlint\|prettier-eslint\|biome\|oxc\|none` |
+| Install dependencies? | yes                | `--no-install`                                                 |
+| Initialize git?       | yes, unless nested | `--no-git`                                                     |
+
+Plus `--formatter prettier\|biome\|oxfmt\|none` and `--linter oxlint\|eslint\|biome\|none` to set either half
+of the quality preset on its own, `--pm npm\|pnpm\|yarn\|bun` to override the package manager that was
+detected, `--force` to scaffold into a directory that is not empty, `--dry-run` to see the file list and write
+nothing, and `-y` to take the defaults for everything not given. **A non-interactive terminal implies `-y`**,
+so this is one command in CI or from an agent:
 
 ```bash
-npm create @rshono@latest my-app -y --deploy cloudflare --tailwind --quality biome
+npx @rshono/create@latest my-app -y --deploy cloudflare --tailwind --quality biome
 ```
 
-The deploy targets, and the deploy command each one prints, are generated from the framework's own
-presets — a target added to rshono appears here with no edit.
+The deploy targets, and the deploy command each one prints, are generated from the framework's own presets —
+a target added to rshono appears here with no edit.
 
 ## What you get
 
 ```
-rshono.config.ts        the chosen deploy target; everything else commented with its default
+package.json            scripts, including the target's own, and the exact pins rshono is tested against
+rshono.config.ts        the chosen deploy target; every other setting takes its default
 tsconfig.json           strict, with @/* → ./src/*
 .env                    committed defaults; secrets go in .env.local
+.gitignore              plus whatever each chosen feature adds, under a heading naming it
+README.md               the app's own commands, layout and deploy step
+AGENTS.md               where an agent finds the framework docs; CLAUDE.md imports it
 public/                 favicon.svg, robots.txt
-src/routes.ts           one page, a 404 and a 500, with the other route kinds commented
-src/server.ts           AppEnv, request-id middleware, error reporting, /api/health, redirects, AppType
-src/actions.ts          a 'use server' action, called from a form that works without JavaScript
-src/components/         layout, home, greet-form ('use client'), 404, 500
-src/lib/env.ts          both sides of the PUBLIC_ boundary in one place
+src/routes.ts           one page, a 404 and a 500
+src/server.ts           error reporting, trailing-slash and old-path redirects, AppType
+src/components/         layout, home, 404, 500
 src/styles.css          element-level CSS, or the Tailwind entry
+src/env.d.ts            the CSS-import declaration the compiler needs
 pnpm-workspace.yaml     pnpm only: which dependency install scripts this app runs (none of them)
 ```
 
-Then, if the dependencies were installed, the scaffold is run through its own formatter — so a fresh
-project passes its own `format:check` rather than reporting a diff nobody made.
+Scaffolding runs the install and nothing else — no formatter, no linter. The templates are written to satisfy
+every formatter option at its configured width, so a fresh project passes its own `format:check` without a
+write pass first.
+
+Beside `dev`, `build` and `typecheck`, the deploy target contributes the scripts only it can define, under three
+names that mean the same thing in every app. **`deploy`** builds and ships it, where the platform has one
+command that does the shipping (`cloudflare`, `vercel`). **`preview`** builds and runs the result here — in
+workerd for `cloudflare`, and as a Node build for `vercel` and `aws-lambda`, since neither can run its own
+output locally. **`start`** runs a build that already exists and never makes one, which is what a host's start
+command needs — so only `node` has one, and needs no `preview`: `build` then `start` already is that.
+
+Every command is spelled for the package manager the project got. That includes the runner for the one CLI a
+scaffold does not install, Vercel's: `npx`, `pnpm dlx`, `yarn dlx` or `bunx`. Wrangler is a devDependency
+instead, since `wrangler dev` is how a Cloudflare app previews.
+
+Those scripts are for a laptop, and a platform building from git asks a different question — what to type into
+two fields on a settings page, where a `deploy` script would build twice. So each target also spells out the
+commands its own platform asks for, in the scaffolded README's Deploying section.
 
 `react` and `react-dom` are pinned **exactly**, at the versions the framework is tested against, and those
 pins are generated from rshono's own manifest. That is not tidiness: the RSC runtime reaches into React's
 internals, and an app installed with npm or bun has no workspace overrides to keep a single copy of it.
 
+## Two things worth knowing
+
+**The ESLint preset pins TypeScript 6.** Linting TypeScript with ESLint means `typescript-eslint`, which reads
+the compiler API directly rather than through a stable interface, so its peer range is
+`typescript >=4.8.4 <6.1.0` — below the TypeScript rshono is built and tested against. An app that chooses
+ESLint therefore gets `typescript ~6.0.3`, the newest that range allows: `npm install` would otherwise fail
+outright on the conflict, and forcing past it hands you a linter running against a compiler API it was never
+built for. The framework's declarations compile identically under either version, which is what makes this the
+app's pin and not the framework's — every other preset leaves TypeScript alone. What you trade for type-aware
+rules is a compiler one major behind, and the JavaScript implementation rather than the native one, so
+`typecheck` on a large app is several times slower. When upstream widens the range, the pin in
+`features/quality.ts` is the only thing to delete.
+
+**Tailwind is four packages, a `postcss.config.mjs` and one rule in `rshono.config.ts`.** rshono compiles CSS
+natively and has no PostCSS in it — that is deliberate, and it means an app that wants a plugin chain brings
+its own, through the `rspack` hook. The overlay writes all of it, with a comment saying what to delete to go
+back to plain CSS.
+
 ## Adding an option
 
 Every difference between two scaffolds is a `Feature` — files to overlay, dependencies, scripts,
@@ -69,44 +116,35 @@ edits and no new machinery:
 
 1. A `Feature` in `src/features/` — `templates/<id>` for the files it brings, plus whatever it adds to the
    manifest.
-2. The template directory itself, as **real files**. They are copied over the base, so an overlay replaces
-   a file rather than patching it, and template files stay valid TypeScript that an editor can check.
-   `_name` becomes `.name` on write, because npm strips a literal `.gitignore` out of a published tarball.
+2. The template directory itself, as **real files**. They are copied over the base, so an overlay replaces a
+   file rather than patching it, and template files stay valid TypeScript that an editor can check. `_name`
+   becomes `.name` on write, because npm strips a literal `.gitignore` out of a published tarball.
 3. A prompt in `src/cli.ts`, if it deserves a question of its own — and a flag, which it always does.
 
-`plan(answers)` is pure: answers in, a `Map` of path → contents out, no directory touched. That is what
-makes the whole matrix of options testable in milliseconds (`test/plan.test.mjs`) and `--dry-run` free. It
-is also exported, for a tool that wants to scaffold without the prompts:
+`plan(answers, pm)` is pure: answers in, a `Map` of path → contents out, no directory touched. That is what
+makes the whole matrix of options testable in milliseconds (`test/plan.test.mjs`) and `--dry-run` free. It is
+also exported, for a tool that wants to scaffold without the prompts:
 
 ```ts
 import { plan, writePlan } from '@rshono/create';
 ```
 
-## Two things worth knowing
-
-**The ESLint preset pins TypeScript 6.** Linting TypeScript with ESLint means `typescript-eslint`, which
-reads the compiler API directly rather than through a stable interface, so its peer range is
-`typescript >=4.8.4 <6.1.0` — below the TypeScript rshono is built and tested against. An app that chooses
-ESLint therefore gets `typescript ~6.0.3`, the newest that range allows: `npm install` would otherwise fail
-outright on the conflict, and forcing past it hands you a linter running against a compiler API it was never
-built for. The framework's declarations compile identically under either version, which is what makes this
-the app's pin and not the framework's — every other preset leaves TypeScript alone. What you trade for
-type-aware rules is a compiler one major behind, and the JavaScript implementation rather than the native
-one, so `typecheck` on a large app is several times slower. When upstream widens the range, the pin in
-`features/quality.ts` is the only thing to delete.
-
-**Tailwind is four packages, a `postcss.config.mjs` and one rule in `rshono.config.ts`.** rshono compiles
-CSS natively and has no PostCSS in it — that is deliberate, and it means an app that wants a plugin chain
-brings its own, through the `rspack` hook. The overlay writes all of it, with a comment saying what to
-delete to go back to plain CSS.
-
 ## Development
 
 ```bash
 pnpm --filter @rshono/create build       # codegen, then one bundled dist/cli.mjs with no runtime deps
-pnpm --filter @rshono/create test        # the plan matrix — fast, no I/O
+pnpm --filter @rshono/create test        # builds, then the plan matrix and the CLI — seconds, no installs
 CREATE_RSHONO_E2E=1 pnpm --filter @rshono/create test   # also: pack, install and build real apps
 ```
 
-`@clack/prompts` (MIT) is bundled rather than depended on, so `npm create` downloads one tarball before it
-can ask its first question.
+`plan.test.mjs` is the fast one — the whole matrix of answers in memory, no directory touched.
+`cli.test.mjs` spawns the real bin against temp directories, which is where argument parsing and the refusal
+to overwrite somebody's files are checked. `e2e.test.mjs` is the opt-in one, and the only one that installs
+anything.
+
+`src/generated/framework.ts` — the rshono version, the Node range, the dependency pins and the deploy target
+list — is written by `scripts/codegen.mjs` from `packages/core`, so `pnpm --filter @rshono/create codegen` is
+what picks up a change there.
+
+`@clack/prompts` (MIT) is bundled rather than depended on, so `npx @rshono/create` downloads one tarball
+before it can ask its first question.

package/bin/create-rshono.mjs

@@ -3,7 +3,8 @@
 // parse and run on whatever Node the user happens to have. The CLI itself is a bundle — its imports
 // are evaluated before any statement in it, so a version check *inside* it would be too late to
 // produce anything friendlier than a stack trace.
-var MINIMUM = [22, 1, 0];
+// Kept in step with `engines.node` in @rshono/core's manifest, which is what a scaffolded app pins.
+var MINIMUM = [22, 18, 0];
 
 var current = process.versions.node.split('.').map(Number);
 var older = false;
@@ -20,8 +21,9 @@ if (older) {
       ' or newer — you are on ' +
       process.versions.node +
       '.\n' +
-      'rshono itself requires it too (worker threads, process.loadEnvFile, Promise.withResolvers),\n' +
-      'so scaffolding on this version would produce an app that cannot start.\n',
+      'rshono itself requires it (native TypeScript stripping loads rshono.config.ts, and the dev\n' +
+      'server needs process.loadEnvFile and Promise.withResolvers), so scaffolding on this version\n' +
+      'would produce an app that cannot start.\n',
   );
   process.exit(1);
 }