vite-plugin-solid is the compiler glue that makes Solid work under Vite

What the plugin actually does to your JSX

vite-plugin-solid is a simple integration to run solid-js with Vite, and the mechanism underneath is a compiler transform rather than a runtime shim. Solid's reactivity is fine-grained and its templates compile to direct DOM operations, which means the JSX in your source has to be transformed at build time by a specific Babel plugin, and that is what this package arranges.

The dependency list in the package metadata shows the shape of it. The Babel core is there, along with babel-preset-solid, which is the preset that wires up Solid's JSX handling, and solid-refresh, which is the hot module replacement runtime. There is also vitefu, which is the helper Vite plugins use to resolve a plugin's own dependencies, and merge-anything, used for merging the option objects the plugin accepts.

The feature list in the README is short and worth quoting in substance. HMR with no configuration needed. Drop-in installation as a Vite plugin. Minimal bundle size. Support for TypeScript with .tsx out of the box. Support for code splitting out of the box.

The TypeScript point is worth pausing on, because in other frameworks the TSX support is a separate plugin you configure. Here it works out of the box, and the options list explains how: the typescript option takes Babel preset-typescript options and merges them into what Solid needs. The code splitting claim is the other one, since Solid's compilation produces code that is meant to be split per component rather than shipped as one bundle.

Installation, and why you install solid-js yourself

The install is two packages in a specific arrangement, and the reason is stated in the README. You install vite and vite-plugin-solid as dev dependencies, and solid-js as a dependency, and the reason is that you have to install those so that you are in control of which Solid version is used to compile your code.

That is an unusual emphasis for a plugin README, and it is a deliberate one. A plugin that pinned a Solid version would decide your runtime version for you, and a mismatch between the compiler and the runtime is the kind of bug that produces baffling errors rather than obvious ones.

The three package managers are all shown, npm first:

# with npm
$ npm install -D vite vite-plugin-solid
$ npm install solid-js

Then it is added to the Vite config, and the file is named in the comment as vite.config.ts:

// vite.config.ts
import { defineConfig } from 'vite';
import solidPlugin from 'vite-plugin-solid';

export default defineConfig({
  plugins: [solidPlugin()],
});

After that you use the ordinary Vite commands, and the scripts in package.json are just dev set to vite and build set to vite build.

For a project starting from nothing, there is a faster route. The starter templates at solidjs/templates behave like CRA, and the quickstart uses degit to fetch the JavaScript one, then installs and runs:

$ npx degit solidjs/templates/js my-solid-project
$ cd my-solid-project
$ npm install # or pnpm install or yarn install
$ npm run start # starts dev-server with hot-module-reloading
$ npm run build # builds to /dist

The options, and the two that change the build output

The options object is the part of the plugin most projects will eventually touch, and the defaults are documented one by one.

The include and exclude options take a picomatch pattern, or an array of patterns, and they specify which files the plugin operates on and which it ignores. The extensions option is the same idea for file types: an array of custom extensions passed through the Solid compiler, with the note that by default the plugin only transforms jsx and tsx files, and that the option is useful if you want mdx files transformed, for example.

Two options change what is emitted rather than what is processed. The dev option, true by default, injects solid-js/dev in place of solid-js in dev mode, with no effect in production, and the README says it is useful for extra logs and debug. The hot option, also true by default, injects the HMR runtime in dev mode with no effect in production.

The ssr option forces SSR code in the produced files, and it defaults to false. The babel option takes Babel transform options merged with the transformations Solid requires, and the solid option takes babel-plugin-jsx-dom-expressions options merged with the defaults set by babel-preset-solid. The typescript option takes Babel preset-typescript options, as described earlier.

There is one subtlety in the solid option that is easy to miss. In dev with HMR enabled, the plugin sets omitServerOnlyTemplates to false for client transforms, so that components containing $ServerOnly elements can be re-created by Solid Refresh, and you can pass that option explicitly to override the behaviour.

HMR through solid-refresh, and its two known edges

Starting from version 1.1.0 the plugin handles automatic HMR through solid-refresh, and the README is measured about its state, calling it early work that provides basic HMR. Two limitations are given.

The first is about state. When you modify a file, every state below that component is reset to the default state, including the current file, while the state in the parent component is preserved. The second is that the entrypoint cannot benefit from HMR yet and forces a hard reload of the entire app, which the README notes is still fast thanks to browser caching.

If either point is blocking, there is a documented way back to the old behaviour: opt out of the automatic HMR and place a snippet in your entry point.

const dispose = render(() => <App />, document.body);

if (import.meta.hot) {
  import.meta.hot.accept();
  import.meta.hot.dispose(dispose);
}

That snippet is the standard dispose pattern for a Solid root, and wiring it to the module hot API means the whole app is replaced rather than partially refreshed, which trades the state-reset problem for a full reload.

The entrypoint limitation is the one that bites in a large codebase, since it is the file most developers edit.

Troubleshooting notes that reveal the shape of the tool

The troubleshooting section is short, and each entry tells you something about how the plugin works.

