create-rsc-kit 0.7.1 → 0.7.2

package/README.md

@@ -3,7 +3,7 @@
 Scaffold a React Server Components app that builds and runs before you edit it.
 
 ```sh
-bun create rsc-kit my-app
+bun create rsc-kit@latest my-app
 ```
 
 Asks which server (Bun, Hono, Elysia or `node:http`), whether you want the React
@@ -11,7 +11,7 @@ Compiler, and whether to include Tailwind. Every answer has a flag, so it runs
 unattended too:
 
 ```sh
-bun create rsc-kit my-app --host=hono --compiler=oxc --tailwind
+bun create rsc-kit@latest my-app --host=bun --compiler=oxc --tailwind
 ```
 
 The point is not the typing it saves. Several things in this setup fail by

package/dist/index.js

@@ -5,38 +5,18 @@
 // several things in it that are invisible when wrong: NODE_ENV on the build,
 // @source for Tailwind, the ambient declaration for the generated engine
 // bundle. Each of those fails by producing a page that looks nearly right.
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { argv, exit, stdout } from 'node:process';
 import { DEFAULT_COMPILER, HELP, HOSTS, publishedCore, assertInsideCwd, assertUsableName, defaultCore, parseArgs, } from './options.js';
 import { Prompter, bold, cyan, dim } from './prompt.js';
+import { checkForNewer, notifyIfStale, selfVersion } from './stale.js';
 import * as t from './templates.js';
 // Same treatment as a refusal from write(): a bad flag is a decision this tool
 // made, and it happens before the try/catch below because the flags are what
 // everything else is built from.
