fix the include side of start.css.filter (#316 follow-up): the option's stated use case — opting a node_modules dependency's graph into dev SSR CSS collection — could not work under the raw createFilter composition, twice over: the default /node_modules/ exclude was applied whenever the user set no exclude and createFilter's exclude-wins rule vetoed the included package, and a non-empty include turned the filter into a strict allowlist that rejected the app's own sources, pruning the crawl at the entry roots — an include-only config silently stripped ALL dev SSR CSS (live-repro'd in examples/start-ssr: include /some-ui-lib/ lost App.css from the streamed head while the page still rendered). The crawl walks the graph from the app's entries, so allowlist semantics are structurally wrong for this option; include now RESCUES files on top of the baseline (everything except exclude, which still defaults to /node_modules/ and still gets replaced — not extended — by a user exclude), composed from two createFilters so a file matching both patterns stays excluded, exactly createFilter's own conflict rule. Default and exclude-only behavior are byte-identical to before; empty-array includes are treated as absent (createFilter would read them as allow-all). Coverage the exclude side always had, now mirrored for include: the css-filter mode grew from 2 to 9 assertions across four dev-server sub-runs (exclude / include / conflict / default) against a temp node_modules package written by the harness — a real directory, not a symlink or file: dep, which Vite would realpath outside node_modules and dodge the default exclusion under test — whose JS imports its own CSS (the filter sees JS modules; CSS files bypass it), ssr.noExternal'd so the SSR env can transform the CSS import. Docs that both next.31 start options were missing: README options.start now documents css.filter (include/exclude semantics, dev-only scope) and #315's errorBoundary (generic 500 fallback, no leaked details, dev untouched, errorBoundary: false when middleware owns errors), and the option list gains the absent setup/errorBoundary/css entries; the StartOptions JSDoc for css.filter spells the same semantics. No new changeset — nothing has shipped (#316's changeset is queued unreleased in #313), so the existing start-css-filter changeset's wording is corrected to describe the fixed semantics instead. Full local gate green: start-ssr 349/349 + http-bridge 10/10, css-matrix 82/82 + bridge 19/19, build + tsc clean.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/start-css-filter.md

@@ -2,4 +2,4 @@
 '@solidjs/vite-plugin': patch
 ---
 
-Add `start.css.filter` to control which module graphs are traversed while collecting development CSS.
+Add `start.css.filter` to control which module graphs are traversed while collecting development CSS. `exclude` prunes matching graphs (defaults to `/node_modules/`; providing one replaces the default), and `include` opts matching files in on top of that baseline — e.g. `{ include: /node_modules\/some-ui-lib/ }` server-inlines that dependency's CSS in dev. A file matching both patterns stays excluded.

README.md

@@ -179,7 +179,8 @@ same server functions.
 The object form carries the options (`start: true` is pure sugar for
 `start: {}` — both mean the identical start mode with defaults, and
 `false`/absent means off): `app`, `document`, `entryServer`, `entryClient`,
-`middleware`, `env`, `external`, all documented below.
+`middleware`, `setup`, `env`, `errorBoundary`, `css`, `external`, all
+documented below.
 
 ```tsx
 // src/App.tsx — the entire app: a plain content component
@@ -429,6 +430,43 @@ client values, the leak scan — follows
 design-correct prior art, reimplemented on this plugin's machinery with
 Standard Schema as the only contract (and runtime-read server values).
 
+**`errorBoundary`** — in a production build, generated entries wrap the app
+in a default error boundary (and the document in an outer one): a render
+error streams a generic `500 | Internal Server Error` fallback — no stack
+or error details reach the HTML; the error itself goes to `console.error`
+— and an error caught before the shell flushes commits a real 500 status
+through the response-head lifecycle. Development is unaffected (Vite's
+error overlay owns dev errors), as are authored entries — the boundary is
+generated-entry codegen. Disable it with `start: { errorBoundary: false }`
+when application middleware owns error handling (an error middleware only
+sees the throw when no boundary catches it first). Default: `true`.
+
+**`css.filter`** — include/exclude patterns
+([picomatch](https://github.com/micromatch/picomatch) globs or regexes;
+relative globs resolve against the Vite root) for the module graphs the dev
+server crawls when collecting the CSS it inlines into `<head>` (the no-FOUC
+guarantee). By default the crawl covers the app's own sources and skips
+`node_modules`. `exclude` prunes matching graphs — providing one replaces
+the default `node_modules` exclusion — and `include` opts matching files in
+on top of that baseline, which is how a dependency's CSS gets
+server-inlined in dev:
+
+```ts
+solid({
+  start: {
+    css: { filter: { include: /node_modules\/some-ui-lib/ } },
+  },
+  ssr: true,
+});
+```
+
+CSS files themselves and virtual modules always pass — the filter decides
+which module graphs are traversed, not which stylesheets are kept — and a
+file matching both patterns stays excluded (Vite `createFilter`'s
+conflict rule). Development only: excluding a graph does not remove its
+CSS from the production build, where CSS always comes from the built
+assets.
+
 **Entry resolution** (all paths relative to the Vite root):
 
 1. Explicit `start.entryServer` / `start.entryClient` options.

examples/start-ssr/test/run.mjs

@@ -78,6 +78,13 @@
 //     generated entries and client assets carry no reference to the
 //     server-components runtime when the option is off.
 //
+//   - `start.css.filter` (css-filter mode, CSS_FILTER=<shape> in
+//     vite.config.ts): the dev CSS crawl's include/exclude semantics against
+//     a temp node_modules package written by the test — `exclude` prunes an
+//     app graph (replacing the default node_modules exclusion), `include`
+//     opts the package's graph in on top of the default baseline with app
+//     CSS surviving (the PR #316 use case), a file matching both patterns
+//     stays excluded, and the filterless default prunes node_modules,
 //   - the response-head lifecycle in dev, prod, and preview (App.tsx's
 //     path-keyed surfaces): httpStatus(404)/httpHeader reach the wire, a
 //     pre-flush Location is a real 3xx with no body, a post-flush Location
@@ -105,13 +112,13 @@
 //
 // Requires the plugin built (pnpm build at the repo root) and Google Chrome.
 // Usage: node test/run.mjs
-// [dev|prod|document|entries|endpoint|configure|no-middleware|middleware|preview|base|builder-order|builder-prepare|babel-hmr|frames]
+// [dev|prod|document|css-filter|entries|endpoint|configure|no-middleware|middleware|preview|base|builder-order|builder-prepare|babel-hmr|frames]
 // (default: all)
 
 import { spawn, execSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import path from 'node:path';
-import { rmSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, rmSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import http from 'node:http';
 import {
   createServer,
@@ -1127,30 +1134,131 @@ async function runDocumentMode() {
   }
 }
 
+// Distinctive rule from the temp test-css-lib package's stylesheet: proves a
+// node_modules graph's CSS was opted into the dev SSR crawl by
+// `start.css.filter.include`. Keep in sync with CSS_LIB_FIXTURES below.
+const LIB_CSS_COLOR = 'rgb(7, 140, 210)';
+
+// Temp fixtures for the css-filter mode (written before the sub-runs,
+// removed after): a real — not symlinked — node_modules package whose JS
+// imports its own CSS (the JS module is what the filter sees; CSS files
+// themselves bypass it), plus an app wrapper that pulls the package into
+// the entry graph. Real directory matters: Vite resolves symlinks, and a
+// `file:` dependency would resolve outside node_modules, dodging the
+// default exclusion under test.
+const CSS_LIB_FIXTURES = {
+  'node_modules/test-css-lib/package.json': JSON.stringify(
+    { name: 'test-css-lib', version: '0.0.0', type: 'module', main: 'index.js' },
+    null,
+    2,
+  ),
+  'node_modules/test-css-lib/index.js': `import './styles.css';\nexport const cssLibReady = true;\n`,
+  'node_modules/test-css-lib/styles.css': `#lib-probe {\n  color: ${LIB_CSS_COLOR};\n}\n`,
+  'src/CssLibApp.tsx': `import 'test-css-lib';
+import App from './App';
+
+export default function CssLibApp() {
+  return <App />;
+}
+`,
+};
+
 async function runCssFilterMode() {
   const mode = 'css-filter';
   console.log(`\n=== ${mode.toUpperCase()} ===`);
-  const port = 3172;
-  const origin = `http://localhost:${port}`;
-  const server = startProcess('pnpm', ['exec', 'vite', '--port', String(port), '--strictPort'], {
-    cwd: exampleDir,
-    env: { ...process.env, CSS_FILTER: '1' },
-  });
-  let serverLog = '';
-  server.stdout.on('data', (d) => (serverLog += d));
-  server.stderr.on('data', (d) => (serverLog += d));
+
+  for (const [file, source] of Object.entries(CSS_LIB_FIXTURES)) {
+    mkdirSync(path.dirname(path.join(exampleDir, file)), { recursive: true });
+    writeFileSync(path.join(exampleDir, file), source);
+  }
+
+  // One dev server per filter shape (the option is config-time); each
+  // sub-run asserts on the streamed dev SSR HTML only.
+  const subRuns = [
+    {
+      filter: 'exclude',
+      port: 3172,
+      checks: (html) => {
+        record(mode, 'exclude', 'excluded module graph is not crawled for CSS', !html.includes(APP_CSS_COLOR));
+        record(mode, 'exclude', 'filter does not prevent app rendering', html.includes('SSR Start Mode'));
+      },
+    },
+    {
+      filter: 'include',
+      port: 3173,
+      checks: (html) => {
+        record(
+          mode,
+          'include',
+          'included node_modules graph is crawled for CSS',
+          html.includes(LIB_CSS_COLOR),
+        );
+        record(
+          mode,
+          'include',
+          'include-only filter keeps collecting app CSS',
+          html.includes(APP_CSS_COLOR),
+        );
+        record(mode, 'include', 'filter does not prevent app rendering', html.includes('SSR Start Mode'));
+      },
+    },
+    {
+      filter: 'conflict',
+      port: 3174,
+      checks: (html) => {
+        record(
+          mode,
+          'conflict',
+          'file matching include and exclude stays excluded',
+          !html.includes(APP_CSS_COLOR),
+        );
+        record(mode, 'conflict', 'filter does not prevent app rendering', html.includes('SSR Start Mode'));
+      },
+    },
+    {
+      filter: 'default',
+      port: 3175,
+      checks: (html) => {
+        record(
+          mode,
+          'default',
+          'node_modules graph is pruned without a filter',
+          !html.includes(LIB_CSS_COLOR),
+        );
+        record(mode, 'default', 'app CSS is collected without a filter', html.includes(APP_CSS_COLOR));
+      },
+    },
+  ];
 
   try {
-    await waitForHttp(origin + '/src/api.ts', 30000);
-    const { html } = await fetchStreamed(origin + '/');
-    record(mode, 'css', 'excluded module graph is not crawled for CSS', !html.includes(APP_CSS_COLOR));
-    record(mode, 'ssr', 'filter does not prevent app rendering', html.includes('SSR Start Mode'));
-  } catch (error) {
-    record(mode, 'run', 'mode completed', false, String(error) + serverLog.slice(-2000));
+    for (const { filter, port, checks } of subRuns) {
+      const origin = `http://localhost:${port}`;
+      const server = startProcess(
+        'pnpm',
+        ['exec', 'vite', '--port', String(port), '--strictPort'],
+        {
+          cwd: exampleDir,
+          env: { ...process.env, CSS_FILTER: filter },
+        },
+      );
+      let serverLog = '';
+      server.stdout.on('data', (d) => (serverLog += d));
+      server.stderr.on('data', (d) => (serverLog += d));
+      try {
+        await waitForHttp(origin + '/src/api.ts', 30000);
+        const { html } = await fetchStreamed(origin + '/');
+        checks(html);
+      } catch (error) {
+        record(mode, filter, 'sub-run completed', false, String(error) + serverLog.slice(-2000));
+      } finally {
+        try {
+          process.kill(-server.pid, 'SIGTERM');
+        } catch {}
+      }
+    }
   } finally {
-    try {
-      process.kill(-server.pid, 'SIGTERM');
-    } catch {}
+    rmSync(path.join(exampleDir, 'node_modules/test-css-lib'), { recursive: true, force: true });
+    rmSync(path.join(exampleDir, 'src/CssLibApp.tsx'), { force: true });
   }
 }
 