The first is about WebStorm generating strange triggers on save, and the fix is to disable the Safe Write option in the editor settings, with a link to a JetBrains support thread. Safe Write creates a temporary file and renames it, and a file watcher that reacts to the temporary file sees a change that is not one. That the plugin's own documentation has to mention an editor's safe write behaviour is a hint about how much of the HMR experience is really about file watching.

The second entry is about a dependency that spits out React code instead of Solid, which means it does not expose JSX properly, and the workaround is to exclude it from the Vite dependency optimization. The third is about Solid's use: directives not working, and the fix is to set the typescript option onlyRemoveTypeImports to true.

That last one is a good illustration of the plugin's architecture. The TypeScript handling is Babel's preset-typescript, and the interaction between how TypeScript strips imports and what Solid's compiler expects is exactly the kind of detail that a Babel option surfaces.

The README also points to the Solid Discord for questions and suggests checking the troubleshooting section first.

The repository, the release channels and the version split

The repository layout shows a plugin maintained as a package with an example matrix. There is a src directory, a playground directory, an examples directory, a rollup config, a pnpm workspace file with a pnpm lock file, a cypress directory with a cypress config, and a scripts directory. There is a changesets directory, which is how the releases are made, and a CHANGELOG.md.

The examples directory has one directory per Vite major version, from vite-3 through vite-8, which is a sensible way to prove the plugin still works across the range of Vite releases a project might be on, and it explains the test script, which runs a script over the examples rather than a unit test suite.

The release picture is the confusing part, and it is worth being precise. The recent tags are all prereleases of a 3.0 line, @solidjs/vite-plugin at 3.0.0-next.50, next.49 and next.48, from October 2026. The package manifest, meanwhile, says the name is vite-plugin-solid at version 2.11.14. The repository also carries a migration note from v1, when the package was renamed from @amoutonbrady/vite-plugin-solid to vite-plugin-solid, and the master branch was retargeted at Vite 2.

So the stable line and the prerelease line are moving in parallel, and the naming has changed twice. If you are pinning a version, read the tag rather than the version in the manifest.

Where this plugin is the wrong choice

The first limit is that this is a Solid plugin. It is not a general JSX transformer and not a React compatibility layer, and the compiler it drives, babel-preset-solid, exists to produce Solid's fine-grained DOM code. If your project is React, Vue, Svelte or Preact, this package is the wrong tool by definition.

The second is the prerelease channel. The recent tags are 3.0.0-next builds of a package whose stable manifest version is 2.11.14, and the 3.0 line has been in next for a while. A project that needs a pinned, stable dependency should look at the 2.x line, and a project that wants the newest Vite compatibility should expect to track prereleases.

The third is the HMR behaviour, already described. State below an edited component resets, and the entrypoint forces a full reload. For a codebase where people keep state in components and are annoyed to lose it, that is a daily friction rather than an occasional one, and the documented workaround is a full-reload behaviour.

The fourth is the Babel layer in general. The plugin is built on Babel, with babel-preset-solid and the JSX transform, and every option that reaches the transform is a Babel option. That is a strength when you need to tweak the compilation, and a cost when you want to understand why the output looks the way it does, because the answer is somewhere in a Babel preset rather than in Solid's own code.

The fifth is the small size of the ecosystem around it. The README points to the Solid Discord and to a solidjs/templates starter, and the examples cover Vite versions rather than other bundlers, so a project that is not on Vite has no path here.

Licence, requirements and the state of the project

The licence in the package metadata is MIT, and the package is authored by Alexandre Mouton-Brady, who also appears in the migration note as the owner of the previous package name, so the project has been under the same hands through the rename.

The runtime requirement is stated in the README: the module is 100 percent ESM compatible and requires NodeJS 14.18.0 or later. The README tells you to check your version with node -v, and suggests Volta or nvm if you are below that, or an update.

That Node floor is a sign of age. A package requiring 14.18 is a package that was written when that was the current release, and the project has clearly kept it working since. The manifest still ships a CommonJS entry point alongside the ESM one, and the exports map lists a node condition and a require condition pointing at the CJS build, so it is consumable from both module systems even though the module itself is ESM only.

The last push to the repository was on 2026-10-19 and the repository is not archived, and the recent prerelease tags show active work on the 3.0 line while the 2.x line remains the version in the manifest. The homepage field points at the repository's own readme, and there is a Discord for support rather than a separate site.

Editorial conclusion

vite-plugin-solid fits a team starting a Solid project that wants HMR and TypeScript support without writing a Babel or JSX configuration by hand, and the option surface is enough to slot it into an existing build when you need to. It is the wrong tool if you are not using Solid, since the plugin is specific to Solid's compilation model, and the wrong tool if you need a stable release, because the recent tags are all next prereleases of a 3.0 line. Before you adopt it, check three things: that your Node version is 14.18.0 or later, since the module is ESM only, that you know which Solid version your project compiles against, because the README is explicit that you install solid-js yourself to stay in control of it, and that you read the HMR limitations, since state below a changed component resets and the entrypoint still forces a hard reload. The licence in the package metadata is MIT, the package version is 2.11.14, and the last push was on 2026-10-19.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. solidjs/solid-vite-plugin on GitHub