create-rsc-kit 0.17.0 → 0.18.0

package/dist/index.js

@@ -9,8 +9,9 @@ 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 { randomBytes } from 'node:crypto';
 import { argv, exit, stdout } from 'node:process';
-import { DEFAULT_COMPILER, HELP, HOSTS, publishedCore, assertInsideCwd, assertUsableName, defaultCore, parseArgs, } from './options.js';
+import { DEFAULT_COMPILER, HELP, HOSTS, publishedCore, assertInsideCwd, assertUsableName, defaultCore, parseArgs, VALIDATIONS } from './options.js';
 import { Prompter, bold, cyan, dim } from './prompt.js';
 import { checkForNewer, notifyIfStale, selfVersion } from './stale.js';
 import * as t from './templates.js';
@@ -77,10 +78,13 @@ async function collect() {
             compiler: flags.compiler ?? 'none',
             tailwind: flags.tailwind ?? true,
             lint: flags.lint ?? true,
+            validation: flags.validation ?? 'zod',
+            env: flags.env ?? (flags.validation ?? 'zod') !== 'none',
             sourceDir: flags.sourceDir ?? 'src',
             install: flags.install ?? true,
             git: flags.git ?? true,
             core,
+            backend: flags.backend,
         };
     }
     // Nothing is attached to answer. readline would simply never resolve, and a
