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

package/README.md

@@ -51,7 +51,7 @@ a target added to rshono appears here with no edit.
 ## What you get
 
 ```
-package.json            scripts, and the exact dependency versions rshono is tested against
+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
@@ -71,6 +71,21 @@ Scaffolding runs the install and nothing else — no formatter, no linter. The t
 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.

package/dist/api.mjs

@@ -77,9 +77,84 @@ __webpack_require__.d(__webpack_exports__, {
     ] : [];
 }
 
+;// CONCATENATED MODULE: ./src/scripts.ts
+// `features/types.js` rather than `features/index.js`: the deploy feature imports `invoke` from here, and
+// going through the barrel would make that a cycle — types.ts imports nothing.
+/**
+ * The scripts every app gets, whatever it targets.
+ *
+ * `start`, `preview` and `deploy` are deliberately not here: each one means something different per
+ * platform, so the deploy target contributes its own. The three names are a contract the targets keep,
+ * and the reason the README can describe an app it was not written for:
+ *
+ * - **`start`** runs a build that already exists and never makes one — what a host's own start command
+ *   calls. Only the target whose build is a server has one.
+ * - **`preview`** builds, then runs the result here — for the targets where that is not the same two
+ *   commands, because otherwise the production build is unanswerable without deploying it.
+ * - **`deploy`** builds, then ships it — where the platform has one command that does the shipping.
+ */ const BASE_SCRIPTS = {
+    dev: 'rshono dev',
+    build: 'rshono build',
+    typecheck: 'tsc --noEmit'
+};
+/**
+ * Every script the app gets, in the order they are written: the base ones, then each feature's, in the order
+ * the features were selected. The manifest and the README's command table are both this, so neither can
+ * document a script the other does not have.
+ */ function buildScripts(features) {
+    const scripts = {
+        ...BASE_SCRIPTS
+    };
+    for (const feature of features)Object.assign(scripts, feature.scripts);
+    return scripts;
+}
+/** The gloss for each base script, in the README's command table. `build` names the target it is for. */ function baseScriptHelp(deploy) {
+    return {
+        dev: 'dev server with HMR, http://localhost:3000',
+        build: `production build for ${deploy}`,
+        typecheck: 'tsc --noEmit'
+    };
+}
+/**
+ * Script names a package manager has a command of its own for. `pnpm deploy` runs pnpm's workspace-deploy
+ * command and never looks at the manifest, so printing it would hand somebody a line that quietly does
+ * something else. The explicit `run` form is what all four managers accept, so those names get it.
+ */ const SHADOWED = new Set([
+    'deploy'
+]);
+/** How to type one of the app's scripts with this package manager — `pnpm dev`, but `npm run dev`. */ function invoke(pm, script) {
+    return `${SHADOWED.has(script) ? `${pm.name} run` : pm.run} ${script}`;
+}
+/**
+ * The README's command table: one line per script, with the command to type and a one-line gloss.
+ *
+ * A script whose feature supplies no `scriptHelp` is left out and covered by the "package.json has the
+ * rest" line — that is how a formatter's `format:check` stays out of a table about running the app.
+ */ function scriptTable(answers, features, pm) {
+    const help = baseScriptHelp(answers.deploy);
+    for (const feature of features)Object.assign(help, feature.scriptHelp);
+    const documented = Object.keys(buildScripts(features)).filter((name)=>help[name]);
+    const width = Math.max(...documented.map((name)=>invoke(pm, name).length));
+    return documented.map((name)=>`${invoke(pm, name).padEnd(width)}  # ${help[name]}`).join('\n');
+}
+/**
+ * The command that gets this app into production, as a sentence — the README's deploy step, and the same
+ * choice the closing summary makes, so the two cannot name different commands.
+ *
+ * Read off the scripts rather than the target, so a target that gains a `deploy` gains the sentence with it.
+ * `start` is the answer where there is no `deploy`: it ships nothing itself, but it is what the host runs.
+ */ function deployStep(features, pm) {
+    const scripts = buildScripts(features);
+    if (scripts.deploy) return `\`${invoke(pm, 'deploy')}\` does the build and the upload in one step.`;
+    if (scripts.start) return `\`${invoke(pm, 'start')}\` runs that build wherever you host it, and never makes one.`;
+    // Every branch names a script the app has, so a target that contributes none of the three still reads true.
+    if (scripts.preview) return `\`${invoke(pm, 'preview')}\` runs the build here, so you can check it first.`;
+    return `\`${invoke(pm, 'build')}\` produces it; getting it there is yours to script.`;
+}
+
 ;// CONCATENATED MODULE: ./src/generated/framework.ts
 // GENERATED by scripts/codegen.mjs from packages/core — do not edit. Run `pnpm --filter @rshono/create codegen`.
