make Start devtools optional

Author: birkskyum

.changeset/dev-toolbar-inspector.md

@@ -2,4 +2,4 @@
 '@solidjs/vite-plugin': minor
 ---
 
-Add the Start development toolbar, error overlay, and server function inspector.
+Add optional Start development toolbar, error overlay, and server function inspector integration.

README.md

@@ -181,9 +181,16 @@ The object form carries the options (`start: true` is pure sugar for
 `false`/absent means off): `app`, `document`, `entryServer`, `entryClient`,
 `middleware`, `setup`, `env`, `devtools`, `external`, all documented below.
 
-Start mode includes a development toolbar with runtime errors and server
-function calls. Set `start: { devtools: false }` to disable it. The toolbar is
-not included in production builds.
+Install `@solidjs/start-devtools` as a development dependency to add the
+development toolbar with runtime errors and server function calls:
+
+```sh
+pnpm add -D @solidjs/start-devtools@next
+```
+
+Start mode detects the package automatically. Set `start: { devtools: true }`
+to require it or `start: { devtools: false }` to disable it. The package is an
+optional peer and the toolbar is not included in production builds.
 
 ```tsx
 // src/App.tsx — the entire app: a plain content component

package.json

@@ -59,7 +59,6 @@
     "@ampproject/remapping": "^2.3.0",
     "@babel/core": "^7.23.3",
     "@dom-expressions/compiler": "^0.50.0-next.43",
-    "@solidjs/start-devtools": "^1.0.0-next.0",
     "@types/babel__core": "^7.20.4",
     "babel-preset-solid": "^2.0.0-rc.0",
     "merge-anything": "^5.1.7",
@@ -73,6 +72,7 @@
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@skypack/package-check": "^0.2.2",
+    "@solidjs/start-devtools": "^1.0.0-next.0",
     "@types/node": "^18.18.4",
     "cypress": "^14.0.0",
     "cypress-visual-regression": "^5.2.2",
@@ -86,12 +86,16 @@
     "vite": "^7.0.0"
   },
   "peerDependencies": {
+    "@solidjs/start-devtools": "^1.0.0-next.0",
     "@solidjs/web": "^2.0.0-rc.0",
     "@testing-library/jest-dom": "^5.16.6 || ^5.17.0 || ^6.*",
     "solid-js": "^2.0.0-rc.0",
     "vite": "^6.0.0 || ^7.0.0 || ^8.0.0 || ^9.0.0"
   },
   "peerDependenciesMeta": {
+    "@solidjs/start-devtools": {
+      "optional": true
+    },
     "@testing-library/jest-dom": {
       "optional": true
     }

pnpm-lock.yaml

@@ -209,7 +209,13 @@ export interface StartOptions {
    * @default undefined (probe env.ts / env.js; off when absent)
    */
   env?: boolean | string;
-  /** Enable the development toolbar. @default true */
+  /**
+   * Enable the development toolbar. By default it is enabled when
+   * `@solidjs/start-devtools` is installed. Setting this to `true` requires
+   * the package, while `false` disables it.
+   *
+   * @default undefined
+   */
   devtools?: boolean;
   /**
    * Add the default production error boundary to generated entries.
@@ -435,7 +441,8 @@ export function startServe(
   const serverComponents = !!internal.serverComponents;
   const errorBoundary = options.errorBoundary !== false;
   const styleFilter = internal.styleFilter;
-  const devtools = options.devtools !== false;
+  let devtools: boolean | undefined = false;
+  let devtoolsResolution: Promise<boolean> | undefined;
   // `external` is server-mode-only (documented no-op in client mode, so a
   // host-integrated config survives the `ssr` boolean flip untouched).
   const externalServer = !clientMode && !!options.external;
@@ -454,6 +461,19 @@ export function startServe(
     return entries;
   }
 
+  async function resolveDevtools(resolve: () => Promise<unknown>): Promise<boolean> {
+    if (devtools !== undefined) return devtools;
+    devtoolsResolution ??= resolve().then(Boolean);
+    devtools = await devtoolsResolution;
+    if (!devtools && options.devtools === true) {
+      throw new Error(
+        '[@solidjs/vite-plugin] start.devtools requires @solidjs/start-devtools. ' +
+          'Install it as a development dependency or set start.devtools to false.',
+      );
+    }
+    return devtools;
+  }
+
   /** Import specifier for generated code: absolute for files, id for virtuals. */
   function entryServerSpec(): string {
     const { entryServer } = requireEntries();
@@ -631,9 +651,8 @@ export function startServe(
     ].join('\n');
   }
 
-  function generatedEntryClientCode(): string {
+  function generatedEntryClientCode(toolbar: boolean): string {
     const { app } = requireEntries();
-    const toolbar = devtools && !isBuild;
     if (clientMode) {
       // render(), not hydrate(): the shell's body is empty, the app mounts
       // fresh. Client code compiles non-hydratable in client mode, so the
@@ -1001,6 +1020,11 @@ export function startServe(
       enforce: 'pre',
       config(userConfig, env) {
         root = path.resolve(userConfig.root || process.cwd());
+        devtools =
+          env.command === 'serve' && !env.isPreview && options.devtools !== false
+            ? undefined
+            : false;
+        devtoolsResolution = undefined;
         entries = resolveEntries(root, options, clientMode);
         middlewarePath = options.middleware
           ? path.resolve(root, normalizeUserPath(root, options.middleware, 'middleware'))
@@ -1141,7 +1165,7 @@ export function startServe(
         ) {
           return { id: source, moduleSideEffects: source === ENTRY_CLIENT_ID };
         }
-        if (!isBuild && devtools && (source === DEVTOOLS_ID || source === DEVTOOLS_MOUNT_ID)) {
+        if (devtools && (source === DEVTOOLS_ID || source === DEVTOOLS_MOUNT_ID)) {
           return { id: source, moduleSideEffects: true };
         }
         return null;
@@ -1165,7 +1189,12 @@ export function startServe(
           return devStylesModuleCode(this.environment, (file) => this.addWatchFile(file));
         }
         if (id === ENTRY_SERVER_ID) return generatedEntryServerCode();
-        if (id === ENTRY_CLIENT_ID) return generatedEntryClientCode();
+        if (id === ENTRY_CLIENT_ID) {
+          const toolbar = await resolveDevtools(() =>
+            this.resolve('@solidjs/start-devtools', requireEntries().app!, { skipSelf: true }),
+          );
+          return generatedEntryClientCode(toolbar);
+        }
         if (id === DOCUMENT_ID) return documentShellCode;
         if (id === ERROR_BOUNDARY_ID) return errorBoundaryCode;
         if (id === DEVTOOLS_ID || id === DEVTOOLS_MOUNT_ID) {
@@ -1176,13 +1205,17 @@ export function startServe(
         }
         return null;
       },
-      transform(code, id, opts) {
-        if (isBuild || !devtools) return null;
+      async transform(code, id, opts) {
+        if (isBuild || devtools === false) return null;
         const current = requireEntries();
         if (current.generated || getEnvironmentConsumer(this.environment, opts) !== 'client') {
           return null;
         }
         if (id.split('?')[0] !== path.resolve(root, current.entryClient)) return null;
+        const toolbar = await resolveDevtools(() =>
+          this.resolve('@solidjs/start-devtools', id, { skipSelf: true }),
+        );
+        if (!toolbar) return null;
         return {
           code: `import ${JSON.stringify(DEVTOOLS_MOUNT_ID)};\n${code}`,
           map: null,