examples/start-ssr/vite.config.ts

@@ -58,6 +58,12 @@ export default defineConfig({
   define: {
     __JSX_COMPILER__: JSON.stringify(jsxCompiler),
   },
+  // test-css-lib is written into node_modules by the css-filter mode; it
+  // imports its own CSS, so the SSR environment must transform it (a
+  // Node-externalized import of a bare .css file would crash the render).
+  ...(process.env.CSS_FILTER === 'include' || process.env.CSS_FILTER === 'default'
+    ? { ssr: { noExternal: ['test-css-lib'] } }
+    : {}),
   // VITEST_PROJECTS=1 (vitest mode): both test postures in ONE workspace —
   // DOM component tests under jsdom get the client posture (browser
   // conditions, dom codegen), while the node project gets the server
@@ -109,9 +115,28 @@ export default defineConfig({
           ? { document: process.env.SSR_DOCUMENT }
           : {
               external: !!process.env.SOLID_EXTERNAL,
-              ...(process.env.CSS_FILTER
+              // CSS_FILTER (css-filter mode) exercises `start.css.filter`
+              // against a temp app (src/CssLibApp.tsx, written by the test)
+              // whose graph pulls a temp node_modules package with CSS
+              // (test-css-lib, also written by the test):
+              // - exclude: prune the App.tsx graph (replaces the default
+              //   node_modules exclusion).
+              // - include: opt the test-css-lib graph in on top of the
+              //   default baseline (app CSS must survive).
+              // - conflict: the same file matched by both patterns stays
+              //   excluded (createFilter's exclude-wins rule).
+              // - default: no filter — the node_modules graph is pruned by
+              //   the default exclusion while app CSS is collected.
+              ...(process.env.CSS_FILTER === 'exclude'
                 ? { css: { filter: { exclude: /App\.tsx$/ } } }
                 : {}),
+              ...(process.env.CSS_FILTER === 'include'
+                ? { app: 'src/CssLibApp.tsx', css: { filter: { include: /test-css-lib/ } } }
+                : {}),
+              ...(process.env.CSS_FILTER === 'conflict'
+                ? { css: { filter: { include: /App\.tsx$/, exclude: /App\.tsx$/ } } }
+                : {}),
+              ...(process.env.CSS_FILTER === 'default' ? { app: 'src/CssLibApp.tsx' } : {}),
               // SSR_MIDDLEWARE=1 (middleware/preview modes): a fetch-style
               // chain fronting every dispatch path — page SSR, /_server,
               // preview — with getRequestEvent() live inside it.

src/index.ts

@@ -557,10 +557,26 @@ export default function solidPlugin(options: Partial<Options> = {}): Plugin[] {
   const startOptions: StartOptions | null =
     options.start === true ? {} : options.start || null;
   const styleFilterOptions = startOptions?.css?.filter;
-  let styleFilter = createFilter(
-    styleFilterOptions?.include,
-    styleFilterOptions?.exclude ?? DEFAULT_STYLE_EXCLUDE,
-  );
+  // The CSS crawl walks the module graph from the app's own entries, so a
+  // plain createFilter allowlist can't express the option's purpose (opting
+  // node_modules graphs in): a bare `include` would reject the app sources
+  // the crawl has to traverse to ever reach the included package. Instead
+  // `include` rescues files on top of the baseline (everything except
+  // `exclude`, which defaults to node_modules), while a file matching both
+  // patterns stays excluded — createFilter's own conflict rule.
+  const createStyleFilter = (resolve?: string) => {
+    const opts = resolve === undefined ? undefined : { resolve };
+    const base = createFilter(
+      undefined,
+      styleFilterOptions?.exclude ?? DEFAULT_STYLE_EXCLUDE,
+      opts,
+    );
+    const include = styleFilterOptions?.include;
+    const hasInclude = include != null && (!Array.isArray(include) || include.length > 0);
+    const included = hasInclude ? createFilter(include, styleFilterOptions?.exclude, opts) : null;
+    return (id: string) => base(id) || (included ? included(id) : false);
+  };
+  let styleFilter = createStyleFilter();
   const filterDevStyles = (id: string) => styleFilter(id);
   // `start.external` only means something when a server side exists to hand
   // over (SSR start mode); in client mode it is a documented no-op.
@@ -852,11 +868,7 @@ export default function solidPlugin(options: Partial<Options> = {}): Plugin[] {
       base = config.base;
       projectRoot = config.root;
       filter = createFilter(options.include, options.exclude, { resolve: projectRoot });
-      styleFilter = createFilter(
-        styleFilterOptions?.include,
-        styleFilterOptions?.exclude ?? DEFAULT_STYLE_EXCLUDE,
-        { resolve: projectRoot },
-      );
+      styleFilter = createStyleFilter(projectRoot);
       if (serverComponents && !(options.start && options.ssr)) {
         config.logger.warn(
           '[@solidjs/vite-plugin] serverFunctions.components is set without SSR start mode (the `start` ' +

src/ssr/index.ts

@@ -81,7 +81,22 @@ export interface StartOptions {
   app?: string;
   /** Options for development CSS crawling. */
   css?: {
-    /** Filter files traversed while collecting CSS. */
+    /**
+     * Filter for the modules traversed while collecting the CSS that dev
+     * SSR inlines into `<head>`. Patterns are
+     * [picomatch](https://github.com/micromatch/picomatch) globs or regexes;
+     * relative globs resolve against the Vite root. CSS files themselves
+     * and virtual modules always pass — the filter decides which module
+     * graphs are crawled, not which stylesheets are kept.
+     *
+     * `exclude` prunes matching graphs and defaults to `/node_modules/`
+     * (providing your own replaces the default). `include` opts matching
+     * files back in on top of that baseline — typically a package whose
+     * CSS should be server-inlined to avoid a development FOUC, e.g.
+     * `{ include: /node_modules\/some-ui-lib/ }`. A file matching both
+     * stays excluded. Development only: production CSS always comes from
+     * the built assets.
+     */
     filter?: {
       include?: FilterPattern;
       exclude?: FilterPattern;