-/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.10';
+/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.11';
 /**
  * The Node range rshono itself declares, restated in every scaffolded app's `engines` — so a CI image
  * or a contributor on an older Node hears it from their package manager rather than from a stack trace.
@@ -160,66 +235,128 @@ __webpack_require__.d(__webpack_exports__, {
 
 ;// CONCATENATED MODULE: ./src/features/deploy.ts
 
+
 /**
  * What a deploy target adds beyond the `deploy` line in `rshono.config.ts`, which the template carries.
  *
  * Deliberately thin: the framework arranges its own output for every platform, and `rshono build`
- * writes the one platform config that has to exist (`wrangler.jsonc`, dated the day it ran) if the
- * project has none — a second copy generated here would only go stale. So a target contributes the
- * command that ships the build, the CLI that command needs, the directories to gitignore, and a note
- * for the step no command covers. Several contribute just one of those.
- */ const DEPLOY_FEATURES = {
-    // Where a Node build goes from here is a Dockerfile or a process manager, neither of which this can
-    // guess — so the target contributes only the command that runs what was built.
-    node: {
-        id: 'deploy-node',
-        scripts: {
-            start: 'rshono start'
-        }
-    },
-    cloudflare: {
-        id: 'deploy-cloudflare',
-        devDependencies: {
-            wrangler: TOOL_VERSIONS.wrangler
+ * writes the one platform config that has to exist (`wrangler.jsonc`) if the project has none — a second
+ * copy generated here would only go stale. So a target contributes the commands that run and ship the
+ * build, the CLI they need, the directories to gitignore, and a note for the step no command covers.
+ *
+ * What the three script names promise is documented once, above `BASE_SCRIPTS` in `scripts.ts`. Only `node`
+ * has a `start`, because `rshono start` refuses a bundle built for anywhere else, and it needs no `preview`:
+ * `build` then `start` already is one.
+ *
+ * `pm` is here because two things have to be spelled for the app's package manager — the runner that fetches
+ * the uninstalled Vercel CLI ({@link PackageManager.dlx}), and every command in {@link Feature.platformSetup}.
+ */ function deployFeatures(pm) {
+    const build = invoke(pm, 'build');
+    return {
+        // Where a Node build goes from here is a Dockerfile or a process manager, neither of which this can
+        // guess — so the target contributes only the command that runs what was built.
+        node: {
+            id: 'deploy-node',
+            scripts: {
+                start: 'rshono start'
+            },
+            scriptHelp: {
+                start: 'run the build that exists — what your host calls'
+            },
+            platformSetup: [
+                'The two commands a host asks for:',
+                '',
+                `- **Build** — \`${pm.name} install && ${build}\``,
+                `- **Start** — \`${invoke(pm, 'start')}\``,
+                '',
+                `In a Dockerfile, the same pair: \`RUN ${build}\`, then \`CMD ["${pm.name}", "start"]\`.`
+            ].join('\n')
         },
-        // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each
-        // one merely picks the platform binary out of the optional dependency that already carries it, so
-        // neither needs to run — `workerd --version` and `esbuild --version` both answer without it.
-        allowBuilds: {
-            esbuild: false,
-            workerd: false
+        cloudflare: {
+            id: 'deploy-cloudflare',
+            devDependencies: {
+                wrangler: TOOL_VERSIONS.wrangler
+            },
+            // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each
+            // one merely picks the platform binary out of the optional dependency that already carries it, so
+            // neither needs to run — `workerd --version` and `esbuild --version` both answer without it.
+            allowBuilds: {
+                esbuild: false,
+                workerd: false
+            },
+            // `wrangler dev` is the one preview that runs the code in the runtime it will actually run in:
+            // workerd, not Node, serving the assets the build assembled. Both scripts read the wrangler.jsonc the
+            // build wrote, so nothing here has to know where the bundle or the assets went.
+            scripts: {
+                preview: 'rshono build && wrangler dev',
+                deploy: 'rshono build && wrangler deploy'
+            },
+            scriptHelp: {
+                preview: 'build, then run it in workerd — port 8787',
+                deploy: 'build, then ship it to Cloudflare'
+            },
+            gitignore: [
+                '.wrangler/'
+            ],
+            notes: [
+                'The first build writes wrangler.jsonc — yours to edit after that.'
+            ],
+            platformSetup: [
+                `Building from a git repo instead: set Workers Builds' **Build command** to \`${build}\`.`,
+                'Its deploy command already defaults to `npx wrangler deploy`, and it installs dependencies itself.'
+            ].join('\n')
         },
-        scripts: {
-            deploy: 'rshono build && wrangler deploy'
+        vercel: {
+            id: 'deploy-vercel',
+            // `--prod` because the script is called `deploy`: without it the CLI uploads to a throwaway preview
+            // URL, which is a useful thing to have but not what the word means. The local `preview` is a Node
+            // build run here — the platform has no way to run its own prebuilt output on your machine.
+            scripts: {
+                preview: 'rshono build --deploy node && rshono start',
+                deploy: `rshono build && ${pm.dlx} vercel deploy --prebuilt --prod`
+            },
+            scriptHelp: {
+                preview: 'build for Node and run that here',
+                deploy: 'build, then upload it to production'
+            },
+            gitignore: [
+                '.vercel/'
+            ],
+            notes: [
+                '--prebuilt uploads what rshono build assembled; the platform must not rebuild it.',
+                'Drop --prod from the deploy script for a preview URL instead.'
+            ],
+            platformSetup: [
+                `Deploying from CI instead: the same \`${invoke(pm, 'deploy')}\`, with \`VERCEL_ORG_ID\`, \`VERCEL_PROJECT_ID\``,
+                'and a CLI token in the environment.',
+                '',
+                `If you let Vercel build the repo itself, set **Framework Preset** to Other — \`hono\` is otherwise`,
+                `detected as the Hono preset — and **Build Command** to \`${build}\`.`
+            ].join('\n')
         },
-        gitignore: [
-            '.wrangler/'
-        ],
-        notes: [
-            'The first build writes wrangler.jsonc — yours to edit after that.'
-        ]
-    },
-    vercel: {
-        id: 'deploy-vercel',
-        scripts: {
-            deploy: 'rshono build && vercel deploy --prebuilt'
-        },
-        gitignore: [
-            '.vercel/'
-        ],
-        notes: [
-            '--prebuilt uploads what rshono build assembled; the platform must not rebuild it.'
-        ]
-    },
-    'aws-lambda': {
-        id: 'deploy-aws-lambda',
-        notes: [
-            'Use a Function URL in RESPONSE_STREAM mode — a buffered invoke mode drops the streaming.'
-        ]
-    }
-};
-function deployFeature(target) {
-    return DEPLOY_FEATURES[target];
+        'aws-lambda': {
+            id: 'deploy-aws-lambda',
+            // No CLI to wrap, and no upload this could guess at. `preview` still applies — the bundle is a Node
+            // handler, so it runs here.
+            scripts: {
+                preview: 'rshono build --deploy node && rshono start'
+            },
+            scriptHelp: {
+                preview: 'build for Node and run that here'
+            },
+            notes: [
+                'Use a Function URL in RESPONSE_STREAM mode — a buffered invoke mode drops the streaming.'
+            ],
+            platformSetup: [
+                `There is no settings page here; the upload is yours to script. A job needs \`${pm.name} install && ${build}\`,`,
+                'then the function package: `dist/`, plus `node_modules` for any dependency of your own, which the server',
+                'bundle leaves external.'
+            ].join('\n')
+        }
+    };
+}
+function deployFeature(target, pm) {
+    return deployFeatures(pm)[target];
 }
 
 ;// CONCATENATED MODULE: ./src/features/quality.ts
@@ -365,9 +502,12 @@ function stylingFeature(styling) {
  * The features a set of answers selects, in application order — so an overlay listed later wins a file
  * both of them ship. Deduplicated by `id`, which is what lets one feature answer two questions (Biome
  * is both the formatter and the linter) without contributing twice.
- */ function selectFeatures(answers) {
+ *
+ * `pm` reaches the deploy target because one script has to name the runner that fetches an uninstalled
+ * CLI; nothing else here depends on which package manager the app is for.
+ */ function selectFeatures(answers, pm) {
     const selected = [
-        deployFeature(answers.deploy),
+        deployFeature(answers.deploy, pm),
         stylingFeature(answers.styling),
         formatterFeature(answers.formatter),
         linterFeature(answers.linter),
@@ -474,15 +614,7 @@ const QUALITY_PRESETS = [
 
 ;// CONCATENATED MODULE: ./src/pkg.ts
 
-/**
- * The scripts every app gets. `start` is not among them, because it means something different per
- * platform: `node` is the one target that runs the build itself, so it contributes its own, and a
- * platform target contributes a `deploy` instead, where its platform has one command to give.
- */ const BASE_SCRIPTS = {
-    dev: 'rshono dev',
-    build: 'rshono build',
-    typecheck: 'tsc --noEmit'
-};
+
 /** Field order in the emitted file — the conventional reading order, and stable so snapshots are too. */ const FIELD_ORDER = [
     'name',
     'version',
@@ -524,13 +656,9 @@ function sorted(record) {
 /**
  * Assembles `package.json` from the answers and whatever the selected features contribute.
  *
- * Dependencies are sorted by name and scripts are left in contribution order (the base ones, then each
- * feature's, in the order features were selected) — so two runs with the same answers produce byte-
- * identical output, which is what makes the generated manifest snapshot-testable.
+ * Dependencies are sorted by name and scripts keep the order {@link buildScripts} gives them — so two runs
+ * with the same answers produce byte-identical output, which is what makes the manifest snapshot-testable.
  */ function buildPackageJson(answers, features, pm) {
-    const scripts = {
-        ...BASE_SCRIPTS
-    };
     const dependencies = {
         '@rshono/core': RSHONO_RANGE,
         hono: FRAMEWORK_DEPS.hono,
@@ -543,7 +671,6 @@ function sorted(record) {
         typescript: FRAMEWORK_DEPS.typescript
     };
     for (const feature of features){
-        Object.assign(scripts, feature.scripts);
         Object.assign(dependencies, feature.dependencies);
         Object.assign(devDependencies, feature.devDependencies);
     }
@@ -556,7 +683,7 @@ function sorted(record) {
         engines: {
             node: NODE_ENGINE
         },
-        scripts,
+        scripts: buildScripts(features),
         dependencies: sorted(dependencies),
         devDependencies: sorted(devDependencies)
     };
@@ -577,12 +704,15 @@ function sorted(record) {
  * markdown `__NAME__` *is* strong emphasis — Prettier rewrites it to `**NAME**` and the token stops
  * matching. `{{…}}` means nothing to any format these templates are written in.
  */ const TOKEN_PATTERN = /\{\{[A-Z][A-Z\d_]*\}\}/g;
-function tokensFor(answers, pm) {
+function tokensFor(answers, features, pm) {
     return {
         '{{PROJECT_NAME}}': answers.packageName,
         '{{DEPLOY_TARGET}}': answers.deploy,
-        '{{DEPLOY_HINT}}': deployHint(answers.deploy),
-        '{{PM_RUN}}': pm.run
+        // Derived from the features rather than the answers, because all three are about the scripts the app
+        // actually got: its command table, the one command that ships it, and what its platform asks for.
+        '{{SCRIPT_TABLE}}': scriptTable(answers, features, pm),
+        '{{DEPLOY_STEP}}': deployStep(features, pm),
+        '{{PLATFORM_SETUP}}': features.map((feature)=>feature.platformSetup ?? '').join('')
     };
 }
 /**
@@ -645,8 +775,8 @@ function readTemplateDir(dir) {
  * decisions and the I/O are separated so the whole matrix of answers can be asserted on in a test, and
  * so `--dry-run` is the same code path minus the last step.
  */ function plan_plan(answers, pm) {
-    const features = selectFeatures(answers);
-    const tokens = tokensFor(answers, pm);
+    const features = selectFeatures(answers, pm);
+    const tokens = tokensFor(answers, features, pm);
     const raw = readTemplateDir(join(TEMPLATES_DIR, 'base'));
     for (const feature of features){
         for (const overlay of feature.overlays ?? []){
@@ -698,6 +828,12 @@ const RUN = {
     yarn: 'yarn',
     bun: 'bun'
 };
+const DLX = {
+    npm: 'npx',
+    pnpm: 'pnpm dlx',
+    yarn: 'yarn dlx',
+    bun: 'bunx'
+};
 function isKnown(name) {
     return PACKAGE_MANAGERS.includes(name);
 }
@@ -706,7 +842,8 @@ function packageManager(name, version) {
         name,
         version,
         install: INSTALL[name],
-        run: RUN[name]
+        run: RUN[name],
+        dlx: DLX[name]
     };
 }
 /**

package/dist/cli.mjs

@@ -2943,7 +2943,7 @@ function hasGit(cwd) {
 
 ;// CONCATENATED MODULE: ./src/generated/framework.ts
 // GENERATED by scripts/codegen.mjs from packages/core — do not edit. Run `pnpm --filter @rshono/create codegen`.
-/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.10';
+/** The framework release a scaffolded app is pinned to: this package and rshono ship together. */ const RSHONO_VERSION = '1.0.0-rc.11';
 /**
  * The Node range rshono itself declares, restated in every scaffolded app's `engines` — so a CI image
  * or a contributor on an older Node hears it from their package manager rather than from a stack trace.
@@ -3091,6 +3091,81 @@ const QUALITY_PRESETS = [
     ] : [];
 }
 
+;// CONCATENATED MODULE: ./src/scripts.ts
+// `features/types.js` rather than `features/index.js`: the deploy feature imports `invoke` from here, and
+// going through the barrel would make that a cycle — types.ts imports nothing.
+/**
+ * The scripts every app gets, whatever it targets.
+ *
+ * `start`, `preview` and `deploy` are deliberately not here: each one means something different per
+ * platform, so the deploy target contributes its own. The three names are a contract the targets keep,
+ * and the reason the README can describe an app it was not written for:
+ *
+ * - **`start`** runs a build that already exists and never makes one — what a host's own start command
+ *   calls. Only the target whose build is a server has one.
+ * - **`preview`** builds, then runs the result here — for the targets where that is not the same two
+ *   commands, because otherwise the production build is unanswerable without deploying it.
+ * - **`deploy`** builds, then ships it — where the platform has one command that does the shipping.
+ */ const BASE_SCRIPTS = {
+    dev: 'rshono dev',
+    build: 'rshono build',
+    typecheck: 'tsc --noEmit'
+};
+/**
+ * Every script the app gets, in the order they are written: the base ones, then each feature's, in the order
+ * the features were selected. The manifest and the README's command table are both this, so neither can
+ * document a script the other does not have.
+ */ function buildScripts(features) {
+    const scripts = {
+        ...BASE_SCRIPTS
+    };
+    for (const feature of features)Object.assign(scripts, feature.scripts);
+    return scripts;
+}
+/** The gloss for each base script, in the README's command table. `build` names the target it is for. */ function baseScriptHelp(deploy) {
+    return {
+        dev: 'dev server with HMR, http://localhost:3000',
+        build: `production build for ${deploy}`,
+        typecheck: 'tsc --noEmit'
+    };
+}
+/**
+ * Script names a package manager has a command of its own for. `pnpm deploy` runs pnpm's workspace-deploy
+ * command and never looks at the manifest, so printing it would hand somebody a line that quietly does
+ * something else. The explicit `run` form is what all four managers accept, so those names get it.
+ */ const SHADOWED = new Set([
+    'deploy'
+]);
+/** How to type one of the app's scripts with this package manager — `pnpm dev`, but `npm run dev`. */ function invoke(pm, script) {
+    return `${SHADOWED.has(script) ? `${pm.name} run` : pm.run} ${script}`;
+}
+/**
+ * The README's command table: one line per script, with the command to type and a one-line gloss.
+ *
+ * A script whose feature supplies no `scriptHelp` is left out and covered by the "package.json has the
+ * rest" line — that is how a formatter's `format:check` stays out of a table about running the app.
+ */ function scriptTable(answers, features, pm) {
+    const help = baseScriptHelp(answers.deploy);
+    for (const feature of features)Object.assign(help, feature.scriptHelp);
+    const documented = Object.keys(buildScripts(features)).filter((name)=>help[name]);
+    const width = Math.max(...documented.map((name)=>invoke(pm, name).length));
+    return documented.map((name)=>`${invoke(pm, name).padEnd(width)}  # ${help[name]}`).join('\n');
+}
+/**
+ * The command that gets this app into production, as a sentence — the README's deploy step, and the same
+ * choice the closing summary makes, so the two cannot name different commands.
+ *
+ * Read off the scripts rather than the target, so a target that gains a `deploy` gains the sentence with it.
+ * `start` is the answer where there is no `deploy`: it ships nothing itself, but it is what the host runs.
+ */ function deployStep(features, pm) {
+    const scripts = buildScripts(features);
+    if (scripts.deploy) return `\`${invoke(pm, 'deploy')}\` does the build and the upload in one step.`;
+    if (scripts.start) return `\`${invoke(pm, 'start')}\` runs that build wherever you host it, and never makes one.`;
+    // Every branch names a script the app has, so a target that contributes none of the three still reads true.
+    if (scripts.preview) return `\`${invoke(pm, 'preview')}\` runs the build here, so you can check it first.`;
+    return `\`${invoke(pm, 'build')}\` produces it; getting it there is yours to script.`;
+}
+
 ;// CONCATENATED MODULE: ./src/versions.ts
 
 /** Passed straight through, so everything generated from the framework reaches the rest of the package here. */ 
@@ -3136,66 +3211,128 @@ const QUALITY_PRESETS = [
 
 ;// CONCATENATED MODULE: ./src/features/deploy.ts
 
+
 /**
  * What a deploy target adds beyond the `deploy` line in `rshono.config.ts`, which the template carries.
  *
  * Deliberately thin: the framework arranges its own output for every platform, and `rshono build`
- * writes the one platform config that has to exist (`wrangler.jsonc`, dated the day it ran) if the
- * project has none — a second copy generated here would only go stale. So a target contributes the
- * command that ships the build, the CLI that command needs, the directories to gitignore, and a note
- * for the step no command covers. Several contribute just one of those.
- */ const DEPLOY_FEATURES = {
-    // Where a Node build goes from here is a Dockerfile or a process manager, neither of which this can
-    // guess — so the target contributes only the command that runs what was built.
-    node: {
-        id: 'deploy-node',
-        scripts: {
-            start: 'rshono start'
-        }
-    },
-    cloudflare: {
-        id: 'deploy-cloudflare',
-        devDependencies: {
-            wrangler: TOOL_VERSIONS.wrangler
-        },
-        // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each
-        // one merely picks the platform binary out of the optional dependency that already carries it, so
-        // neither needs to run — `workerd --version` and `esbuild --version` both answer without it.
-        allowBuilds: {
-            esbuild: false,
-            workerd: false
+ * writes the one platform config that has to exist (`wrangler.jsonc`) if the project has none — a second
+ * copy generated here would only go stale. So a target contributes the commands that run and ship the
+ * build, the CLI they need, the directories to gitignore, and a note for the step no command covers.
+ *
+ * What the three script names promise is documented once, above `BASE_SCRIPTS` in `scripts.ts`. Only `node`
+ * has a `start`, because `rshono start` refuses a bundle built for anywhere else, and it needs no `preview`:
+ * `build` then `start` already is one.
+ *
+ * `pm` is here because two things have to be spelled for the app's package manager — the runner that fetches
+ * the uninstalled Vercel CLI ({@link PackageManager.dlx}), and every command in {@link Feature.platformSetup}.
+ */ function deployFeatures(pm) {
+    const build = invoke(pm, 'build');
+    return {
+        // Where a Node build goes from here is a Dockerfile or a process manager, neither of which this can
+        // guess — so the target contributes only the command that runs what was built.
+        node: {
+            id: 'deploy-node',
+            scripts: {
+                start: 'rshono start'
+            },
+            scriptHelp: {
+                start: 'run the build that exists — what your host calls'
+            },
+            platformSetup: [
+                'The two commands a host asks for:',
+                '',
+                `- **Build** — \`${pm.name} install && ${build}\``,
+                `- **Start** — \`${invoke(pm, 'start')}\``,
+                '',
+                `In a Dockerfile, the same pair: \`RUN ${build}\`, then \`CMD ["${pm.name}", "start"]\`.`
+            ].join('\n')
         },
-        scripts: {
-            deploy: 'rshono build && wrangler deploy'
+        cloudflare: {
+            id: 'deploy-cloudflare',
+            devDependencies: {
+                wrangler: TOOL_VERSIONS.wrangler
+            },
+            // The only two install scripts a scaffolded app can end up with, and wrangler brings both. Each
+            // one merely picks the platform binary out of the optional dependency that already carries it, so
+            // neither needs to run — `workerd --version` and `esbuild --version` both answer without it.
+            allowBuilds: {
+                esbuild: false,
+                workerd: false
+            },
+            // `wrangler dev` is the one preview that runs the code in the runtime it will actually run in:
+            // workerd, not Node, serving the assets the build assembled. Both scripts read the wrangler.jsonc the
+            // build wrote, so nothing here has to know where the bundle or the assets went.
+            scripts: {
+                preview: 'rshono build && wrangler dev',
+                deploy: 'rshono build && wrangler deploy'
+            },
+            scriptHelp: {
+                preview: 'build, then run it in workerd — port 8787',
+                deploy: 'build, then ship it to Cloudflare'
+            },
+            gitignore: [
+                '.wrangler/'
+            ],
+            notes: [
+                'The first build writes wrangler.jsonc — yours to edit after that.'
+            ],
+            platformSetup: [
+                `Building from a git repo instead: set Workers Builds' **Build command** to \`${build}\`.`,
+                'Its deploy command already defaults to `npx wrangler deploy`, and it installs dependencies itself.'
+            ].join('\n')
         },
-        gitignore: [
-            '.wrangler/'
-        ],
-        notes: [
-            'The first build writes wrangler.jsonc — yours to edit after that.'
-        ]
-    },
-    vercel: {
-        id: 'deploy-vercel',
-        scripts: {
-            deploy: 'rshono build && vercel deploy --prebuilt'
+        vercel: {
+            id: 'deploy-vercel',
+            // `--prod` because the script is called `deploy`: without it the CLI uploads to a throwaway preview
+            // URL, which is a useful thing to have but not what the word means. The local `preview` is a Node
+            // build run here — the platform has no way to run its own prebuilt output on your machine.
+            scripts: {
+                preview: 'rshono build --deploy node && rshono start',
+                deploy: `rshono build && ${pm.dlx} vercel deploy --prebuilt --prod`
+            },
+            scriptHelp: {
+                preview: 'build for Node and run that here',
+                deploy: 'build, then upload it to production'
+            },
+            gitignore: [
+                '.vercel/'
+            ],
+            notes: [
+                '--prebuilt uploads what rshono build assembled; the platform must not rebuild it.',
+                'Drop --prod from the deploy script for a preview URL instead.'
+            ],
+            platformSetup: [
+                `Deploying from CI instead: the same \`${invoke(pm, 'deploy')}\`, with \`VERCEL_ORG_ID\`, \`VERCEL_PROJECT_ID\``,
+                'and a CLI token in the environment.',
+                '',
+                `If you let Vercel build the repo itself, set **Framework Preset** to Other — \`hono\` is otherwise`,
+                `detected as the Hono preset — and **Build Command** to \`${build}\`.`
+            ].join('\n')
         },
-        gitignore: [
-            '.vercel/'
-        ],
-        notes: [
-            '--prebuilt uploads what rshono build assembled; the platform must not rebuild it.'
-        ]
-    },
-    'aws-lambda': {
-        id: 'deploy-aws-lambda',
-        notes: [
-            'Use a Function URL in RESPONSE_STREAM mode — a buffered invoke mode drops the streaming.'
-        ]
-    }
-};
-function deployFeature(target) {
-    return DEPLOY_FEATURES[target];
+        'aws-lambda': {
+            id: 'deploy-aws-lambda',
+            // No CLI to wrap, and no upload this could guess at. `preview` still applies — the bundle is a Node
+            // handler, so it runs here.
+            scripts: {
+                preview: 'rshono build --deploy node && rshono start'
+            },
+            scriptHelp: {
+                preview: 'build for Node and run that here'
+            },
+            notes: [
+                'Use a Function URL in RESPONSE_STREAM mode — a buffered invoke mode drops the streaming.'
+            ],
+            platformSetup: [
+                `There is no settings page here; the upload is yours to script. A job needs \`${pm.name} install && ${build}\`,`,
+                'then the function package: `dist/`, plus `node_modules` for any dependency of your own, which the server',
+                'bundle leaves external.'
+            ].join('\n')
+        }
+    };
+}
+function deployFeature(target, pm) {
+    return deployFeatures(pm)[target];
 }
 
 ;// CONCATENATED MODULE: ./src/features/quality.ts
@@ -3341,9 +3478,12 @@ function stylingFeature(styling) {
  * The features a set of answers selects, in application order — so an overlay listed later wins a file
  * both of them ship. Deduplicated by `id`, which is what lets one feature answer two questions (Biome
  * is both the formatter and the linter) without contributing twice.
- */ function selectFeatures(answers) {
+ *
+ * `pm` reaches the deploy target because one script has to name the runner that fetches an uninstalled
+ * CLI; nothing else here depends on which package manager the app is for.
+ */ function selectFeatures(answers, pm) {
     const selected = [
-        deployFeature(answers.deploy),
+        deployFeature(answers.deploy, pm),
         stylingFeature(answers.styling),
         formatterFeature(answers.formatter),
         linterFeature(answers.linter),
@@ -3361,15 +3501,7 @@ function stylingFeature(styling) {
 
 ;// CONCATENATED MODULE: ./src/pkg.ts
 
-/**
- * The scripts every app gets. `start` is not among them, because it means something different per
- * platform: `node` is the one target that runs the build itself, so it contributes its own, and a
- * platform target contributes a `deploy` instead, where its platform has one command to give.
- */ const BASE_SCRIPTS = {
-    dev: 'rshono dev',
-    build: 'rshono build',
-    typecheck: 'tsc --noEmit'
-};
+
 /** Field order in the emitted file — the conventional reading order, and stable so snapshots are too. */ const FIELD_ORDER = [
     'name',
     'version',
@@ -3411,13 +3543,9 @@ function sorted(record) {
 /**
  * Assembles `package.json` from the answers and whatever the selected features contribute.
  *
- * Dependencies are sorted by name and scripts are left in contribution order (the base ones, then each
- * feature's, in the order features were selected) — so two runs with the same answers produce byte-
- * identical output, which is what makes the generated manifest snapshot-testable.
+ * Dependencies are sorted by name and scripts keep the order {@link buildScripts} gives them — so two runs
+ * with the same answers produce byte-identical output, which is what makes the manifest snapshot-testable.
  */ function buildPackageJson(answers, features, pm) {
-    const scripts = {
-        ...BASE_SCRIPTS
-    };
     const dependencies = {
         '@rshono/core': RSHONO_RANGE,
         hono: FRAMEWORK_DEPS.hono,
@@ -3430,7 +3558,6 @@ function sorted(record) {
         typescript: FRAMEWORK_DEPS.typescript
     };
     for (const feature of features){
-        Object.assign(scripts, feature.scripts);
         Object.assign(dependencies, feature.dependencies);
         Object.assign(devDependencies, feature.devDependencies);
     }
@@ -3443,7 +3570,7 @@ function sorted(record) {
         engines: {
             node: NODE_ENGINE
         },
-        scripts,
+        scripts: buildScripts(features),
         dependencies: sorted(dependencies),
         devDependencies: sorted(devDependencies)
     };
@@ -3464,12 +3591,15 @@ function sorted(record) {
  * markdown `__NAME__` *is* strong emphasis — Prettier rewrites it to `**NAME**` and the token stops
  * matching. `{{…}}` means nothing to any format these templates are written in.
  */ const TOKEN_PATTERN = /\{\{[A-Z][A-Z\d_]*\}\}/g;
-function tokensFor(answers, pm) {
+function tokensFor(answers, features, pm) {
     return {
         '{{PROJECT_NAME}}': answers.packageName,
         '{{DEPLOY_TARGET}}': answers.deploy,
-        '{{DEPLOY_HINT}}': deployHint(answers.deploy),
-        '{{PM_RUN}}': pm.run
+        // Derived from the features rather than the answers, because all three are about the scripts the app
+        // actually got: its command table, the one command that ships it, and what its platform asks for.
+        '{{SCRIPT_TABLE}}': scriptTable(answers, features, pm),
+        '{{DEPLOY_STEP}}': deployStep(features, pm),
+        '{{PLATFORM_SETUP}}': features.map((feature)=>feature.platformSetup ?? '').join('')
     };
 }
 /**
@@ -3532,8 +3662,8 @@ function readTemplateDir(dir) {
  * decisions and the I/O are separated so the whole matrix of answers can be asserted on in a test, and
  * so `--dry-run` is the same code path minus the last step.
  */ function plan_plan(answers, pm) {
-    const features = selectFeatures(answers);
-    const tokens = tokensFor(answers, pm);
+    const features = selectFeatures(answers, pm);
+    const tokens = tokensFor(answers, features, pm);
     const raw = readTemplateDir(external_node_path_join(TEMPLATES_DIR, 'base'));
     for (const feature of features){
         for (const overlay of feature.overlays ?? []){
@@ -3583,6 +3713,12 @@ const RUN = {
     yarn: 'yarn',
     bun: 'bun'
 };
+const DLX = {
+    npm: 'npx',
+    pnpm: 'pnpm dlx',
+    yarn: 'yarn dlx',
+    bun: 'bunx'
+};
 function isKnown(name) {
     return PACKAGE_MANAGERS.includes(name);
 }
@@ -3591,7 +3727,8 @@ function packageManager(name, version) {
         name,
         version,
         install: INSTALL[name],
-        run: RUN[name]
+        run: RUN[name],
+        dlx: DLX[name]
     };
 }
 /**
@@ -3625,6 +3762,17 @@ function run(pm, args, cwd) {
 ;// CONCATENATED MODULE: ./src/ui.ts
 
 
+
+/**
+ * The two halves of the closing line, in the words of the app's own scripts: what produces something
+ * shippable, and where it goes from there. The target with no command to give keeps the framework's hint,
+ * which is a sentence about the platform rather than something to type.
+ */ function productionSteps(answers, plan, pm) {
+    const scripts = buildScripts(plan.features);
+    const check = scripts.preview ? `${invoke(pm, 'preview')} to run the production build` : `${pm.run} build`;
+    const ship = scripts.deploy ? `${invoke(pm, 'deploy')} to ship it` : scripts.start ? `${invoke(pm, 'start')} on the host that runs it` : deployHint(answers.deploy);
+    return `${check}, and ${ship}`;
+}
 /**
  * What to do next, in the order to do it — the last thing the user reads, and for most people the only
  * documentation they will read today. `installed` decides whether the install step is still theirs.
@@ -3636,7 +3784,7 @@ function run(pm, args, cwd) {
     const lines = [
         steps.join('\n')
     ];
-    lines.push(`\nThen ${pm.run} build, and ${deployHint(answers.deploy)}.`);
+    lines.push(`\nThen ${productionSteps(answers, plan, pm)}.`);
     if (plan.notes.length > 0) lines.push(`\n${plan.notes.join('\n')}`);
     return lines.join('\n');
 }
@@ -3821,7 +3969,7 @@ function fail(message) {
 async function main() {
     const { values, positionals } = parse();
     if (values.help) return console.log(HELP);
-    if (values.version) return console.log("1.0.0-rc.10");
+    if (values.version) return console.log("1.0.0-rc.11");
     // A pipe, a CI job or an agent gets the defaults rather than a prompt nothing can answer. Both
     // streams have to be a terminal: the prompts draw on stdout but *read from stdin*, so
     // `echo | npx @rshono/create` would otherwise ask a question with nothing behind the keyboard.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rshono/create",
-  "version": "1.0.0-rc.10",
+  "version": "1.0.0-rc.11",
   "description": "Scaffold a new rshono app — Hono + Rspack + React Server Components",
   "author": "Lasse <lasse@lassetange.com> (https://www.lassetange.com)",
   "license": "ISC",
@@ -46,7 +46,7 @@
     "@rspack/core": "2.1.7",
     "@types/node": "^26.1.1",
     "typescript": "^7.0.2",
-    "@rshono/core": "1.0.0-rc.10"
+    "@rshono/core": "1.0.0-rc.11"
   },
   "scripts": {
     "build": "node scripts/codegen.mjs && node scripts/build.mjs",

package/templates/base/README.md

@@ -1,9 +1,7 @@
 # {{PROJECT_NAME}}
 
 ```bash
-{{PM_RUN}} dev        # dev server with HMR, http://localhost:3000
-{{PM_RUN}} build      # production build for {{DEPLOY_TARGET}}
-{{PM_RUN}} typecheck  # tsc --noEmit
+{{SCRIPT_TABLE}}
 ```
 
 `package.json` has the rest, including whatever your formatter and linter added.
@@ -31,8 +29,12 @@ compiles to `undefined` rather than shipping. `src/components/layout.tsx` reads
 
 ## Deploying
 
-This app is built for `{{DEPLOY_TARGET}}`: after `{{PM_RUN}} build`, {{DEPLOY_HINT}}.
+This app is built for `{{DEPLOY_TARGET}}`. {{DEPLOY_STEP}}
+
+{{PLATFORM_SETUP}}
 
 Change `deploy` in `rshono.config.ts` to target somewhere else, or build for one place without editing the
 file: `rshono build --deploy vercel`, or `RSHONO_DEPLOY=vercel` in CI. `dev` always runs the Node dev
 server, whatever the target — it is a property of the build, not of developing.
+
+Every target, and what each one needs: <https://www.rshono.com/docs/deployment>