-/**
- * This package's own version, printed so a stale one is visible.
- *
- * `bun create rsc-kit` is `bunx create-rsc-kit`, and bunx caches its
- * resolution of `latest` under that key — so a machine that ran it once keeps
- * scaffolding from whatever it downloaded then, however many releases ago.
- * There is nothing this package can do about that, but there is something it
- * can do about the symptom, which was a prompt offering hosts that had been
- * removed two releases earlier and no way to tell why.
- *
- * Read rather than baked in: the version is only written at publish time.
- */
-function selfVersion() {
-    try {
-        const path = join(dirname(fileURLToPath(import.meta.url)), '../package.json');
-        return `v${JSON.parse(readFileSync(path, 'utf-8')).version}`;
-    }
-    catch {
-        return '';
-    }
-}
 const flags = (() => {
     try {
         return parseArgs(argv.slice(2));
@@ -54,7 +34,7 @@ const unattended = flags.yes === true || flags.host !== undefined;
 // Resolved once: it walks up from this file looking for the sibling package.
 const core = flags.core ?? defaultCore(dirname(fileURLToPath(import.meta.url)));
 // Started before the first question and never awaited here — see notifyIfStale.
-const staleCheck = checkForNewer();
+const staleCheck = checkForNewer('create-rsc-kit', selfVersion(import.meta.url));
 const options = await collect();
 try {
     write(options);
@@ -81,7 +61,7 @@ if (options.install) {
     }
 }
 report(options);
-await notifyIfStale();
+await notifyIfStale(staleCheck, 'bun create rsc-kit@latest');
 // ── ─────────────────────────────────────────────────────────────────────────
 /** Declared, not assigned: collect() runs at module top level, above this. */
 function basename(path) {
@@ -112,7 +92,7 @@ async function collect() {
             HELP);
         exit(1);
     }
-    stdout.write(`\n${bold('Create an RSC app')} ${dim(selfVersion())}\n\n`);
+    stdout.write(`\n${bold('Create an RSC app')} ${dim(`v${selfVersion(import.meta.url)}`)}\n\n`);
     const p = new Prompter();
     try {
         const dir = flags.dir ?? (await p.text('Directory', 'my-app'));
@@ -211,61 +191,6 @@ function report(o) {
         stdout.write(`  ${cyan(step)}\n`);
     stdout.write(`\n${dim('Pages live in src/app. Where it deploys is the Nitro preset in vite.config.ts.')}\n\n`);
 }
-/**
- * Ask the registry what `latest` is, so a stale copy can say so.
- *
- * Printing the version alone does not help: nobody knows 0.5.0 is two behind
- * unless something tells them.
- *
- * `bun create rsc-kit` is `bunx create-rsc-kit`, and bunx reuses what it
- * downloaded the first time — a machine that ran this once keeps scaffolding
- * from that copy however many releases later. Writing the tag out is what
- * makes it revalidate. Measured against a 0.6.0 planted in the cache:
- *
- *   bun create rsc-kit             stale
- *   bunx create-rsc-kit            stale
- *   bun create rsc-kit@latest      fresh
- *   bunx create-rsc-kit@latest     fresh
- *   npx create-rsc-kit@latest      fresh
- *
- * So the escape is one word, and this is what tells someone to use it — the
- * form without it is the one every set of install instructions writes.
- *
- * create-next-app does this with the `update-check` package. Not here: this
- * package is installed by bunx before it can ask anything, so a dependency is
- * latency every user waits through — the same reason the prompts are written
- * against readline. It is one request.
- *
- * Started before the first prompt and read after the last, so it costs nothing
- * — a person answering questions is slower than a registry. Failure is
- * silence: offline, behind a proxy, or a registry that is down are all just no
- * notice rather than a scaffolder that will not run.
- */
-function checkForNewer() {
-    // Unknown is not stale. selfVersion() answers '' when it cannot read the
-    // manifest, and comparing against that would report every run as behind.
-    const mine = selfVersion().slice(1);
-    if (!mine)
-        return Promise.resolve(null);
-    return (async () => {
-        const response = await fetch('https://registry.npmjs.org/create-rsc-kit/latest', {
-            signal: AbortSignal.timeout(3000),
-            headers: { accept: 'application/json' },
-        });
-        if (!response.ok)
-            return null;
-        const latest = (await response.json()).version;
-        return latest && latest !== mine ? latest : null;
-    })().catch(() => null);
-}
-async function notifyIfStale() {
-    const latest = await staleCheck;
-    if (!latest)
-        return;
-    stdout.write(`${dim('A newer create-rsc-kit is out:')} ${bold(`v${latest}`)}${dim(`, and this is ${selfVersion()}.`)}\n` +
-        `${dim('bunx reuses the copy it downloaded first. Name the tag and it fetches:')}\n\n` +
-        `  ${cyan('bun create rsc-kit@latest')}\n\n`);
-}
 /** A path the user can paste, when it is under where they are. */
 function relativeish(dir) {
     const cwd = process.cwd();

package/dist/init.js

@@ -277,25 +277,72 @@ function routes(o, dir) {
     return steps;
 }
 /**
- * A tsconfig, for a project that has none.
+ * A tsconfig, for a project that has none — and one line for a project that has.
  *
  * Laravel ships without one, and the route tree is .tsx — so with nothing here
  * an editor reports an error on every generated file and the `typecheck`
  * script has no configuration to read. Written only when absent, like
  * everything else.
+ *
+ * Where one exists it is not replaced, but `include` still has to name
+ * `.rsc-kit`, because that is where the build writes its ambient declarations
+ * and TypeScript will not find them otherwise. Not a style preference: a
+ * directory whose name begins with a dot is outside the default `**\/*`, so a
+ * project with no `include` at all misses them exactly like one that lists
+ * only `src`. Measured both ways.
+ *
+ * Missing it is invisible — every file is written, the build passes, and Link
+ * takes `string` again instead of the route union, so a link to a page that
+ * does not exist compiles and 404s in the browser.
  */
 function tsconfig(o, found, dir) {
-    const steps = [];
-    if (found.hasTypeScript) {
-        return [...steps, { kind: 'skipped', what: 'tsconfig.json', detail: 'already here' }];
+    const path = join(dir, 'tsconfig.json');
+    if (!found.hasTypeScript) {
+        writeFileSync(path, t.tsconfig(o));
+        return [{ kind: 'wrote', what: 'tsconfig.json' }];
+    }
+    // Reported, never rewritten. Adding the entry means parsing and reprinting
+    // the file, which loses the comments a tsconfig is allowed to have and the
+    // formatting someone chose — a worse trade than one line of output, for a
+    // file this does not own.
+    const current = readFileSync(path, 'utf-8');
+    // Comments are legal here and JSON.parse does not take them.
+    const include = (() => {
+        try {
+            const parsed = JSON.parse(current.replace(/\/\*[\s\S]*?\*\/|(^|\s)\/\/.*$/gm, '$1'));
+            return Array.isArray(parsed.include) ? parsed.include : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (include?.some((entry) => typeof entry === 'string' && entry.includes('.rsc-kit'))) {
+        return [{ kind: 'skipped', what: 'tsconfig.json', detail: 'already includes .rsc-kit' }];
     }
-    writeFileSync(join(dir, 'tsconfig.json'), t.tsconfig(o));
-    return [...steps, { kind: 'wrote', what: 'tsconfig.json' }];
+    // An absent `include` is not an empty one — TypeScript's default covers the
+    // project — but the default is `**\/*`, and a directory whose name begins
+    // with a dot is outside it. So both cases need the entry, and a project with
+    // no `include` needs `**\/*` written alongside it or it loses everything
+    // else. Measured both ways.
+    return [
+        {
+            kind: 'manual',
+            what: 'tsconfig.json',
+            detail: include
+                ? `add "${TYPES_GLOB}" to "include", or typed routes fall back to string`
+                : `add "include": ["**/*", "${TYPES_GLOB}"], or typed routes fall back to string`,
+        },
+    ];
 }
+/** Where the build writes its ambient declarations, as a tsconfig include. */
+const TYPES_GLOB = '.rsc-kit/**/*';
 /** Ignore the files the build rewrites into the source dir on every run. */
 function gitignore(o, dir) {
     const path = join(dir, '.gitignore');
-    const generated = ['rsc-env.d.ts', 'rsc-types.d.ts', 'rsc-routes.d.ts', 'rsc-engine.d.ts'].map((f) => `${o.sourceDir}/${f}`);
+    // The declarations moved out of the source directory into .rsc-kit, so this
+    // is one line where it used to be four. The stub stays put — the app imports
+    // it by relative path.
+    const generated = ['.rsc-kit/', `${o.sourceDir}/server-actions.generated.ts`];
     const p = t.paths(o);
     // Everything the build writes: the bundles, Nitro's output, and the hot
     // file. The hot file is the worst of them to commit — it points every other
@@ -306,9 +353,10 @@ function gitignore(o, dir) {
     const missing = [...generated, ...outputs].filter((line) => !current.split('\n').some((existing) => existing.trim() === line));
     if (missing.length === 0)
         return [{ kind: 'skipped', what: '.gitignore', detail: 'already covers the generated files' }];
-    writeFileSync(path, current + (current.endsWith('\n') || current === '' ? '' : '\n') +
-        '\n# The RSC build: rewritten into the source dir every run, and written out.\n' +
-        missing.join('\n') + '\n');
+    // The blank line separates this block from whatever was above it, so there
+    // is nothing to separate from when the file is new.
+    const head = current === '' ? '' : current.endsWith('\n') ? current + '\n' : current + '\n\n';
+    writeFileSync(path, head + '# The RSC build: rewritten every run, and what it builds.\n' + missing.join('\n') + '\n');
     return [{ kind: 'merged', what: '.gitignore', detail: `added ${missing.length} generated paths` }];
 }
 /** Everything, in the order a reader would want to hear about it. */
@@ -358,7 +406,7 @@ export async function runInit(args) {
     if (!existsSync(join(dir, 'package.json'))) {
         stdout.write(`\n${bold('No package.json here.')}\n` +
             `  init adds RSC to a project that already exists. To start a new one:\n` +
-            `  ${cyan('bun create rsc-kit my-app')}\n\n`);
+            `  ${cyan('bun create rsc-kit@latest my-app')}\n\n`);
         exit(1);
     }
     const flags = parseArgs(args);

package/dist/stale.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The calling package's version, read from the manifest above it.
+ *
+ * Read rather than baked in, because the version is only written at publish
+ * time. The caller passes its own `import.meta.url` so this answers for
+ * whichever package asked — `create-rsc-kit` and `rsc-kit` both do.
+ */
+export declare function selfVersion(moduleUrl: string): string;
+/**
+ * Ask the registry what `latest` is. Null when there is nothing to say.
+ *
+ * Start it before the first prompt and read it after the last: a person
+ * answering questions is slower than a registry, so it costs nothing. Failure
+ * is silence — offline, behind a proxy, or a registry that is down are all no
+ * notice rather than a tool that hangs or will not run.
+ */
+export declare function checkForNewer(pkg: string, mine: string): Promise<string | null>;
+/** Say it, and say the way out — which is the tag, not the version. */
+export declare function notifyIfStale(check: Promise<string | null>, command: string): Promise<void>;

package/dist/stale.js

@@ -0,0 +1,81 @@
+// Telling someone their scaffolder is old, because nothing else will.
+//
+// `bun create rsc-kit` is `bunx create-rsc-kit`, and `bunx rsc-kit init` is the
+// same shape — bunx reuses the copy it downloaded the first time. A machine
+// that ran either once keeps using that version however many releases later,
+// which here meant scaffolding from one two releases old: offering hosts that
+// had been removed, and writing a config the current plugin refuses.
+//
+// Naming the tag is what makes bunx revalidate. Measured against an older
+// build planted in the cache slot:
+//
+//   bun create rsc-kit             stale
+//   bunx create-rsc-kit            stale
+//   bunx rsc-kit init              stale
+//   bun create rsc-kit@latest      fresh
+//   bunx create-rsc-kit@latest     fresh
+//   npx create-rsc-kit@latest      fresh
+//
+// So every instruction this project publishes names it. That is the fix, and
+// this is for the copies already cached, which no wording can reach. Printing
+// a version alone would not do it either — nobody knows v0.5.0 is two behind
+// unless something says so.
+//
+// create-next-app does this with the `update-check` package. Not here: both
+// packages are installed by bunx before they can do anything, so a dependency
+// is latency every user waits through, which is the same reason the prompts
+// are written against readline. It is one request to one url.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { stdout } from 'node:process';
+import { bold, cyan, dim } from './prompt.js';
+/**
+ * The calling package's version, read from the manifest above it.
+ *
+ * Read rather than baked in, because the version is only written at publish
+ * time. The caller passes its own `import.meta.url` so this answers for
+ * whichever package asked — `create-rsc-kit` and `rsc-kit` both do.
+ */
+export function selfVersion(moduleUrl) {
+    try {
+        const path = join(dirname(fileURLToPath(moduleUrl)), '../package.json');
+        return JSON.parse(readFileSync(path, 'utf-8')).version;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Ask the registry what `latest` is. Null when there is nothing to say.
+ *
+ * Start it before the first prompt and read it after the last: a person
+ * answering questions is slower than a registry, so it costs nothing. Failure
+ * is silence — offline, behind a proxy, or a registry that is down are all no
+ * notice rather than a tool that hangs or will not run.
+ */
+export function checkForNewer(pkg, mine) {
+    // Unknown is not stale. An unreadable manifest answers '', and comparing
+    // against that would report every run as behind.
+    if (!mine)
+        return Promise.resolve(null);
+    return (async () => {
+        const response = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+            signal: AbortSignal.timeout(3000),
+            headers: { accept: 'application/json' },
+        });
+        if (!response.ok)
+            return null;
+        const latest = (await response.json()).version;
+        return latest && latest !== mine ? latest : null;
+    })().catch(() => null);
+}
+/** Say it, and say the way out — which is the tag, not the version. */
+export async function notifyIfStale(check, command) {
+    const latest = await check;
+    if (!latest)
+        return;
+    stdout.write(`${dim('A newer release is out:')} ${bold(`v${latest}`)}${dim('.')}\n` +
+        `${dim('bunx reuses the copy it downloaded first. Name the tag and it fetches:')}\n\n` +
+        `  ${cyan(command)}\n\n`);
+}

package/dist/templates.d.ts

@@ -68,7 +68,7 @@ export declare function counter(o: Options): string;
  * and nothing warns — the page just arrives unstyled.
  */
 export declare const styles = "@import 'tailwindcss';\n\n/* The whole source tree, not just this directory. A client component is found\n   automatically because it enters the browser bundle; a server component never\n   does, so anything it uses has to be declared here or it is silently absent\n   from the stylesheet. */\n@source '../';\n";
-export declare const gitignore = "node_modules\nbuild\n.rsc\ndist\n*.log\n.DS_Store\n\n# Written by the build into the source dir, every run.\nsrc/rsc-env.d.ts\nsrc/rsc-types.d.ts\nsrc/rsc-routes.d.ts\nsrc/rsc-engine.d.ts\n";
+export declare const gitignore = "node_modules\nbuild\n.output\n.rsc\ndist\n*.log\n.DS_Store\n\n# Rewritten by the build every run: the ambient declarations, and the stub\n# module the app imports its server actions from.\n.rsc-kit/\nsrc/server-actions.generated.ts\n";
 /**
  * oxlint, with the React Compiler's own rules turned on.
  *

package/dist/templates.js

@@ -228,7 +228,10 @@ export const tsconfig = (o) => JSON.stringify({
                 ? ['node', 'vite/client']
                 : ['@types/bun', 'vite/client'],
     },
-    include: [`${o.sourceDir}/**/*`],
+    // .rsc-kit holds the generated ambient declarations. Ambient means
+    // inside the project, and `include` is what decides that — leave it out
+    // and typed routes silently fall back to string.
+    include: [`${o.sourceDir}/**/*`, '.rsc-kit/**/*'],
 }, null, 2) + '\n';
 export function layout(o) {
     return `${o.tailwind ? "import './styles.css'\n" : ''}import type { ReactNode } from 'react'
@@ -318,16 +321,16 @@ export const styles = `@import 'tailwindcss';
 `;
 export const gitignore = `node_modules
 build
+.output
 .rsc
 dist
 *.log
 .DS_Store
 
-# Written by the build into the source dir, every run.
-src/rsc-env.d.ts
-src/rsc-types.d.ts
-src/rsc-routes.d.ts
-src/rsc-engine.d.ts
+# Rewritten by the build every run: the ambient declarations, and the stub
+# module the app imports its server actions from.
+.rsc-kit/
+src/server-actions.generated.ts
 `;
 /**
  * oxlint, with the React Compiler's own rules turned on.
@@ -375,31 +378,49 @@ export function oxlintConfig(o) {
 }
 export function readme(o) {
     const pm = o.host === 'node' ? 'npm run' : 'bun run';
+    const runtime = o.host === 'worker' ? 'Cloudflare Workers' : o.host === 'node' ? 'Node' : 'Bun';
+    // A Worker is deployed rather than started, and only Bun compiles.
+    const serve = o.host === 'worker'
+        ? `${pm} preview     # wrangler dev, on workerd\n${pm} deploy      # nitro deploy --prebuilt`
+        : `${pm} start       # serve on http://localhost:${PORT}`;
+    const compile = o.host === 'bun'
+        ? `\n\n\`${pm} compile\` puts the whole application in one file — engine, pages and
+assets — with Bun's runtime inside it. Frozen pages stay outside: a binary
+has no filesystem to read them from, so it renders those live.`
+        : '';
     return `# ${o.name}
 
-React Server Components on ${o.host === 'node' ? 'node:http' : o.host === 'bun' ? 'Bun.serve' : o.host}.
+React Server Components, served by ${runtime}.
 
 \`\`\`sh
 ${pm} dev         # vite — serves from source, no build step
 ${pm} build       # bundles, then freezes every page it can
-${pm} start       # serve on http://localhost:${PORT}
+${serve}
 \`\`\`
 
-Freezing is part of \`build\`. To redo it against fresh data without
-rebuilding — or after turning it off in \`vite.config.ts\` — run
-\`bunx rsc-kit prerender --out ${paths(o).outDir}\`, keeping that package's version in
-step with \`@rsc-kit/core\`.
+There is no server file here. \`vite.config.ts\` names a Nitro preset and the
+server is built around your route tree, into \`.output/\` — changing where this
+deploys is changing that one string.${compile}
+
+Freezing is part of \`build\`: it renders every page it can and stores the
+result, so those pages are read off disk instead of rendered per visitor.
+Turn it off with \`rscKit({ prerender: false })\` when the build machine
+cannot do what the pages need.
 
 ## Where things go
 
-    src/app/layout.tsx    the root layout; owns <html>
-    src/app/page.tsx      /
-    src/app/about/page.tsx  /about
-    src/components/       client components ("use client")
+    src/app/layout.tsx     the root layout; owns <html>
+    src/app/page.tsx       /
+    src/app/styles.css     imported by the layout
+    src/components/        client components ("use client")
 
-A directory with a \`page.tsx\` is a route. \`[slug]\` is a parameter,
+A directory with a \`page.tsx\` is a route, so \`src/app/about/page.tsx\` is
+\`/about\` with nothing to register. \`[slug]\` is a parameter, and
 \`middleware.ts\` runs before anything at or below it renders.
 
-Docs: https://github.com/ramonmalcolm/rsc-kit
+\`.rsc-kit/\` is the build's: the route types that make \`href\` checkable, and
+the ambient declarations. Rewritten every build, and gitignored.
+
+Docs: https://rsc-kit.dev
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rsc-kit",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "type": "module",
   "description": "Scaffold an RSC app on Bun, Hono, Elysia or Node.",
   "bin": {
@@ -34,6 +34,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./stale": {
+      "types": "./dist/stale.d.ts",
+      "default": "./dist/stale.js"
     }
   },
   "repository": {