solidjs · birkskyum · Aug 25, 2026 · Aug 25, 2026
diff --git a/.changeset/calm-cats-build.md b/.changeset/calm-cats-build.md
@@ -0,0 +1,9 @@
+---
+'@solidjs/vite-plugin': patch
+---
+
+Rename the plugin-managed application option from `start` to `app` and the
+root component field from `start.app` to `app.root`. Explicit entries now use
+`app.entries.client` and `app.entries.server`, and `errorBoundary` is renamed
+to `productionErrorBoundary`. `StartOptions` is now `AppOptions`. The typed
+`env` option is now top-level and can be used without app mode.
diff --git a/README.md b/README.md
diff --git a/examples/start-client/package.json → examples/app-client/package.json b/examples/start-client/package.json → examples/app-client/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "example-start-client",
+  "name": "example-app-client",
   "private": "true",
   "type": "module",
   "scripts": {

diff --git a/examples/start-client/src/App.css → examples/app-client/src/App.css b/examples/start-client/src/App.css → examples/app-client/src/App.css
diff --git a/examples/start-client/src/App.tsx → examples/app-client/src/App.tsx b/examples/start-client/src/App.tsx → examples/app-client/src/App.tsx
@@ -10,7 +10,7 @@ export default function App() {
 
   return (
     <main>
-      <h1 id="title">Client Start Mode</h1>
+      <h1 id="title">Client App Mode</h1>
       <p id="marker">CLIENT-RENDERED-APP</p>
       <button id="increment" onClick={() => setCount(count() + 1)}>
         Increment

diff --git a/examples/start-client/src/Document.tsx → examples/app-client/src/Document.tsx b/examples/start-client/src/Document.tsx → examples/app-client/src/Document.tsx
@@ -11,7 +11,7 @@ export default function Document(props) {
       <head>
         <meta charset="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>Start Client</title>
+        <title>App Client</title>
         <HydrationScript />
       </head>
       <body>{props.children}</body>

diff --git a/examples/start-client/src/LazySection.tsx → examples/app-client/src/LazySection.tsx b/examples/start-client/src/LazySection.tsx → examples/app-client/src/LazySection.tsx
diff --git a/examples/start-client/test/run.mjs → examples/app-client/test/run.mjs b/examples/start-client/test/run.mjs → examples/app-client/test/run.mjs
@@ -1,6 +1,6 @@
-// Client start-mode fixture test: proves `solid({ start: true })` (the
-// zero-config sugar for `start: {}`, without `ssr: true`) gives a plain
-// Vite app the start-mode conventions (src/App.tsx, optional src/Document.tsx,
+// Client app-mode fixture test: proves `solid({ app: true })` (the
+// zero-config sugar for `app: {}`, without `ssr: true`) gives a plain
+// Vite app the app-mode conventions (src/App.tsx, optional src/Document.tsx,
 // no index.html, no mount file) with client-only rendering:
 //   - dev: every HTML-accepting GET streams the rendered document shell —
 //     WITHOUT the app markup (nothing server-renders the app) — carrying the
@@ -91,7 +91,7 @@ async function fetchHtml(url) {
 }
 
 // ---------------------------------------------------------------------------
-// CDP driver (compact copy of the start-ssr harness's)
+// CDP driver (compact copy of the app-ssr harness's)
 // ---------------------------------------------------------------------------
 async function connectChrome() {
   let target;
@@ -206,7 +206,7 @@ async function runBrowserChecks(mode, origin) {
   const chrome = startProcess(CHROME, [
     '--headless=new',
     `--remote-debugging-port=${CDP_PORT}`,
-    `--user-data-dir=/tmp/start-client-chrome-${mode}`,
+    `--user-data-dir=/tmp/app-client-chrome-${mode}`,
     '--no-first-run',
     '--disable-extensions',
     'about:blank',
@@ -419,7 +419,7 @@ async function flipMode() {
   const chrome = startProcess(CHROME, [
     '--headless=new',
     `--remote-debugging-port=${CDP_PORT}`,
-    `--user-data-dir=/tmp/start-client-chrome-flip`,
+    `--user-data-dir=/tmp/app-client-chrome-flip`,
     '--no-first-run',
     '--disable-extensions',
     'about:blank',
@@ -454,19 +454,31 @@ async function flipMode() {
 // ---------------------------------------------------------------------------
 const requested = process.argv[2];
 const modes = requested ? [requested] : ['dev', 'prod', 'flip'];
-// `start: true` is pure sugar for `start: {}` (this suite's vite.config runs
+// `app: true` is pure sugar for `app: {}` (this suite's vite.config runs
 // on the boolean form): both spellings must construct the identical plugin
-// set, and `start: false` must mean off exactly like omission.
+// set, and `app: false` must mean off exactly like omission.
 {
   const { default: solid } = await import('@solidjs/vite-plugin');
   const names = (opts) => solid(opts).map((p) => p.name).join(',');
   record(
     'config',
     'sugar',
-    'start: true constructs the same plugins as start: {}',
-    names({ start: true }) === names({ start: {} }) &&
-      names({ start: true }) !== names({}) &&
-      names({ start: false }) === names({}),
+    'app: true constructs the same plugins as app: {}',
+    names({ app: true }) === names({ app: {} }) &&
+      names({ app: true }) !== names({}) &&
+      names({ app: false }) === names({}),
+  );
+  let migrationError = '';
+  try {
+    names({ start: true });
+  } catch (error) {
+    migrationError = String(error);
+  }
+  record(
+    'config',
+    'migration',
+    'start option reports the app replacement',
+    migrationError.includes('`start` has been renamed to `app`'),
   );
 }
 try {

diff --git a/examples/start-client/tsconfig.json → examples/app-client/tsconfig.json b/examples/start-client/tsconfig.json → examples/app-client/tsconfig.json
diff --git a/examples/start-client/vite.config.ts → examples/app-client/vite.config.ts b/examples/start-client/vite.config.ts → examples/app-client/vite.config.ts
@@ -1,9 +1,9 @@
 import { defineConfig } from 'vite';
 import solidPlugin from '@solidjs/vite-plugin';
 
-// Client start mode, zero-config spelling: `start: true` (sugar for
-// `start: {}` — both mean the identical start mode with defaults) opts
-// into the start-mode conventions, and the `ssr` boolean (false/omitted here)
+// Client app mode, zero-config spelling: `app: true` (sugar for
+// `app: {}` — both mean the identical app mode with defaults) opts
+// into the app-mode conventions, and the `ssr` boolean (false/omitted here)
 // makes the app client-rendered. No index.html, no mount file, no server
 // output: src/App.tsx is the app, src/Document.tsx (optional) is the shell.
 // Dev streams the rendered shell for every HTML GET (history-fallback
@@ -14,7 +14,7 @@ import solidPlugin from '@solidjs/vite-plugin';
 //
 // SOLID_FLIP_SSR=1 flips the one boolean (test/run.mjs's flip mode): the
 // identical app SSRs and hydrates with zero source changes. All suite modes
-// run on the boolean `start: true` form, covering the sugar end to end.
+// run on the boolean `app: true` form, covering the sugar end to end.
 export default defineConfig({
-  plugins: [solidPlugin({ start: true, ssr: !!process.env.SOLID_FLIP_SSR })],
+  plugins: [solidPlugin({ app: true, ssr: !!process.env.SOLID_FLIP_SSR })],
 });
diff --git a/examples/start-ssr-external/LazyOutside.tsx → examples/app-ssr-external/LazyOutside.tsx b/examples/start-ssr-external/LazyOutside.tsx → examples/app-ssr-external/LazyOutside.tsx
@@ -1,5 +1,5 @@
-// Lives OUTSIDE the start-ssr example's Vite root (its asset key is
-// `../start-ssr-external/LazyOutside.tsx`) — the sibling-workspace-package
+// Lives OUTSIDE the app-ssr example's Vite root (its asset key is
+// `../app-ssr-external/LazyOutside.tsx`) — the sibling-workspace-package
 // shape. Regression fixture for dev SSR lazy asset URLs (#298): a
 // root-external key can't be served as `"/" + key` (`/../…` normalizes
 // wrong in the browser); it needs Vite's `/@fs/` URL on the resolved

diff --git a/examples/start-ssr/package.json → examples/app-ssr/package.json b/examples/start-ssr/package.json → examples/app-ssr/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "example-start-ssr",
+  "name": "example-app-ssr",
   "private": "true",
   "type": "module",
   "scripts": {

diff --git a/examples/start-ssr/server.js → examples/app-ssr/server.js b/examples/start-ssr/server.js → examples/app-ssr/server.js
@@ -1,4 +1,4 @@
-// The entire production server for an SSR start-mode app: static client assets
+// The entire production server for an SSR app-mode app: static client assets
 // plus one import — the built server bundle's `handleRequest`, an
 // adapter-agnostic web `Request -> Response` handler that streams the SSR
 // render, resolves hashed client assets through the build manifest, and

diff --git a/examples/start-ssr/src/App.css → examples/app-ssr/src/App.css b/examples/start-ssr/src/App.css → examples/app-ssr/src/App.css
diff --git a/examples/start-ssr/src/App.tsx → examples/app-ssr/src/App.tsx b/examples/start-ssr/src/App.tsx → examples/app-ssr/src/App.tsx
@@ -1,4 +1,4 @@
-// The entire app the user writes for SSR start mode: a plain content component
+// The entire app the user writes for SSR app mode: a plain content component
 // (no <html>, no HydrationScript, no entries — the plugin's generated
 // document shell provides all of that). Exercises, for test/run.mjs:
 // - hydration + client interactivity (the counter),
@@ -31,7 +31,7 @@ const OnlyClient = clientOnly(() => import('./ClientOnlyWidget'));
 // - a module outside the Vite root — its dev URL must be a base-prefixed
 //   /@fs/ URL, not "/../…" (#298).
 const LazyQuery = lazy(() => import('./QueryLazy.tsx?variant=a'));
-const LazyOutside = lazy(() => import('../../start-ssr-external/LazyOutside'));
+const LazyOutside = lazy(() => import('../../app-ssr-external/LazyOutside'));
 
 function LazyAssetsSection() {
   return (
@@ -134,7 +134,7 @@ export default function App() {
 
   return (
     <main>
-      <h1 id="title">SSR Start Mode</h1>
+      <h1 id="title">SSR App Mode</h1>
       <button id="increment" onClick={() => setCount(count() + 1)}>
         count
       </button>

diff --git a/examples/start-ssr/src/ClientOnlyWidget.tsx → examples/app-ssr/src/ClientOnlyWidget.tsx b/examples/start-ssr/src/ClientOnlyWidget.tsx → examples/app-ssr/src/ClientOnlyWidget.tsx
diff --git a/examples/start-ssr/src/CustomDocument.tsx → examples/app-ssr/src/CustomDocument.tsx b/examples/start-ssr/src/CustomDocument.tsx → examples/app-ssr/src/CustomDocument.tsx
diff --git a/examples/start-ssr/src/HmrTarget.tsx → examples/app-ssr/src/HmrTarget.tsx b/examples/start-ssr/src/HmrTarget.tsx → examples/app-ssr/src/HmrTarget.tsx
diff --git a/examples/start-ssr/src/NestedLazy.tsx → examples/app-ssr/src/NestedLazy.tsx b/examples/start-ssr/src/NestedLazy.tsx → examples/app-ssr/src/NestedLazy.tsx
diff --git a/examples/start-ssr/src/NestedLazyLayout.tsx → examples/app-ssr/src/NestedLazyLayout.tsx b/examples/start-ssr/src/NestedLazyLayout.tsx → examples/app-ssr/src/NestedLazyLayout.tsx
diff --git a/examples/start-ssr/src/NestedLazyLeaf.tsx → examples/app-ssr/src/NestedLazyLeaf.tsx b/examples/start-ssr/src/NestedLazyLeaf.tsx → examples/app-ssr/src/NestedLazyLeaf.tsx
diff --git a/examples/start-ssr/src/QueryLazy.tsx → examples/app-ssr/src/QueryLazy.tsx b/examples/start-ssr/src/QueryLazy.tsx → examples/app-ssr/src/QueryLazy.tsx
diff --git a/examples/start-ssr/src/api.ts → examples/app-ssr/src/api.ts b/examples/start-ssr/src/api.ts → examples/app-ssr/src/api.ts
diff --git a/examples/start-ssr/src/db.ts → examples/app-ssr/src/db.ts b/examples/start-ssr/src/db.ts → examples/app-ssr/src/db.ts
diff --git a/examples/start-ssr/src/frames/FramesApp.tsx → examples/app-ssr/src/frames/FramesApp.tsx b/examples/start-ssr/src/frames/FramesApp.tsx → examples/app-ssr/src/frames/FramesApp.tsx
@@ -4,11 +4,11 @@ import { getFreshPanel, getPanel, incrementCounter } from './data';
 import Row from './Row';
 
 /**
- * Server-components page: a plain content component like any other start-mode
- * app root. `serverFunctions: { components: true }` + SSR start mode's
+ * Server-components page: a plain content component like any other app-mode
+ * app root. `serverFunctions: { components: true }` + SSR app mode's
  * generated entries emit every bit of wiring (the render plugin, the
  * bootstrap script, the client-side installServerComponents() call) — this
- * file is only app code. The test's frames mode points `start.app` here.
+ * file is only app code. The test's frames mode points `app.root` here.
  *
  * The whole client surface for server components is `dynamic` over a server
  * function call: every response for a call site resolves to the same stable

diff --git a/examples/start-ssr/src/frames/Row.tsx → examples/app-ssr/src/frames/Row.tsx b/examples/start-ssr/src/frames/Row.tsx → examples/app-ssr/src/frames/Row.tsx
diff --git a/examples/start-ssr/src/frames/data.tsx → examples/app-ssr/src/frames/data.tsx b/examples/start-ssr/src/frames/data.tsx → examples/app-ssr/src/frames/data.tsx
diff --git a/examples/start-ssr/src/middleware.ts → examples/app-ssr/src/middleware.ts b/examples/start-ssr/src/middleware.ts → examples/app-ssr/src/middleware.ts
@@ -1,5 +1,5 @@
 // Fetch-style middleware chain for the middleware/preview e2e modes
-// (SSR_MIDDLEWARE=1 wires it through `start.middleware` in vite.config.ts).
+// (SSR_MIDDLEWARE=1 wires it through `app.middleware` in vite.config.ts).
 // Server-only: only the generated handler imports it. Exercises the whole
 // contract:
 // - runs inside the request-event scope: getRequestEvent() answers, locals

diff --git a/examples/start-ssr/src/posture.test.tsx → examples/app-ssr/src/posture.test.tsx b/examples/start-ssr/src/posture.test.tsx → examples/app-ssr/src/posture.test.tsx
diff --git a/examples/start-ssr/src/query-modules.d.ts → examples/app-ssr/src/query-modules.d.ts b/examples/start-ssr/src/query-modules.d.ts → examples/app-ssr/src/query-modules.d.ts
diff --git a/...les/start-ssr/src/server-posture.test.tsx → examples/app-ssr/src/server-posture.test.tsx b/...les/start-ssr/src/server-posture.test.tsx → examples/app-ssr/src/server-posture.test.tsx
diff --git a/examples/start-ssr/src/serverConfig.ts → examples/app-ssr/src/serverConfig.ts b/examples/start-ssr/src/serverConfig.ts → examples/app-ssr/src/serverConfig.ts
diff --git a/examples/start-ssr/src/setup.tsx → examples/app-ssr/src/setup.tsx b/examples/start-ssr/src/setup.tsx → examples/app-ssr/src/setup.tsx
@@ -1,4 +1,4 @@
-// Per-request app setup (`start.setup`): the seam for routers that must
+// Per-request app setup (`app.setup`): the seam for routers that must
 // prepare an app instance before SSR begins — TanStack-style
 // `await router.load()` — receiving the shared request event (middleware
 // locals included) and returning the component to render in the app's

diff --git a/examples/start-ssr/test/host-dispatch.mjs → examples/app-ssr/test/host-dispatch.mjs b/examples/start-ssr/test/host-dispatch.mjs → examples/app-ssr/test/host-dispatch.mjs
diff --git a/examples/start-ssr/test/http-bridge.mjs → examples/app-ssr/test/http-bridge.mjs b/examples/start-ssr/test/http-bridge.mjs → examples/app-ssr/test/http-bridge.mjs
@@ -1,4 +1,4 @@
-// Node↔web bridge hardening e2e, run against the real start-mode dev
+// Node↔web bridge hardening e2e, run against the real app-mode dev
 // middleware over TLS. Vite's dev server uses
 // `http2.createSecureServer({ allowHTTP1: true })` whenever `server.https`
 // is set without a proxy, so under https the plugin's middlewares receive
@@ -118,7 +118,7 @@ async function poll(predicate, ms = 3000) {
 }
 
 // ---------------------------------------------------------------------------
-// The dev server: root the start-ssr app, TLS on — exactly Vite's
+// The dev server: root the app-ssr app, TLS on — exactly Vite's
 // `server.https` shape (http2 secure server with h1 fallback).
 // ---------------------------------------------------------------------------
 const server = await createServer({
@@ -144,7 +144,7 @@ try {
   const page = await withTimeout(h2Request(origin, { path: '/' }), 15000, 'h2 page');
   record(
     'h2 SSR page renders (pseudo-headers skipped)',
-    page.status === 200 && page.body.includes('SSR Start Mode'),
+    page.status === 200 && page.body.includes('SSR App Mode'),
     `status ${page.status}: ${page.body.slice(0, 200)}`,
   );