# ⚡ @solidjs/vite-plugin > [`vite-plugin-solid`](https://www.npmjs.com/package/vite-plugin-solid) has moved to > `@solidjs/vite-plugin`. See [Migrating from vite-plugin-solid](#migrating-from-vite-plugin-solid). A simple integration to run [solid-js](https://github.com/solidjs/solid) with [vite](https://github.com/vitejs/vite) ## Got a question? / Need help? Join [solid discord](https://discord.com/invite/solidjs) and check the [troubleshooting section](#troubleshooting) to see if your question hasn't been already answered. ## Features - HMR with no configuration needed - Drop-in installation as a vite plugin - Minimal bundle size - Support typescript (`.tsx`) out of the box - Experimental TypeScript TSRX (`.tsrx`) support out of the box - Support code splitting out of the box ## Requirements This module is 100% ESM compatible and requires Node.js `>=22.12.0` (the same floor as the `solid-js` 2.0 runtime packages). You can check your current Node.js version by running `node -v`. Use a version manager such as [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to update it. Supported Vite versions: **Vite 8 and 9**. ## Quickstart Start from one of the Solid 2 [templates](https://github.com/solidjs/templates/tree/main/solid-v2): ```bash $ npx degit solidjs/templates/solid-v2/basic my-solid-project $ cd my-solid-project $ npm install # or pnpm install or yarn install $ npm run dev # starts the dev server with hot module replacement $ npm run build # builds to /dist ``` `solid-v2/bare` is the minimal starting point, and `solid-v2/fullstack` adds streaming SSR, middleware and server functions. ## Installation Install `vite` and `@solidjs/vite-plugin` as dev dependencies, and Solid's runtime, `solid-js` and `@solidjs/web`, as dependencies. Both runtime packages are peer dependencies of the plugin, so you control which Solid version your code is compiled against. ```bash # with npm $ npm install -D vite @solidjs/vite-plugin $ npm install solid-js @solidjs/web # with pnpm $ pnpm add -D vite @solidjs/vite-plugin $ pnpm add solid-js @solidjs/web # with yarn $ yarn add -D vite @solidjs/vite-plugin $ yarn add solid-js @solidjs/web ``` Add it as plugin to `vite.config.js` ```js // vite.config.ts import { defineConfig } from 'vite'; import solidPlugin from '@solidjs/vite-plugin'; export default defineConfig({ plugins: [solidPlugin()], }); ``` ## Run Just use regular `vite` or `vite build` commands ```json { "scripts": { "dev": "vite", "build": "vite build" } } ``` ## API ### options - Type: Object - Default: {} #### options.include - Type: (string | RegExp)[] | string | RegExp | null - Default: undefined A [picomatch](https://github.com/micromatch/picomatch) pattern, or array of patterns, which specifies the files the plugin should operate on. #### options.exclude - Type: (string | RegExp)[] | string | RegExp | null - Default: undefined A [picomatch](https://github.com/micromatch/picomatch) pattern, or array of patterns, which specifies the files to be ignored by the plugin. #### options.dev - Type: Boolean - Default: undefined (development builds under `vite dev`, production builds otherwise) Use Solid's development builds: the `development` export condition of `solid-js` and `@solidjs/web`, which carry the extra checks, warnings and diagnostics, plus the compiler's dev output. Left unset, they are used under `vite dev` (and vitest) only. `true` forces them in `vite build` too, for example to debug a production bundle with the dev warnings on. `false` serves the production builds under `vite dev` as well; HMR then falls back to full reloads, since the production refresh runtime is an inert stub. #### options.observe - Type: Boolean - Default: false Resolve Solid's observe builds in production: the production-speed runtime that keeps the diagnostics and attribution channels (`OBSERVE`) alive for observability tooling (error monitoring, performance tracing). Adds the `observe` export condition to every environment and turns on the compiler's source names (see `options.solid.sourceNames`), so graph labels (``, `span.textContent`, `count`) survive minification. Under `vite dev` the dev build still wins. #### options.diagnostics - Type: Boolean - Default: undefined (on when the app declares `@solidjs/diagnostics`) Dev-serve only: expose Solid's diagnostic and attribution channels to out-of-process consumers (agents, tests, `curl`). The plugin injects a client module that installs the in-page bridge from the app's own `@solidjs/diagnostics`, and serves a `/__solid/diagnostics` endpoint on the dev server: `GET` reports status, and `POST { method, params }` forwards capture control (`begin`/`end`), `whyDidRun` and cost queries to the page over the Vite WebSocket. The dev server prints the endpoint at startup. Left unset, it turns on when the nearest `package.json` declares `@solidjs/diagnostics`, so adding the dev dependency is the whole setup. `true` forces it on (and errors if the package is missing), `false` opts out. Never active on `vite build`, preview or in test mode, and off with `dev: false` unless `observe` is on, since the channels only exist in the dev and observe builds. #### options.performanceTracks - Type: `boolean | PerformanceTracksOptions` (from `@solidjs/web/performance-tracks`) - Default: true Dev-serve only: paint Solid's records — effect and memo re-runs, interactions, holds, async flights, navigations, server-function calls — as custom tracks in the Chrome Performance panel, without the app calling `enablePerformanceTracks()` itself. Record a trace with the Performance panel while the dev server serves the page; the `Solid` group appears beside Chrome's main-thread and network tracks (`Interactions`, `Propagation`, `Effects`, `Memos`, `Async`, `Holds`, `Navigations`, `Server`), every span labelled by *why* it ran, findings as markers on the Timings track. See [Chrome Performance panel](https://github.com/solidjs/solid/blob/next/documentation/solid-2.0/08-dev-diagnostics.md#chrome-performance-panel-solidjswebperformance-tracks) in the Solid 2.0 diagnostics guide for how to read them. The plugin injects a small client module that enables the tracks *ahead of the app's entry* — a `` tail. That stub is `event.response`, which `@solidjs/web`'s base `RequestEvent` type does not declare: type start-mode events as `StartRequestEvent` (exported from the plugin, and what `StartMiddleware` receives), or cast a `getRequestEvent()` result to it. **`middleware`** points at a server-only module default-exporting one middleware — `(event, next) => Response | Promise`, the request at `event.request` — or an array of them. The plugin composes the chain itself. `next()` takes no arguments: assign `event.request = new Request(...)` before calling it to hand a different request downstream (calling `next(request)`, the previous shape, throws a migration error). The page render runs inside `next()`, so per-request render inputs go on the event before that call. `event.nonce` is the CSP nonce (a string, or `{ script, style }` with each a non-empty string or `false`). `event.renderMode` is `'stream'` or `'async'` for this request, overriding the static `renderMode` below. `handleRequest(request, { nonce, renderMode })` is seeded onto the event before the chain and wins over a middleware write. ```ts // vite.config.ts solid({ start: { middleware: './src/middleware.ts' }, ssr: true }); // src/middleware.ts export default async (event, next) => { event.nonce ??= crypto.randomUUID(); if (/bot|crawler/i.test(event.request.headers.get('user-agent') ?? '')) { event.renderMode = 'async'; } const response = await next(); const scriptNonce = typeof event.nonce === 'string' ? event.nonce : event.nonce?.script; if (scriptNonce && response.headers.get('content-type')?.startsWith('text/html')) { response.headers.set( 'content-security-policy', `script-src 'nonce-${scriptNonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none'`, ); } return response; }; ``` Generated entries pass `event.nonce` into `renderToStream`. An authored `entry-server` must forward the `context.nonce` the handler passes it (`renderToStream(app, { manifest, nonce: context.nonce })`). The chain fronts every request the plugin dispatches — page SSR and the server-function endpoint, dev, production, and preview alike — and runs inside the request-event scope, so `getRequestEvent()` answers with the same event as the `event` argument (the endpoint shares it, so `locals` decoration is visible to server functions too). Nothing reaches the wire until the outermost middleware returns: headers stay mutable after `next()` even for streamed responses. In dev, writing `event.nonce` or `event.renderMode` after `await next()` warns: the render already read them. Whatever escapes the chain is settled at the handler edge. A thrown `Response` is the response, so `throw redirect('/login')` answers the 302 (as the server-function endpoint does), and so is the `Response` a thrown `respond()` envelope carries; `Response.error()` is not a response and counts as a failure. In a production build any other failure (a middleware throw, a `serverRenderSetup` failure, or an invalid `event.renderMode` / `event.nonce`) is contained by the handler instead of rejecting to the host. It is reported once to the hook registered with `configureServerErrors` from `@solidjs/web` (through its `reportRequestFailure`: `{ kind: 'request', handling: 'failed' }` and the request `event`; an error the runtime already reported is not heard again), or logged with `console.error` when no hook is registered, and the client gets a bodyless 500. That 500 carries the headers and cookies written to the request event only while the response head is still open: once `next()` has returned a rendered page, the head was committed with that page, and a later throw drops them. An error middleware still sees a throw first, and with `productionErrorBoundary` on, render errors are handled by the boundary before they get this far. In dev those failures still reject, so the dev server sees the original error (with the built-in dev middleware, Vite's error middleware and its overlay). **`serverRenderSetup`** points at a server-only module whose default export runs before every page render: `(event, App) => Component | void | Promise`. The generated server entry awaits it after the middleware chain has dispatched to the page render and immediately before `renderToStream`. It is the seam for routers that must prepare an app instance per request before SSR can begin (create a router bound to the request, `await router.load()`, then render): ```ts // vite.config.ts solid({ start: { serverRenderSetup: './src/server-render-setup.tsx' }, ssr: true }); // src/server-render-setup.tsx import type { StartServerRenderSetup } from '@solidjs/vite-plugin'; const serverRenderSetup: StartServerRenderSetup = async (event, App) => { const router = createRouter({ url: event.request.url }); await router.load(); // async work completes before the shell streams return () => ; // rendered in the app's place }; export default serverRenderSetup; ``` `event` is the shared request event, the same one the middleware chain decorated, so `locals` are visible, and the function runs inside the request scope (`getRequestEvent()` answers in anything it calls). Return a component and the generated entry renders it inside the Document where `` would have been; return nothing and `` renders unchanged, so a pure side-effect setup (seeding a per-request cache) needs no return. Zero-config apps are untouched: without the option the generated entry is byte-identical to before. Three boundaries to know. It runs for page renders only: the middleware chain and the server-function endpoint run without it, and so does a request that a middleware answers without calling `next()`. The module's top level evaluates once, when the handler loads, so per-request work belongs in the default export. And it only exists in generated entries (an authored `entry-server` owns `render()` already; configuring both is an error). As with any server-side tree shaping, whatever it renders must be matched client-side for hydration: routers that own both sides (their client entry re-creates the router and hydrates the same tree) fit naturally. **`serverSetup`** points at a server-only module that runs to completion before anything else in the server graph loads: the app, the middleware, `@solidjs/web`, every dependency. It is the seam for code that must run first, typically instrumentation that patches the runtime before the modules it patches are loaded (an APM's OpenTelemetry setup, a profiler, a `module.register` hook): ```ts // vite.config.ts solid({ start: { serverSetup: './src/server-setup.ts' }, ssr: true }); // src/server-setup.ts import * as Sentry from '@sentry/node'; Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 1 }); ``` Import order alone cannot do this in ESM. A static `import './server-setup'` at the top of an entry does run first, but every module in the static graph is loaded before any of them runs, so a loader hook it registers comes too late for the modules it patches, and an async setup module does not hold back the imports after it. The plugin therefore hands out the handler as `await import(serverSetup); await import(handler)`, since top-level await sequencing is the one construct that guarantees the order. It does so on every surface: `vite dev`, `vite build`, `vite preview`, a host consuming the handler entry, and the `nodeServer` entry. This replaces the per-host `node --import instrument.mjs` dance. The module may be async and needs no exports. It runs once per server start (under `vite dev`, again whenever the server environment reloads). The server build must keep code splitting on (the default), since inlining dynamic imports would hoist the handler graph back above the server setup module. **`clientSetup`** points at a client module that the generated client entry runs before it hydrates (SSR mode) or mounts (client mode) the app. Use it for browser setup that must be in place before the first render: - a server-function transport wrapper or request-header hook, - a `vite:preloadError` listener, - an error reporter's `init()`. ```ts // vite.config.ts solid({ start: { clientSetup: './src/client-setup.ts' }, ssr: true }); // src/client-setup.ts window.addEventListener('vite:preloadError', () => window.location.reload()); ``` How it runs: - The generated entry imports the module for its side effects, ahead of the app. A synchronous module finishes before the app's modules evaluate. - The module may use top-level `await`. `hydrate()` / `render()` waits for it to settle. The app's modules may evaluate while it waits, but nothing renders. - Because it can wait, it can read a global that a classic `