create-rsc-kit 0.3.0 → 0.4.0

package/dist/index.js

@@ -18,7 +18,7 @@ if (flags.help) {
     stdout.write(HELP);
     exit(0);
 }
-const unattended = flags.host !== undefined;
+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)));
 const options = await collect();
@@ -58,7 +58,7 @@ async function collect() {
         return {
             dir: resolve(dir),
             name: basename(dir),
-            host: flags.host,
+            host: flags.host ?? 'bun',
             compiler: flags.compiler ?? 'none',
             tailwind: flags.tailwind ?? true,
             lint: flags.lint ?? true,
@@ -122,7 +122,7 @@ function write(o) {
         ['package.json', t.packageJson(o)],
         ['tsconfig.json', t.tsconfig(o)],
         ['vite.config.ts', t.viteConfig(o)],
-        [t.serverFile(o.host), t.server(o.host)],
+        [t.serverFile(o.host), t.server(o)],
         ['.gitignore', t.gitignore],
         ['README.md', t.readme(o)],
         ['src/app/layout.tsx', t.layout(o)],

package/dist/init.d.ts

@@ -2,6 +2,8 @@ import type { Host, Options } from './options.js';
 export interface Detected {
     /** What the project's package.json says it already depends on. */
     deps: Record<string, string>;
+    /** A Laravel application: artisan and a composer manifest, both. */
+    laravel: boolean;
     host: Host | null;
     sourceDir: string | null;
     viteConfig: string | null;

package/dist/init.js

@@ -28,9 +28,13 @@ export function detect(dir) {
         ...(packageJson.dependencies ?? {}),
         ...(packageJson.devDependencies ?? {}),
     };
-    let host = null;
+    // Both files, not either: `artisan` alone is a name anything could use, and
+    // a composer.json alone is any PHP project. Together they are Laravel, and
+    // the check costs nothing to be sure about.
+    const laravel = existsSync(join(dir, 'artisan')) && existsSync(join(dir, 'composer.json'));
+    let host = laravel ? 'laravel' : null;
     for (const [pkg, value] of Object.entries(HOST_PACKAGES)) {
-        if (deps[pkg])
+        if (!laravel && deps[pkg])
             host = value;
     }
     // No framework named, so it comes down to which runtime's types are here.
@@ -40,8 +44,14 @@ export function detect(dir) {
         host = deps['@types/node'] && !deps['@types/bun'] ? 'node' : 'bun';
     return {
         deps,
+        laravel,
         host,
-        sourceDir: ['src', 'app', 'resources/js'].find((d) => existsSync(join(dir, d))) ?? null,
+        // 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.
+        sourceDir: laravel
+            ? 'resources/js/rsc'
+            : ['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),
         hasTailwind: Boolean(deps.tailwindcss),
@@ -49,15 +59,36 @@ export function detect(dir) {
         packageJson,
     };
 }
+/**
+ * The major a range starts at, or null when it is not one.
+ *
+ * Deliberately crude — `file:` specs, `latest`, `workspace:*` and git urls all
+ * come back null and are left alone. It only has to answer one question, and
+ * only where the answer is unambiguous.
+ */
+function major(range) {
+    const match = /^\D*(\d+)\./.exec(range);
+    return match ? Number(match[1]) : null;
+}
 /**
  * Add the dependencies the engine needs, without touching versions already
  * chosen. A project on React 19.3 does not want to be pinned back to ours.
+ *
+ * Except when what is already there is too OLD, which is not the same thing
+ * and is the common case here: every Laravel application ships a Vite, and at
+ * the time of writing none of them ship Vite 8. Leaving it silently is how an
+ * install ends in a build failing on a plugin API that does not exist yet —
+ * an error naming neither Vite nor this package. So a major below what the
+ * engine needs is reported as an edit to make, and nothing is upgraded on
+ * someone's behalf: a Vite major is their decision, and it moves their own
+ * asset pipeline too.
  */
 function mergeDependencies(o, found) {
     const pkg = found.packageJson;
     const wanted = JSON.parse(t.packageJson(o));
     const steps = [];
     const added = [];
+    const tooOld = [];
     for (const [field, incoming] of [
         ['dependencies', wanted.dependencies],
         ['devDependencies', wanted.devDependencies],
@@ -65,8 +96,14 @@ function mergeDependencies(o, found) {
         const current = pkg[field] ?? {};
         for (const [name, range] of Object.entries(incoming)) {
             // Already declared anywhere: leave it exactly as it is.
-            if (found.deps[name])
+            if (found.deps[name]) {
+                const have = major(found.deps[name]);
+                const want = major(range);
+                if (have !== null && want !== null && have < want) {
+                    tooOld.push(`${name} ${found.deps[name]} → ${range}`);
+                }
                 continue;
+            }
             current[name] = range;
             added.push(name);
         }
@@ -77,56 +114,137 @@ function mergeDependencies(o, found) {
     steps.push(added.length > 0
         ? { kind: 'merged', what: 'package.json', detail: `added ${added.join(', ')}` }
         : { kind: 'skipped', what: 'package.json dependencies', detail: 'everything needed is already here' });
+    if (tooOld.length > 0) {
+        steps.push({
+            kind: 'manual',
+            what: 'versions already here that the engine cannot build with',
+            detail: `left alone — upgrade them yourself, the build fails on the old ones:\n      ` +
+                tooOld.join('\n      '),
+        });
+    }
     return steps;
 }
 /**
- * Scripts, but never over one that exists.
+ * Laravel's own scripts, exactly as the framework ships them.
+ *
+ * Matched by value, not by name. `dev` meaning `vite` is a script nobody
+ * chose; `dev` meaning anything else is somebody's work and is not ours to
+ * reason about.
+ */
+const STOCK = {
+    dev: ['vite'],
+    build: ['vite build'],
+};
+/**
+ * The two pipelines, under one name.
  *
- * `dev` and `build` are the two most likely to already mean something, and
- * quietly replacing either is how a tool loses someone's trust permanently.
+ * `npm run dev` already means the asset pipeline, and after this it has to
+ * mean the renderer too — so it means both. Anything else asks a Laravel
+ * developer to learn a second command for the thing they already have a
+ * command for, and the one they know would silently stop being enough.
+ *
+ * Sequential for a build because it has to be — the outputs are independent
+ * but a failure in either should stop the deploy. Parallel for dev because
+ * both are long-lived servers.
+ */
+function combine(name, theirs, ours) {
+    return name === 'dev'
+        ? `concurrently -k -n assets,rsc -c blue,magenta "${theirs}" "${ours}"`
+        : `${theirs} && ${ours}`;
+}
+/**
+ * Scripts, never over one that somebody wrote.
+ *
+ * Three outcomes. A name that is free is taken. A name holding the framework's
+ * own script is combined, so the command keeps doing what it did and starts
+ * doing this as well. A name holding anything else is left completely alone,
+ * and the RSC command goes to `rsc:<name>` with the reason reported — a tool
+ * that quietly replaces a working build script loses someone's trust
+ * permanently, and it only has to be wrong once.
  */
 function mergeScripts(o, found) {
     const pkg = found.packageJson;
     const scripts = pkg.scripts ?? {};
-    const wanted = JSON.parse(t.packageJson(o)).scripts;
+    const wanted = t.scripts(o);
     const added = [];
-    const conflicts = [];
+    const combined = [];
+    const renamed = [];
+    let needsConcurrently = false;
     for (const [name, command] of Object.entries(wanted)) {
-        if (scripts[name] === undefined) {
+        const existing = scripts[name];
+        if (existing === undefined) {
             scripts[name] = command;
             added.push(name);
+            continue;
         }
-        else if (scripts[name] !== command) {
-            conflicts.push(`${name}: ${command}`);
+        if (existing === command)
+            continue;
+        if (STOCK[name]?.includes(existing.trim())) {
+            scripts[name] = combine(name, existing.trim(), command);
+            combined.push(name);
+            needsConcurrently ||= name === 'dev';
+            continue;
         }
+        const fallback = `rsc:${name}`;
+        if (scripts[fallback] === undefined)
+            scripts[fallback] = command;
+        renamed.push(`${name} is yours, so this one is ${fallback}`);
     }
     pkg.scripts = scripts;
     const steps = [];
     if (added.length > 0)
         steps.push({ kind: 'merged', what: 'scripts', detail: added.join(', ') });
-    if (conflicts.length > 0) {
+    if (combined.length > 0) {
+        steps.push({
+            kind: 'merged',
+            what: combined.join(' and '),
+            detail: 'now runs the asset pipeline AND the renderer',
+        });
+    }
+    // Declared here rather than in the template, because whether it is needed
+    // depends on what was already in package.json. Laravel ships it for its own
+    // `composer run dev`, so this is usually a no-op.
+    if (needsConcurrently && !found.deps.concurrently) {
+        const dev = pkg.devDependencies ?? {};
+        dev.concurrently = '^9.0.0';
+        pkg.devDependencies = Object.fromEntries(Object.entries(dev).sort(([a], [b]) => a.localeCompare(b)));
+    }
+    if (renamed.length > 0) {
         steps.push({
             kind: 'manual',
-            what: 'scripts you already have',
-            detail: `left alone — add these yourself if you want them:\n      ${conflicts.join('\n      ')}`,
+            what: 'scripts you wrote yourself',
+            detail: `left alone:\n      ${renamed.join('\n      ')}`,
         });
     }
     return steps;
 }
 /** The plugin entry, written if there is no config and printed if there is. */
 function viteConfig(o, found, dir) {
-    if (found.viteConfig === null) {
-        writeFileSync(join(dir, 'vite.config.ts'), t.viteConfig(o));
-        return [{ kind: 'wrote', what: 'vite.config.ts' }];
+    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;
+    if (existing === null) {
+        writeFileSync(join(dir, file), t.viteConfig(o));
+        return [{ kind: 'wrote', what: file }];
     }
+    const p = t.paths(o);
+    const shown = [
+        `sourceDir: '${p.sourceDir}'`,
+        `outDir: '${p.outDir}'`,
+        `assetsDir: '${p.assetsDir}'`,
+        ...(p.assetsUrl ? [`assetsUrl: '${p.assetsUrl}'`] : []),
+        ...(p.hotFile ? [`hotFile: '${p.hotFile}'`] : []),
+    ].join(', ');
     return [
         {
             kind: 'manual',
-            what: found.viteConfig,
+            what: existing,
             detail: `add the plugin — it must come before any react() layer:\n` +
                 `      import { rscRoutes } from '@rsc-kit/core/vite'\n\n` +
                 `      plugins: [\n` +
-                `        rscRoutes({ sourceDir: '${o.sourceDir}', outDir: 'build', assetsDir: 'build/public' }),\n` +
+                `        rscRoutes({ ${shown} }),\n` +
                 `        …whatever you already have\n` +
                 `      ]`,
         },
@@ -143,14 +261,14 @@ function server(o, dir) {
                 detail: 'left alone. Mount the handler in it — anything the route table does not\n' +
                     '      claim comes back null, so your own routes still win:\n\n' +
                     t
-                        .server(o.host)
+                        .server(o)
                         .split('\n')
                         .map((line) => '      ' + line)
                         .join('\n'),
             },
         ];
     }
-    writeFileSync(join(dir, file), t.server(o.host));
+    writeFileSync(join(dir, file), t.server(o));
     return [{ kind: 'wrote', what: file }];
 }
 /** The route tree, only where there is not one already. */
@@ -179,17 +297,39 @@ function routes(o, dir) {
     }
     return steps;
 }
+/**
+ * A tsconfig, for a project that has none.
+ *
+ * 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.
+ */
+function tsconfig(o, found, dir) {
+    if (found.hasTypeScript) {
+        return [{ kind: 'skipped', what: 'tsconfig.json', detail: 'already here' }];
+    }
+    writeFileSync(join(dir, 'tsconfig.json'), t.tsconfig(o));
+    return [{ kind: 'wrote', what: 'tsconfig.json' }];
+}
 /** 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}`);
+    const p = t.paths(o);
+    // Everything the build writes. On Laravel that is three separate places —
+    // the bundles, the browser assets under public/, and the hot file — and a
+    // committed hot file is the worst of them: it points every other machine at
+    // a dev server that is not running there.
+    const all = [p.outDir, p.assetsDir, ...(p.hotFile ? [p.hotFile] : [])];
+    const outputs = all.filter((path) => !all.some((other) => other !== path && path.startsWith(other + '/')));
     const current = existsSync(path) ? readFileSync(path, 'utf-8') : '';
-    const missing = generated.filter((line) => !current.includes(line));
+    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# Written into the source dir by the RSC build, every run.\n' +
-        missing.join('\n') + '\nbuild\n');
+        '\n# The RSC build: rewritten into the source dir every run, and written out.\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. */
@@ -198,6 +338,7 @@ export function initialise(o, found, dir) {
         ...routes(o, dir),
         ...viteConfig(o, found, dir),
         ...server(o, dir),
+        ...tsconfig(o, found, dir),
         ...gitignore(o, dir),
         ...mergeDependencies(o, found),
         ...mergeScripts(o, found),
@@ -215,6 +356,8 @@ const INIT_HELP = `
   Options
     --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
     --compiler=…         none | oxc | babel
     --tailwind           add Tailwind as well
     -y, --yes            accept what was detected, ask nothing
@@ -242,11 +385,15 @@ export async function runInit(args) {
     }
     const flags = parseArgs(args);
     const found = detect(dir);
-    const unattended = args.includes('-y') || args.includes('--yes') || flags.host !== undefined;
+    const unattended = flags.yes === true || flags.host !== undefined;
     stdout.write(`\n${bold('Adding rsc-kit')} ${dim(dir)}\n\n`);
     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\n`);
+    stdout.write(`  ${dim('react')}       ${found.hasReact ? 'already here' : 'will be added'}\n`);
+    if (found.host === 'laravel') {
+        stdout.write(`  ${dim('backend')}     ${flags.backend ?? 'http://localhost'}\n`);
+    }
+    stdout.write('\n');
     let compiler = flags.compiler ?? 'none';
     let tailwind = flags.tailwind ?? found.hasTailwind;
     if (!unattended) {
@@ -272,6 +419,7 @@ export async function runInit(args) {
         install: false,
         git: false,
         core: flags.core ?? publishedCore(),
+        backend: flags.backend,
     };
     const steps = initialise(options, found, dir);
     const mark = { wrote: cyan('+'), merged: cyan('~'), manual: bold('!'), skipped: dim('·') };
@@ -280,7 +428,11 @@ export async function runInit(args) {
         stdout.write(`  ${mark[step.kind]} ${step.what}${step.detail ? dim('  — ' + step.detail) : ''}\n`);
     }
     const manual = steps.filter((s) => s.kind === 'manual');
-    stdout.write(manual.length > 0
-        ? `\n${bold('Then, by hand:')} the edits marked ! above are in files you already had.\n\n`
+    if (manual.length > 0) {
+        stdout.write(`\n${bold('Then, by hand:')} the edits marked ! above are in files you already had.\n\n`);
+        return;
+    }
+    stdout.write(options.host === 'laravel'
+        ? `\n  ${cyan('npm install')}, then ${cyan('npm run rsc:dev')} — and open the app at its own domain.\n\n`
         : `\n  ${cyan('bun install')} and you are ready.\n\n`);
 }

package/dist/options.d.ts

@@ -1,4 +1,4 @@
-export type Host = 'bun' | 'hono' | 'elysia' | 'node';
+export type Host = 'bun' | 'hono' | 'elysia' | 'node' | 'laravel';
 export type Compiler = 'none' | 'oxc' | 'babel';
 export interface Options {
     dir: string;
@@ -9,11 +9,24 @@ export interface Options {
     lint: boolean;
     /** Where the app/ route tree lives, relative to the project. */
     sourceDir: string;
+    /**
+     * Where host calls go, for a backed host. Laravel's own url, so a server
+     * component's rpc() reaches the application it is rendering for.
+     */
+    backend?: string;
     install: boolean;
     git: boolean;
     /** What to depend on for the engine. A path makes a local checkout testable. */
     core: string;
 }
+/**
+ * What the prompt offers, which is not every Host.
+ *
+ * `laravel` is missing on purpose: it is never scaffolded, only added to an
+ * application that already exists — so init detects it and nothing asks. A
+ * question whose only right answer is "the framework I am already in" is a
+ * question with a wrong answer available.
+ */
 export declare const HOSTS: {
     value: Host;
     label: string;
@@ -51,9 +64,18 @@ export declare function publishedCore(fromDir?: string): string;
  * sibling and the range is right.
  */
 export declare function defaultCore(fromDir: string): string;
+/**
+ * The flags, with --yes as its own answer rather than a host.
+ *
+ * It used to set `host = 'bun'`, because both entry points read "a host was
+ * named" as "do not prompt". That silently overrode detection: `rsc-kit init
+ * -y` in a Hono project — or a Laravel one — generated a Bun server for it,
+ * having detected the right answer and then thrown it away.
+ */
 export declare function parseArgs(argv: string[]): Partial<Options> & {
     help?: boolean;
     init?: boolean;
+    yes?: boolean;
 };
 export declare function assertUsableName(name: string): void;
 /**

package/dist/options.js

@@ -1,6 +1,14 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+/**
+ * What the prompt offers, which is not every Host.
+ *
+ * `laravel` is missing on purpose: it is never scaffolded, only added to an
+ * application that already exists — so init detects it and nothing asks. A
+ * question whose only right answer is "the framework I am already in" is a
+ * question with a wrong answer available.
+ */
 export const HOSTS = [
     { value: 'bun', label: 'Bun.serve', hint: 'no framework, fastest to start' },
     { value: 'hono', label: 'Hono', hint: 'also what a Worker or Deno would use' },
@@ -78,13 +86,21 @@ export function defaultCore(fromDir) {
     }
     return publishedCore();
 }
+/**
+ * The flags, with --yes as its own answer rather than a host.
+ *
+ * It used to set `host = 'bun'`, because both entry points read "a host was
+ * named" as "do not prompt". That silently overrode detection: `rsc-kit init
+ * -y` in a Hono project — or a Laravel one — generated a Bun server for it,
+ * having detected the right answer and then thrown it away.
+ */
 export function parseArgs(argv) {
     const out = {};
     for (const arg of argv) {
         if (arg === '--help' || arg === '-h')
             out.help = true;
         else if (arg === '--yes' || arg === '-y')
-            out.host ??= 'bun';
+            out.yes = true;
         else if (arg === '--no-install')
             out.install = false;
         else if (arg === '--no-git')
@@ -107,6 +123,8 @@ export function parseArgs(argv) {
             out.compiler = arg.slice(11);
         else if (arg.startsWith('--core='))
             out.core = arg.slice(7);
+        else if (arg.startsWith('--backend='))
+            out.backend = arg.slice(10);
         else if (!arg.startsWith('-'))
             out.dir ??= arg;
     }

package/dist/templates.d.ts

@@ -1,10 +1,51 @@
 import type { Host, Options } from './options.js';
+export interface Paths {
+    /** Where the app/ route tree lives. */
+    sourceDir: string;
+    /** Where the bundles land. The server imports the rsc one from here. */
+    outDir: string;
+    /** Where browser assets are written. */
+    assetsDir: string;
+    /** The url they are served under, when it is not Vite's default. */
+    assetsUrl?: string;
+    /** Written while the dev server runs, for a backend that has to find it. */
+    hotFile?: string;
+}
+/**
+ * Where this host's build writes, and where its server reads.
+ *
+ * One function because the two have to agree and nothing checks that they do:
+ * an assetsDir the server does not serve 404s every asset while every page
+ * still renders, so the page looks right and nothing hydrates. Laravel's
+ * differ from the rest because public/ is already the browser's root and
+ * bootstrap/ is already where a Laravel app keeps generated code.
+ */
+export declare function paths(o: Options): Paths;
+/**
+ * The config the RSC build runs, which for Laravel is not the app's own.
+ *
+ * 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.
+ */
+export declare const configFile: (o: Options) => string;
+/**
+ * The commands, under the names someone would guess.
+ *
+ * `dev` and `build`, even on Laravel where both are already taken. What to do
+ * about that is init's decision and not this one — see mergeScripts, which
+ * combines with the stock scripts and only steps aside for a script somebody
+ * wrote themselves.
+ */
+export declare function scripts(o: Options): Record<string, string>;
 export declare function packageJson(o: Options): string;
 /** One server per app, so it needs no qualifier. */
 export declare const serverFile: (_host: Host) => string;
 export declare function viteConfig(o: Options): string;
 export declare const tsconfig: (o: Options) => string;
-export declare function server(host: Host): string;
+export declare function server(o: Options): string;
 export declare function layout(o: Options): string;
 export declare function page(o: Options): string;
 export declare function counter(o: Options): string;

package/dist/templates.js

@@ -4,6 +4,78 @@
 // each other — the compiler changes vite.config, Tailwind changes it and the
 // layout — and a template directory would need one copy per combination.
 const PORT = 3000;
+/**
+ * Where this host's build writes, and where its server reads.
+ *
+ * One function because the two have to agree and nothing checks that they do:
+ * an assetsDir the server does not serve 404s every asset while every page
+ * still renders, so the page looks right and nothing hydrates. Laravel's
+ * differ from the rest because public/ is already the browser's root and
+ * bootstrap/ is already where a Laravel app keeps generated code.
+ */
+export function paths(o) {
+    if (o.host !== 'laravel') {
+        return { sourceDir: o.sourceDir, outDir: 'build', assetsDir: 'build/public' };
+    }
+    return {
+        sourceDir: o.sourceDir,
+        outDir: 'bootstrap/rsc/vite',
+        assetsDir: 'public/build/rsc-vite',
+        assetsUrl: '/build/rsc-vite/',
+        hotFile: 'public/rsc-hot',
+    };
+}
+/**
+ * The config the RSC build runs, which for Laravel is not the app's own.
+ *
+ * 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.
+ */
+export const configFile = (o) => o.host === 'laravel' ? 'vite.rsc.config.ts' : 'vite.config.ts';
+/**
+ * The commands, under the names someone would guess.
+ *
+ * `dev` and `build`, even on Laravel where both are already taken. What to do
+ * about that is init's decision and not this one — see mergeScripts, which
+ * combines with the stock scripts and only steps aside for a script somebody
+ * wrote themselves.
+ */
+export function scripts(o) {
+    const run = o.host === 'node' ? 'node' : 'bun run';
+    const p = paths(o);
+    if (o.host === 'laravel') {
+        const config = `--config ${configFile(o)}`;
+        // The build cannot discover the app's server actions — reflection through
+        // Composer's autoloader is the only thing that sees what a class inherits
+        // from its parents and traits — so PHP writes them out first and the
+        // plugin reads the file. Part of the command rather than a step to
+        // remember: a stale map names a method that has since been renamed, and
+        // nothing fails until the browser calls it.
+        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`.
+            // Only a script somebody actually wrote gets left alone, and then the
+            // RSC one takes an `rsc:` name and says so.
+            dev: `${actions} && vite ${config}`,
+            build: `${actions} && vite build ${config}`,
+            start: `${run} ${serverFile(o.host)}`,
+        };
+    }
+    return {
+        // Vite serves it: modules are re-evaluated on edit, and adding a
+        // page restarts to pick up the new route table. Nothing is prebuilt,
+        // so there is no NODE_ENV to keep in step with a build.
+        dev: 'vite',
+        build: 'vite build',
+        start: `${run} ${serverFile(o.host)}`,
+        prerender: `rsc-kit prerender --out ${p.outDir}`,
+    };
+}
 export function packageJson(o) {
     const deps = {
         '@rsc-kit/core': o.core,
@@ -45,19 +117,12 @@ export function packageJson(o) {
     }
     if (o.lint)
         dev['oxlint'] = '^1.81.0';
-    const run = o.host === 'node' ? 'node' : 'bun run';
     return (JSON.stringify({
         name: o.name,
         type: 'module',
         private: true,
         scripts: {
-            // Vite serves it: modules are re-evaluated on edit, and adding a
-            // page restarts to pick up the new route table. Nothing is prebuilt,
-            // so there is no NODE_ENV to keep in step with a build.
-            dev: 'vite',
-            build: 'vite build',
-            start: `${run} ${serverFile(o.host)}`,
-            prerender: 'rsc-kit prerender --out build',
+            ...scripts(o),
             typecheck: 'tsc --noEmit',
             ...(o.lint
                 ? { lint: 'oxlint src --fix', 'lint:check': 'oxlint src --deny-warnings' }
@@ -81,10 +146,20 @@ export function viteConfig(o) {
     if (o.tailwind)
         imports.push("import tailwindcss from '@tailwindcss/vite'");
     imports.push("import { rscRoutes } from '@rsc-kit/core/vite'");
+    const p = paths(o);
+    // Every path the build writes to, and the two the server has to agree with.
+    // Written out rather than defaulted so they are editable in one place — and
+    // so the pair that has no error case, assetsDir and assetsUrl, is visible
+    // together.
+    const options = [
+        `sourceDir: '${p.sourceDir}'`,
+        `outDir: '${p.outDir}'`,
+        `assetsDir: '${p.assetsDir}'`,
+        ...(p.assetsUrl ? [`assetsUrl: '${p.assetsUrl}'`] : []),
+        ...(p.hotFile ? [`hotFile: '${p.hotFile}'`] : []),
+    ];
     plugins.push(`rscRoutes({
-      sourceDir: 'src',
-      outDir: 'build',
-      assetsDir: 'build/public',
+      ${options.join(',\n      ')},
     })`);
     plugins.push(o.compiler === 'oxc' ? 'react({ compiler: true })' : 'react()');
     if (o.compiler === 'babel')
@@ -131,7 +206,95 @@ import { assetsFrom, prerenderedFrom } from '@rsc-kit/core/files'
 // bundle, so this server is production because it was built that way — not
 // because whoever started it remembered to say so.
 import * as engine from './build/dist/rsc/index.js'`;
-export function server(host) {
+/**
+ * The renderer for an app whose data lives in PHP.
+ *
+ * Different in kind from the others, not just in wiring: those servers ARE the
+ * application, and this one renders for an application it talks to. Every
+ * rpc() a server component makes leaves this process as a POST carrying the
+ * visitor's own cookie, so the session, the user and the authorization are
+ * Laravel's — this side holds no database connection and no session.
+ *
+ * Only production runs it. In development `vite` is the renderer, and Laravel
+ * finds it through the hot file.
+ */
+function backedServer(o) {
+    const p = paths(o);
+    const backend = o.backend ?? 'http://localhost';
+    return `// The renderer for this app.
+//
+// It owns routing, rendering, prerendered pages and assets. Laravel owns the
+// data: every rpc() a server component makes arrives there as a POST, with
+// this visitor's cookie, and comes back as JSON.
+//
+// Run it beside Laravel:
+//   bun server.ts
+//
+// Both processes need the same RSC_HOST_CALL_SECRET. Nothing else is shared.
+
+import { createBackedHandler } from '@rsc-kit/core/serve'
+import * as engine from './${p.outDir}/dist/rsc/index.js'
+
+const secret = process.env.RSC_HOST_CALL_SECRET
+// Where host calls go: the application this is rendering for.
+const backend = process.env.RSC_BACKEND ?? '${backend}'
+const port = Number(process.env.RSC_RENDERER_PORT ?? 5173)
+
+// Refused rather than defaulted. An empty secret is a host-call endpoint that
+// answers to anyone who can reach it, and it would fail nowhere until then.
+if (!secret) {
+  console.error('RSC_HOST_CALL_SECRET must match the one Laravel is configured with.')
+  process.exit(1)
+}
+
+const handle = createBackedHandler({
+  engine,
+  // The browser's root, and the prefix the build serves assets under. Passing
+  // the asset folder itself 404s every asset while every page still renders —
+  // so the page looks right and nothing hydrates.
+  assetsDir: 'public',
+  assetsPrefix: '${p.assetsUrl}',
+  // Where the build's prerender writes.
+  prerenderedDir: '${p.outDir}/static',
+  hostCall: {
+    endpoint: \`\${backend}/__rsc/host-call\`,
+    secret,
+  },
+  // Compared by the client on every navigation, which falls back to a full
+  // load when it changes. Without one a browser keeps talking to a deployment
+  // that no longer exists.
+  version: process.env.RSC_BUILD_VERSION,
+
+  // A page reading \`params\` gets its url params from the engine; the query
+  // string is merged in here, because a page asking for \`params.q\` should get
+  // it whether it arrived in the path or after the ?.
+  //
+  // Read from the url rather than fetched: a page needing more than the
+  // request carries — a loaded record, a tenant — asks for it with a host
+  // call, because this process has no database.
+  props: (match, request) => ({
+    ...match.params,
+    ...Object.fromEntries(new URL(request.url).searchParams),
+  }),
+})
+
+Bun.serve({
+  port,
+  // Named explicitly. The default binds IPv6 only on some machines, so the
+  // renderer answers on localhost and ::1 but not on 127.0.0.1 — which reads
+  // as the process being down.
+  hostname: process.env.RSC_RENDERER_HOST ?? '127.0.0.1',
+  idleTimeout: 60,
+  fetch: async (request) => (await handle(request)) ?? new Response('Not found', { status: 404 }),
+})
+
+console.log(\`renderer on http://127.0.0.1:\${port}, calling \${backend}\`)
+`;
+}
+export function server(o) {
+    const host = o.host;
+    if (host === 'laravel')
+        return backedServer(o);
     if (host === 'bun') {
         return `${IMPORTS}
 

package/package.json

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