@@ -101,6 +105,11 @@ async function collect() {
         const compiler = flags.compiler ?? ((await p.confirm('React Compiler', true)) ? DEFAULT_COMPILER : 'none');
         const tailwind = flags.tailwind ?? (await p.confirm('Tailwind CSS', true));
         const lint = flags.lint ?? (await p.confirm('oxlint', true));
+        const validation = flags.validation ?? (await p.select('Validation library', VALIDATIONS));
+        // Only worth asking once there is a library to validate with.
+        const env = validation === 'none'
+            ? false
+            : (flags.env ?? (await p.confirm('Typed environment variables (@t3-oss/env-core)', true)));
         return {
             dir: resolve(dir),
             name: basename(dir),
@@ -108,10 +117,13 @@ async function collect() {
             compiler,
             tailwind,
             lint,
+            validation,
+            env,
             sourceDir: flags.sourceDir ?? 'src',
             install: flags.install ?? (await p.confirm('Install dependencies now', true)),
             git: flags.git ?? true,
             core,
+            backend: flags.backend,
         };
     }
     finally {
@@ -148,8 +160,21 @@ function write(o) {
     ];
     if (o.tailwind)
         files.push(['src/app/styles.css', t.styles]);
+    if (o.env) {
+        files.push([`${o.sourceDir}/env.ts`, t.env(o)]);
+        files.push([`${o.sourceDir}/instrumentation.ts`, t.instrumentation(o)]);
+        files.push(['.env.example', t.envExample]);
+    }
     if (o.lint)
         files.push(['.oxlintrc.json', t.oxlintConfig(o)]);
+    // A backend answering host calls: the two lines that wire it, and a
+    // secret the backend is given once. The scaffold's .gitignore already
+    // keeps .env out of git.
+    if (o.backend) {
+        files.push(['.env', t.backendEnv(o.backend, randomBytes(32).toString('base64url'))]);
+        if (!o.env)
+            files.push(['.env.example', t.backendEnvExample(o.backend)]);
+    }
     const replaced = [];
     for (const [path, contents] of files) {
         const full = join(o.dir, path);
@@ -193,6 +218,9 @@ function report(o) {
     for (const step of steps)
         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`);
+    if (o.backend) {
+        stdout.write(`${bold('Then:')} ${t.backendStep(false)}\n\n`);
+    }
 }
 /** A path the user can paste, when it is under where they are. */
 function relativeish(dir) {

package/dist/init.d.ts

@@ -4,6 +4,8 @@ export interface Detected {
     deps: Record<string, string>;
     /** A Laravel application: artisan and a composer manifest, both. */
     laravel: boolean;
+    /** A Go module: the backend is Go, and answers host calls from its own server. */
+    go: boolean;
     host: Host | null;
     sourceDir: string | null;
     viteConfig: string | null;
@@ -25,7 +27,6 @@ export interface Step {
  * about things the project has already decided.
  */
 export declare function detect(dir: string): Detected;
-/** Everything, in the order a reader would want to hear about it. */
 export declare function initialise(o: Options, found: Detected, dir: string): Step[];
 /**
  * Add RSC to a project that already exists.

package/dist/init.js

@@ -8,7 +8,8 @@
 // written, missing dependencies are added, and for anything already present
 // the exact edit is printed for the reader to make. A tool that silently
 // reformats a working server has to be right about more than it can know.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { cwd, exit, stdout } from 'node:process';
 import { DEFAULT_COMPILER, parseArgs, publishedCore } from './options.js';
@@ -47,12 +48,18 @@ export function detect(dir) {
     return {
         deps,
         laravel,
+        go: existsSync(join(dir, 'go.mod')),
         host,
-        // Its own directory under resources/js rather than resources/js itself: a
-        // Laravel app already keeps its asset entry points there, and a route tree
-        // rooted at that directory would make app.js a page.
+        // resources/js, the directory a Laravel app already keeps its JavaScript
+        // in, so the route tree is resources/js/app the way it is src/app
+        // everywhere else. The stock app.js and bootstrap.js beside it are files,
+        // not the app/ directory, and the route tree never looks at them. An app
+        // that init set up before this default - a tree at resources/js/rsc/app
+        // - keeps it: a second run must never move a tree.
         sourceDir: laravel
-            ? 'resources/js/rsc'
+            ? existsSync(join(dir, 'resources/js/rsc/app'))
+                ? 'resources/js/rsc'
+                : 'resources/js'
             : ['src', 'app', 'resources/js'].find((d) => existsSync(join(dir, d))) ?? null,
         viteConfig: ['vite.config.ts', 'vite.config.js', 'vite.config.mts'].find((f) => existsSync(join(dir, f))) ?? null,
         hasReact: Boolean(deps.react),
@@ -86,6 +93,17 @@ function major(range) {
  * asset pipeline too.
  */
 function mergeDependencies(o, found) {
+    // laravel-vite-plugin served the Blade asset pipeline, which the renderer
+    // replaces; left installed it would still be resolvable from the moved-aside
+    // config, and nothing else. Removed from the manifest so `npm install` does
+    // not keep fetching it; the moved-aside config names it in its own steps.
+    if (o.host === 'laravel') {
+        for (const field of ['dependencies', 'devDependencies']) {
+            const bucket = found.packageJson[field];
+            if (bucket && 'laravel-vite-plugin' in bucket)
+                delete bucket['laravel-vite-plugin'];
+        }
+    }
     const pkg = found.packageJson;
     const wanted = JSON.parse(t.packageJson(o));
     const steps = [];
@@ -182,6 +200,15 @@ function mergeScripts(o, found) {
         if (existing === command)
             continue;
         if (STOCK[name]?.includes(existing.trim())) {
+            // A stock script. On Laravel it was the Blade asset pipeline's, and
+            // the renderer owns the frontend now - one config, one pipeline - so
+            // it is replaced rather than run beside. Elsewhere the two are
+            // combined, so the command keeps doing what it did as well.
+            if (o.host === 'laravel') {
+                scripts[name] = command;
+                combined.push(name);
+                continue;
+            }
             scripts[name] = combine(name, existing.trim(), command);
             combined.push(name);
             needsConcurrently ||= name === 'dev';
@@ -200,7 +227,9 @@ function mergeScripts(o, found) {
         steps.push({
             kind: 'merged',
             what: combined.join(' and '),
-            detail: 'now runs the asset pipeline AND the renderer',
+            detail: o.host === 'laravel'
+                ? 'the renderer, in place of the Blade pipeline they ran'
+                : 'now runs the asset pipeline AND the renderer',
         });
     }
     // Declared here rather than in the template, because whether it is needed
@@ -223,32 +252,64 @@ function mergeScripts(o, found) {
 /** The plugin entry, written if there is no config and printed if there is. */
 function viteConfig(o, found, dir) {
     const file = t.configFile(o);
-    // Laravel is asked about a different file than the one it already has. Its
-    // vite.config carries laravel-vite-plugin, and the two cannot share a config
-    // — so the question is whether the RSC config exists, not whether any does.
-    const existing = o.host === 'laravel' ? (existsSync(join(dir, file)) ? file : null) : found.viteConfig;
+    const existing = found.viteConfig;
     if (existing === null) {
         writeFileSync(join(dir, file), t.viteConfig(o));
         return [{ kind: 'wrote', what: file }];
     }
+    // A Laravel app's vite.config carries laravel-vite-plugin, which owns
+    // base, publicDir, outDir, the input list and the server origin - the same
+    // things this build owns - so the two cannot share a file. They do not
+    // need to: once the renderer owns the frontend there is no @vite
+    // directive and no Blade asset pipeline for that plugin to serve. The old
+    // config is kept beside the new one, for a Blade page or two that still
+    // needs it, rather than lost.
+    if (o.host === 'laravel') {
+        const source = readFileSync(join(dir, existing), 'utf-8');
+        // Already the renderer's: a second run, or a hand-written one.
+        if (source.includes('rscKit(')) {
+            return [{ kind: 'skipped', what: existing, detail: 'already has rscKit()' }];
+        }
+        // Some other config the build cannot own - not Blade's - so the edit is
+        // printed rather than the file replaced.
+        if (!source.includes('laravel-vite-plugin')) {
+            return [manualPluginStep(o, existing)];
+        }
+        const aside = existing.replace(/vite\.config/, 'vite.config.blade');
+        if (!existsSync(join(dir, aside)))
+            renameSync(join(dir, existing), join(dir, aside));
+        writeFileSync(join(dir, file), t.viteConfig(o));
+        return [
+            { kind: 'wrote', what: file, detail: `the renderer owns the frontend now` },
+            {
+                kind: 'manual',
+                what: aside,
+                detail: `your previous config, moved aside. It served the Blade asset pipeline ` +
+                    `(laravel-vite-plugin, @vite in a layout). Delete it once nothing uses that; ` +
+                    `to keep a Blade page, build it with \`vite build --config ${aside}\`.`,
+            },
+        ];
+    }
+    return [manualPluginStep(o, existing)];
+}
+/** The edit to make by hand when a config the build cannot own is already there. */
+function manualPluginStep(o, existing) {
     const p = t.paths(o);
     const shown = [
         `sourceDir: '${p.sourceDir}'`,
         `outDir: '${p.outDir}'`,
         ...(p.hotFile ? [`hotFile: '${p.hotFile}'`] : []),
     ].join(', ');
-    return [
-        {
-            kind: 'manual',
-            what: existing,
-            detail: `add the plugin — it must come before any react() layer:\n` +
-                `      import { rscKit } from '@rsc-kit/core/vite'\n\n` +
-                `      plugins: [\n` +
-                `        rscKit({ ${shown} }),\n` +
-                `        …whatever you already have\n` +
-                `      ]`,
-        },
-    ];
+    return {
+        kind: 'manual',
+        what: existing,
+        detail: `add the plugin — it must come before any react() layer:\n` +
+            `      import { rscKit } from '@rsc-kit/core/vite'\n\n` +
+            `      plugins: [\n` +
+            `        rscKit({ ${shown} }),\n` +
+            `        …whatever you already have\n` +
+            `      ]`,
+    };
 }
 /** The route tree, only where there is not one already. */
 function routes(o, dir) {
@@ -302,6 +363,38 @@ function routes(o, dir) {
  * takes `string` again instead of the route union, so a link to a page that
  * does not exist compiles and 404s in the browser.
  */
+/** JSON with comments, made JSON: comments outside strings removed, strings kept whole. */
+function withoutComments(source) {
+    let out = '';
+    let i = 0;
+    while (i < source.length) {
+        const c = source[i];
+        if (c === '"') {
+            const end = source.indexOf('"', i + 1);
+            let j = end;
+            // A quote escaped inside the string is not its end.
+            while (j !== -1 && source[j - 1] === '\\')
+                j = source.indexOf('"', j + 1);
+            const close = j === -1 ? source.length : j + 1;
+            out += source.slice(i, close);
+            i = close;
+            continue;
+        }
+        if (c === '/' && source[i + 1] === '/') {
+            const nl = source.indexOf('\n', i);
+            i = nl === -1 ? source.length : nl;
+            continue;
+        }
+        if (c === '/' && source[i + 1] === '*') {
+            const end = source.indexOf('*/', i + 2);
+            i = end === -1 ? source.length : end + 2;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}
 function tsconfig(o, found, dir) {
     const path = join(dir, 'tsconfig.json');
     if (!found.hasTypeScript) {
@@ -313,10 +406,14 @@ function tsconfig(o, found, dir) {
     // 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.
+    // Comments are legal here and JSON.parse does not take them. Stripped
+    // outside strings only: a glob like ".rsc-kit/**/*" holds "/*", and a
+    // regex that did not know about strings read it as a comment opening,
+    // ate the rest of the file, and reported the tsconfig this very tool
+    // wrote as missing the entry it wrote.
     const include = (() => {
         try {
-            const parsed = JSON.parse(current.replace(/\/\*[\s\S]*?\*\/|(^|\s)\/\/.*$/gm, '$1'));
+            const parsed = JSON.parse(withoutComments(current));
             return Array.isArray(parsed.include) ? parsed.include : null;
         }
         catch {
@@ -356,8 +453,12 @@ function gitignore(o, dir) {
     // machine at a dev server that is not running there.
     const all = ['.output', p.outDir, ...(p.hotFile ? [p.hotFile] : [])];
     const outputs = all.filter((path) => !all.some((other) => other !== path && path.startsWith(other + '/')));
+    // A backend's secret lives in .env, which is the file whose commit is
+    // noticed late. Only when there is one: a project without a backend has
+    // its own policy and this leaves it alone.
+    const secrets = o.backend && o.host !== 'laravel' ? ['.env', '.env.*', '!.env.example'] : [];
     const current = existsSync(path) ? readFileSync(path, 'utf-8') : '';
-    const missing = [...generated, ...outputs].filter((line) => !current.split('\n').some((existing) => existing.trim() === line));
+    const missing = [...generated, ...outputs, ...secrets].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' }];
     // The blank line separates this block from whatever was above it, so there
@@ -367,18 +468,50 @@ function gitignore(o, dir) {
     return [{ kind: 'merged', what: '.gitignore', detail: `added ${missing.length} generated paths` }];
 }
 /** Everything, in the order a reader would want to hear about it. */
+/**
+ * The backend's two lines, for a project that has one and is not Laravel.
+ *
+ * .env is written once and never rewritten: the secret in it is the one the
+ * backend was given, and regenerating it on a second run would answer every
+ * host call with 403 - which reads as the application refusing its own data.
+ * The wiring on the other side is printed, never written: a package main in
+ * someone's module is not a file to add blind.
+ */
+function backend(o, found, dir) {
+    if (!o.backend || o.host === 'laravel')
+        return [];
+    const steps = [];
+    const env = join(dir, '.env');
+    if (existsSync(env)) {
+        steps.push({ kind: 'skipped', what: '.env', detail: 'already exists; RSC_BACKEND and RSC_HOST_CALL_SECRET must be in it' });
+    }
+    else {
+        writeFileSync(env, t.backendEnv(o.backend, randomBytes(32).toString('base64url')));
+        steps.push({ kind: 'wrote', what: '.env', detail: 'RSC_BACKEND and a generated RSC_HOST_CALL_SECRET' });
+    }
+    const example = join(dir, '.env.example');
+    if (!existsSync(example)) {
+        writeFileSync(example, t.backendEnvExample(o.backend));
+        steps.push({ kind: 'wrote', what: '.env.example' });
+    }
+    steps.push({ kind: 'manual', what: 'backend', detail: t.backendStep(found.go) });
+    return steps;
+}
 export function initialise(o, found, dir) {
     const steps = [
         ...routes(o, dir),
         ...viteConfig(o, found, dir),
         ...tsconfig(o, found, dir),
         ...gitignore(o, dir),
+        ...backend(o, found, dir),
         ...mergeDependencies(o, found),
         ...mergeScripts(o, found),
     ];
     writeFileSync(join(dir, 'package.json'), JSON.stringify(found.packageJson, null, 2) + '\n');
     return steps;
 }
+/** Where a Go server listens, unless told otherwise. */
+const DEFAULT_BACKEND = 'http://127.0.0.1:8080';
 const INIT_HELP = `
   rsc-kit init — add RSC to the project in this directory
 
@@ -390,7 +523,9 @@ const INIT_HELP = `
     --source-dir <dir>   where app/ should live (detected, usually src)
     --host=…             bun | hono | elysia | node (detected from your deps)
                          laravel is detected from artisan, never asked
-    --backend=<url>      for laravel: where host calls go, e.g. http://app.test
+    --backend=<url>      a backend answering host calls - a Go server, say, at
+                         http://127.0.0.1:8080 (assumed when go.mod is here);
+                         laravel reads APP_URL instead
     --compiler=…         none | oxc | babel
     --tailwind           add Tailwind as well
     -y, --yes            accept what was detected, ask nothing
@@ -423,9 +558,13 @@ export async function runInit(args) {
     stdout.write(`  ${dim('server')}      ${found.host}${flags.host ? '' : dim('  (detected)')}\n`);
     stdout.write(`  ${dim('source')}      ${flags.sourceDir ?? found.sourceDir ?? 'src'}\n`);
     stdout.write(`  ${dim('react')}       ${found.hasReact ? 'already here' : 'will be added'}\n`);
+    const backendUrl = flags.backend ?? (found.go ? DEFAULT_BACKEND : undefined);
     if (found.host === 'laravel') {
         stdout.write(`  ${dim('backend')}     ${flags.backend ?? 'http://localhost'}\n`);
     }
+    else if (backendUrl) {
+        stdout.write(`  ${dim('backend')}     ${backendUrl}${flags.backend ? '' : dim('  (go.mod is here)')}\n`);
+    }
     stdout.write('\n');
     let compiler = flags.compiler ?? 'none';
     let tailwind = flags.tailwind ?? found.hasTailwind;
@@ -448,11 +587,14 @@ export async function runInit(args) {
         compiler,
         tailwind,
         lint: false,
+        // An existing project has its own schema library and env handling; init adds neither.
+        validation: 'none',
+        env: false,
         sourceDir: flags.sourceDir ?? found.sourceDir ?? 'src',
         install: false,
         git: false,
         core: flags.core ?? publishedCore(),
-        backend: flags.backend,
+        backend: backendUrl,
     };
     const steps = initialise(options, found, dir);
     const mark = { wrote: cyan('+'), merged: cyan('~'), manual: bold('!'), skipped: dim('·') };
@@ -462,7 +604,7 @@ export async function runInit(args) {
     }
     const manual = steps.filter((s) => s.kind === 'manual');
     if (manual.length > 0) {
-        stdout.write(`\n${bold('Then, by hand:')} the edits marked ! above are in files you already had.\n\n`);
+        stdout.write(`\n${bold('Then, by hand:')} the steps marked ! above.\n\n`);
         return;
     }
     stdout.write(options.host === 'laravel'

package/dist/options.d.ts

@@ -8,6 +8,13 @@
  */
 export type Host = 'bun' | 'node' | 'worker' | 'laravel';
 export type Compiler = 'none' | 'oxc' | 'babel';
+/**
+ * The validation library, asked once because everything schema-shaped hangs
+ * off it: typed environment variables, `action.input(schema)`, a form's
+ * schema, a page's `searchParams`. All three speak Standard Schema, which is
+ * what the engine reads, so none is special-cased anywhere else.
+ */
+export type Validation = 'none' | 'zod' | 'valibot' | 'arktype';
 export interface Options {
     dir: string;
     name: string;
@@ -22,6 +29,13 @@ export interface Options {
      * component's rpc() reaches the application it is rendering for.
      */
     backend?: string;
+    validation: Validation;
+    /**
+     * Typed environment variables through @t3-oss/env-core, read once at
+     * startup and refused with the variable named when one is missing or wrong.
+     * Needs a validation library; asked only when one was chosen.
+     */
+    env: boolean;
     install: boolean;
     git: boolean;
     /** What to depend on for the engine. A path makes a local checkout testable. */
@@ -35,6 +49,12 @@ export interface Options {
  * question whose only right answer is "the framework I am already in" is a
  * question with a wrong answer available.
  */
+export declare const VALIDATIONS: {
+    value: Validation;
+    label: string;
+    hint: string;
+}[];
+export declare function assertValidation(value: string): Validation;
 export declare const HOSTS: {
     value: Host;
     label: string;
@@ -93,4 +113,4 @@ export declare function assertUsableName(name: string): void;
  * generator nobody can run without reading it first.
  */
 export declare function assertInsideCwd(dir: string, cwd: string): void;
-export declare const HELP = "\n  create-rsc-kit \u2014 scaffold an RSC app\n\n  Usage\n    create-rsc-kit <dir> [options]\n    bun create rsc-kit@latest <dir> [options]\n\n  Options\n    --host=bun|node|worker        where it runs \u2014 picks the Nitro preset\n    --compiler=none|oxc|babel     React Compiler (prompt offers oxc; babel by flag)\n    --tailwind / --no-tailwind    include Tailwind\n    --lint / --no-lint            include oxlint\n    --source-dir <dir>            where app/ lives (default: src)\n    --init                        add to the project here, rather than scaffold\n    --core=<spec>                 engine dependency, e.g. file:../rsc-kit/packages/core\n    --no-install                  skip installing dependencies\n    --no-git                      skip git init\n    -y, --yes                     accept every default, ask nothing\n    -h, --help                    this\n";
+export declare const HELP = "\n  create-rsc-kit \u2014 scaffold an RSC app\n\n  Usage\n    create-rsc-kit <dir> [options]\n    bun create rsc-kit@latest <dir> [options]\n\n  Options\n    --host=bun|node|worker        where it runs \u2014 picks the Nitro preset\n    --compiler=none|oxc|babel     React Compiler (prompt offers oxc; babel by flag)\n    --tailwind / --no-tailwind    include Tailwind\n    --lint / --no-lint            include oxlint\n    --validation=zod|valibot|arktype|none\n                                  the schema library; forms, actions and env use it\n    --env / --no-env              typed environment variables (@t3-oss/env-core)\n    --source-dir <dir>            where app/ lives (default: src)\n    --backend=<url>               a backend answering host calls \u2014 a Go server, say,\n                                  at http://127.0.0.1:8080; writes .env with a secret\n    --init                        add to the project here, rather than scaffold\n    --core=<spec>                 engine dependency, e.g. file:../rsc-kit/packages/core\n    --no-install                  skip installing dependencies\n    --no-git                      skip git init\n    -y, --yes                     accept every default, ask nothing\n    -h, --help                    this\n";

package/dist/options.js

@@ -9,6 +9,17 @@ import { fileURLToPath } from 'node:url';
  * question whose only right answer is "the framework I am already in" is a
  * question with a wrong answer available.
  */
+export const VALIDATIONS = [
+    { value: 'zod', label: 'Zod', hint: 'the one most examples are written in' },
+    { value: 'valibot', label: 'Valibot', hint: 'the same idea, a tenth of the bytes in the browser' },
+    { value: 'arktype', label: 'ArkType', hint: 'TypeScript syntax as a string, fastest at runtime' },
+    { value: 'none', label: 'None', hint: 'add one later; forms and actions take any Standard Schema' },
+];
+export function assertValidation(value) {
+    if (value === 'none' || value === 'zod' || value === 'valibot' || value === 'arktype')
+        return value;
+    throw new Error(`--validation must be one of zod, valibot, arktype or none; got ${JSON.stringify(value)}`);
+}
 export const HOSTS = [
     { value: 'bun', label: 'Bun', hint: 'and compiles to a single binary' },
     { value: 'node', label: 'Node', hint: 'the default everywhere else' },
@@ -132,6 +143,12 @@ export function parseArgs(argv) {
             out.host = assertHost(arg.slice(7));
         else if (arg.startsWith('--compiler='))
             out.compiler = arg.slice(11);
+        else if (arg.startsWith('--validation='))
+            out.validation = assertValidation(arg.slice(13));
+        else if (arg === '--env')
+            out.env = true;
+        else if (arg === '--no-env')
+            out.env = false;
         else if (arg.startsWith('--core='))
             out.core = arg.slice(7);
         else if (arg.startsWith('--backend='))
@@ -183,7 +200,12 @@ export const HELP = `
     --compiler=none|oxc|babel     React Compiler (prompt offers oxc; babel by flag)
     --tailwind / --no-tailwind    include Tailwind
     --lint / --no-lint            include oxlint
+    --validation=zod|valibot|arktype|none
+                                  the schema library; forms, actions and env use it
+    --env / --no-env              typed environment variables (@t3-oss/env-core)
     --source-dir <dir>            where app/ lives (default: src)
+    --backend=<url>               a backend answering host calls — a Go server, say,
+                                  at http://127.0.0.1:8080; writes .env with a secret
     --init                        add to the project here, rather than scaffold
     --core=<spec>                 engine dependency, e.g. file:../rsc-kit/packages/core
     --no-install                  skip installing dependencies

package/dist/templates.d.ts

@@ -23,15 +23,17 @@ export interface Paths {
  */
 export declare function paths(o: Options): Paths;
 /**
- * The config the RSC build runs, which for Laravel is not the app's own.
+ * The config the RSC build runs: the app's own, on every host.
  *
- * A Laravel application already has a vite.config with laravel-vite-plugin in
- * it, and the two cannot share one: both set an input list, an outDir and a
- * hot file, and whichever plugin runs second wins. So the RSC build gets its
- * own file and the scripts name it, rather than an install that quietly breaks
- * the asset pipeline the app was already using.
+ * Laravel used to get a second file, vite.rsc.config.ts, on the reasoning
+ * that laravel-vite-plugin and rscKit() cannot share one - which is true:
+ * laravel-vite-plugin sets base, publicDir, outDir, the input list and the
+ * server origin, and so does this build. But once the renderer owns the
+ * frontend there is nothing left for laravel-vite-plugin to do: no @vite
+ * directive, no public/hot, no Blade asset pipeline. The right answer is
+ * one config with rscKit() in it, which is what the Laravel docs app runs.
  */
-export declare const configFile: (o: Options) => string;
+export declare const configFile: (_o: Options) => string;
 /**
  * The commands, under the names someone would guess.
  *
@@ -112,3 +114,39 @@ export declare function agents(o: Options): string;
  */
 export declare function mcp(): string;
 export declare function readme(o: Options): string;
+/**
+ * Typed environment variables, read once at startup.
+ *
+ * A missing or malformed variable is refused here, with its name, before
+ * anything runs - not as an `undefined` three calls later. Server variables
+ * never reach the browser; a client one has to carry the prefix, and is read
+ * from import.meta.env, which is what Vite exposes there.
+ */
+export declare function env(o: Options): string;
+/**
+ * The process bootstrap, written when the app validates its environment.
+ *
+ * env.ts refuses at import - and where that import happens decides who sees
+ * the refusal. Imported by the first page that needs a variable, a missing
+ * one is reported by that page, to that visitor, after the server said it
+ * was up. Imported here, the generated entry evaluates this file before any
+ * page module and awaits register() before the first request, so a server
+ * with a bad environment does not start. Next names the file the same.
+ */
+export declare function instrumentation(_o: Options): string;
+/**
+ * The two lines that wire a backend: where host calls go, and the secret it
+ * checks. Written when the project has a backend answering them - a Go
+ * server, or anything speaking the contract - so the renderer needs no
+ * configuring in development or in production. A Laravel app has both in
+ * its .env already, under APP_URL.
+ */
+export declare function backendEnv(backend: string, secret: string): string;
+export declare function backendEnvExample(backend: string): string;
+/**
+ * What the backend has to do, said once at the end. Go gets its own, because
+ * the project said it was Go; anything else gets the contract.
+ */
+export declare function backendStep(go: boolean): string;
+/** The example beside it - the one file that is committed. */
+export declare const envExample = "# Copy to .env and fill in. Server variables never reach the browser;\n# a browser-readable one starts with PUBLIC_. The schema is src/env.ts.\n#\n# Not NODE_ENV. Vite sets it - development under `vite`, production under\n# `vite build` - and a value written here overrides that: NODE_ENV=development\n# in .env makes a production build emit React's development JSX runtime,\n# which the production server does not have, and every page fails to render.\n# DATABASE_URL=\n# SESSION_SECRET=\n# PUBLIC_SITE_URL=\n";

package/dist/templates.js

@@ -29,15 +29,17 @@ export function paths(o) {
     };
 }
 /**
- * The config the RSC build runs, which for Laravel is not the app's own.
+ * The config the RSC build runs: the app's own, on every host.
  *
- * A Laravel application already has a vite.config with laravel-vite-plugin in
- * it, and the two cannot share one: both set an input list, an outDir and a
- * hot file, and whichever plugin runs second wins. So the RSC build gets its
- * own file and the scripts name it, rather than an install that quietly breaks
- * the asset pipeline the app was already using.
+ * Laravel used to get a second file, vite.rsc.config.ts, on the reasoning
+ * that laravel-vite-plugin and rscKit() cannot share one - which is true:
+ * laravel-vite-plugin sets base, publicDir, outDir, the input list and the
+ * server origin, and so does this build. But once the renderer owns the
+ * frontend there is nothing left for laravel-vite-plugin to do: no @vite
+ * directive, no public/hot, no Blade asset pipeline. The right answer is
+ * one config with rscKit() in it, which is what the Laravel docs app runs.
  */
-export const configFile = (o) => o.host === 'laravel' ? 'vite.rsc.config.ts' : 'vite.config.ts';
+export const configFile = (_o) => 'vite.config.ts';
 /**
  * The commands, under the names someone would guess.
  *
@@ -48,14 +50,13 @@ export const configFile = (o) => o.host === 'laravel' ? 'vite.rsc.config.ts' : '
  */
 export function scripts(o) {
     if (o.host === 'laravel') {
-        const config = `--config ${configFile(o)}`;
         const actions = 'php artisan rsc:action-manifest';
         return {
             // The ordinary names. A Laravel application already has `dev` and
             // `build`, and init combines rather than replaces — the stock ones run
             // the asset pipeline, and both pipelines belong to `npm run dev`.
-            dev: `${actions} && vite ${config}`,
-            build: `${actions} && vite build ${config}`,
+            dev: `${actions} && vite`,
+            build: `${actions} && vite build`,
             // What the build wrote. There is no server file to start any more.
             start: 'bun .output/server/index.mjs',
         };
@@ -154,6 +155,14 @@ export function packageJson(o) {
     }
     if (o.lint)
         dev['oxlint'] = '^1.81.0';
+    if (o.validation === 'zod')
+        deps['zod'] = '^4.0.0';
+    if (o.validation === 'valibot')
+        deps['valibot'] = '^1.0.0';
+    if (o.validation === 'arktype')
+        deps['arktype'] = '^2.1.0';
+    if (o.env)
+        deps['@t3-oss/env-core'] = '^0.13.0';
     return (JSON.stringify({
         name: o.name,
         type: 'module',
@@ -587,6 +596,16 @@ at build time. That is usually correct — just know that it is the trade.
 \`await connection()\` says "render this per visitor" deliberately, when
 nothing else in the page happens to say it.
 
+## Startup
+
+\`${o.sourceDir}/instrumentation.ts\` runs once before anything else — at
+startup on a server, at the first request on a Worker — and the entry imports
+it before any page. ${o.env
+        ? "It imports \`./env\`, so a missing or malformed variable stops the server from starting rather than reaching a visitor. "
+        : ''}Put once-per-process setup there (\`register()\` may be async, and the first
+render waits for it). Do not import a bootstrap module from pages to get the
+same effect; it depends on nobody forgetting.
+
 ## Data
 
 Fetch in a server component and await it. There is no loader and no
@@ -745,3 +764,144 @@ the ambient declarations. Rewritten every build, and gitignored.
 Docs: https://docs.rsc-kit.dev
 `;
 }
+/**
+ * Typed environment variables, read once at startup.
+ *
+ * A missing or malformed variable is refused here, with its name, before
+ * anything runs - not as an `undefined` three calls later. Server variables
+ * never reach the browser; a client one has to carry the prefix, and is read
+ * from import.meta.env, which is what Vite exposes there.
+ */
+export function env(o) {
+    const lib = {
+        zod: {
+            imp: "import * as z from 'zod'",
+            url: 'z.url()',
+            str: 'z.string().min(1)',
+            opt: "z.enum(['development', 'production', 'test']).default('development')",
+        },
+        valibot: {
+            imp: "import * as v from 'valibot'",
+            url: 'v.pipe(v.string(), v.url())',
+            str: 'v.pipe(v.string(), v.minLength(1))',
+            opt: "v.optional(v.picklist(['development', 'production', 'test']), 'development')",
+        },
+        arktype: {
+            imp: "import { type } from 'arktype'",
+            url: "type('string.url')",
+            str: "type('string > 0')",
+            opt: "type(\"'development' | 'production' | 'test' | undefined\")",
+        },
+    }[o.validation === 'none' ? 'zod' : o.validation];
+    return `${lib.imp}
+import { createEnv } from '@t3-oss/env-core'
+
+// Read once, here, and refused with the variable named when one is missing
+// or wrong - before anything runs, not as an undefined three calls later.
+//
+// Server variables stay on the server. A variable the browser may read has
+// to start with PUBLIC_, and is read from import.meta.env, which is what Vite
+// exposes there. Add a variable: one line in the schema, and every reader is
+// typed.
+export const env = createEnv({
+  server: {
+    NODE_ENV: ${lib.opt},
+    // DATABASE_URL: ${lib.url},
+    // SESSION_SECRET: ${lib.str},
+  },
+  clientPrefix: 'PUBLIC_',
+  client: {
+    // PUBLIC_SITE_URL: ${lib.url},
+  },
+  runtimeEnv: { ...process.env, ...import.meta.env },
+  emptyStringAsUndefined: true,
+  // A build machine without the production variables: SKIP_ENV_VALIDATION=1
+  // builds anyway, and the server that runs the build validates at startup.
+  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+})
+`;
+}
+/**
+ * The process bootstrap, written when the app validates its environment.
+ *
+ * env.ts refuses at import - and where that import happens decides who sees
+ * the refusal. Imported by the first page that needs a variable, a missing
+ * one is reported by that page, to that visitor, after the server said it
+ * was up. Imported here, the generated entry evaluates this file before any
+ * page module and awaits register() before the first request, so a server
+ * with a bad environment does not start. Next names the file the same.
+ */
+export function instrumentation(_o) {
+    return `// Runs once, before anything else: on a server at startup, on a Worker
+// when its first request arrives. The entry imports this file first, so a
+// package configured here is configured before any page module evaluates.
+//
+// env.ts validates on import. Importing it here means a missing variable
+// stops the server from starting rather than reaching a visitor as a page
+// that fails three calls later.
+import './env'
+
+// Anything asynchronous the app needs before its first request - warming a
+// connection, checking a migration - goes here. The first render waits for
+// it. Read environment inside this function, not at the top of the module,
+// if the app deploys to a Worker: a binding is only readable once a request
+// has arrived.
+export async function register() {}
+`;
+}
+/**
+ * The two lines that wire a backend: where host calls go, and the secret it
+ * checks. Written when the project has a backend answering them - a Go
+ * server, or anything speaking the contract - so the renderer needs no
+ * configuring in development or in production. A Laravel app has both in
+ * its .env already, under APP_URL.
+ */
+export function backendEnv(backend, secret) {
+    return `# Where rpc() goes: a backend answering POST /__rsc/host-call. The renderer
+# reads both of these, in development (vite) and in production (the built
+# server). The backend checks the secret on every call; keep it out of git.
+RSC_BACKEND=${backend}
+RSC_HOST_CALL_SECRET=${secret}
+`;
+}
+export function backendEnvExample(backend) {
+    return `# Copy to .env. The backend answering rpc(), and the secret it checks -
+# generate one: openssl rand -base64 32
+RSC_BACKEND=${backend}
+RSC_HOST_CALL_SECRET=
+`;
+}
+/**
+ * What the backend has to do, said once at the end. Go gets its own, because
+ * the project said it was Go; anything else gets the contract.
+ */
+export function backendStep(go) {
+    if (go) {
+        return [
+            'answer host calls from your Go server - go get github.com/rsc-kit/go, then:',
+            '',
+            '    reg := rsckit.NewRegistry()',
+            '    reg.Register("Orders.recent", func(ctx context.Context, args rsckit.Args) (any, error) { … })',
+            '    callback, _ := rsckit.NewCallbackHandler(reg, os.Getenv("RSC_HOST_CALL_SECRET"))',
+            '    mux.Handle("POST /__rsc/host-call", callback)',
+            '',
+            '  A page reads it with await rpc(\'Orders.recent\'). https://rsc-kit.dev/hosts/go',
+        ].join('\n');
+    }
+    return [
+        'answer POST /__rsc/host-call from your backend, checking X-Rsc-Host-Secret',
+        '  against RSC_HOST_CALL_SECRET in .env. The contract: https://rsc-kit.dev/hosts/your-own-backend',
+    ].join('\n');
+}
+/** The example beside it - the one file that is committed. */
+export const envExample = `# Copy to .env and fill in. Server variables never reach the browser;
+# a browser-readable one starts with PUBLIC_. The schema is src/env.ts.
+#
+# Not NODE_ENV. Vite sets it - development under \`vite\`, production under
+# \`vite build\` - and a value written here overrides that: NODE_ENV=development
+# in .env makes a production build emit React's development JSX runtime,
+# which the production server does not have, and every page fails to render.
+# DATABASE_URL=
+# SESSION_SECRET=
+# PUBLIC_SITE_URL=
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rsc-kit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "type": "module",
   "description": "Scaffold an RSC app on Bun, Hono, Elysia or Node.",
   "bin": {