vitejs/vite-plugin-react: the official React integration for Vite, and when to pick SWC instead

What vitejs/vite-plugin-react actually is, and who it is for

This repository is not one plugin. It is a pnpm workspace holding three published packages: @vitejs/plugin-react, @vitejs/plugin-react-swc, and @vitejs/plugin-rsc. The top-level README does almost nothing except point at three package READMEs and list the packages in a table with links to their changelogs. That structure is the first thing to understand, because a search for "vite plugin react" usually lands on the repository rather than on the package you actually need.

The audience is narrow and clear. You are building a React application on Vite and you need JSX and TSX transformed, plus Fast Refresh so that editing a component updates it in the browser without losing state. The plugin keywords in the root package.json list build-tool, dev-server, frontend, hmr, react and vite, which matches that scope exactly. If you are not on Vite, or not on React, none of this applies to you.

The repository is a monorepo with a playground directory, a scripts directory, and a CI publish script. That layout tells you the plugins are tested against real Vite dev servers and real production builds rather than only unit tests: the root package.json defines test-serve and test-build scripts that run Vitest against a playground config, with a VITE_TEST_BUILD environment variable switching between the two modes. That is the shape of a project maintained as infrastructure for a larger ecosystem, not a side utility.

How the three packages split the work

The mechanism differs per package, and the difference is the whole point of having three.

@vitejs/plugin-react runs the transform through Babel. That is what makes it extensible: Babel's plugin system is the reason this variant exists at all, and it is why the React Compiler and similar transforms have somewhere to attach. The cost is that Babel is a JavaScript toolchain doing work on every module during dev and build.

@vitejs/plugin-react-swc does the same job through SWC, a Rust-based compiler. Faster transforms, but the extension surface is SWC's, not Babel's. The repository includes a script, override-react, described in the root package.json as a bash script, that swaps React versions in the workspace. There is also an override-vite7 script that rewrites pnpm-workspace.yaml overrides and excludes packages/plugin-react from the workspace, which suggests the packages are deliberately tested against more than one Vite major line.

@vitejs/plugin-rsc is a different concern entirely: React Server Components. Its README is a separate document, and the package has its own release cadence ([email protected], published 2026-08-07, while plugin-react was at 6.1.1 on 2026-08-28). The version gap between 0.5.x and 6.x is not a maturity signal in either direction; it reflects that RSC support is versioned independently of the client plugin.

Fast Refresh is the shared behavioural promise across the client plugins. The READMEs are the place to read the specifics of each; the root README does not restate them.

Setting up @vitejs/plugin-react in a Vite project

The repository does not carry install instructions at the root. It directs you to packages/plugin-react/README.md, and that is where the setup steps live. The root package.json enforces pnpm for contributors via a preinstall hook running npx only-allow pnpm, but that constraint applies to developing the plugin itself, not to consuming it.

The root workspace also exposes a dev script that runs the package builds in parallel across packages/*, and a build script that builds every package in the workspace. Those are for working on the plugin, not for using it in an app.

Once the plugin is registered in your Vite config, the behaviour to check is not that the page renders, but that editing a component's body updates the browser without a full reload and without resetting component state. If state resets, Fast Refresh is not active and the plugin is not being applied to that file. If you want the SWC variant instead, the swap is one package name and one import, and the package to install is @vitejs/plugin-react-swc, documented in its own README under packages/plugin-react-swc.

The Babel-to-SWC choice is a one-way door

The genuine limitation here is not a bug. It is that the two client plugins are not interchangeable in both directions, and the repository does not offer a migration path between them beyond swapping the import.

Going from @vitejs/plugin-react to @vitejs/plugin-react-swc is easy until you have a Babel plugin. The moment your config carries a Babel transform, the SWC variant cannot host it, because the plugin surface is SWC's. Nothing in the root README or the repository layout suggests a compatibility shim. So the decision is really: do you need Babel's plugin ecosystem, now or plausibly later? If yes, the Babel variant is the safe default and the transform speed difference is the price. If no, SWC is the faster path and you accept that adding a Babel plugin later means switching packages.

The second limitation is documentation distribution. The root README is a pointer page. Anything about configuration options, Fast Refresh caveats, or RSC constraints lives in the three package READMEs. If you are evaluating the project from the repository root alone, you will come away knowing the packages exist and very little about how to configure them. That is a deliberate structure for a monorepo, but it makes the root page a poor first stop.

A third boundary: this is the Vite integration, not a React build system. It does not replace your bundler configuration, your TypeScript settings, or your routing. It transforms JSX and wires up HMR.

What to compare against, and where the difference shows

The natural comparison is between the two client plugins in this same repository, since the search data around this project is dominated by "vite plugin react vs swc". The difference in approach is the compiler: Babel in JavaScript versus SWC in Rust, with the extension model following from that. Choosing between them is choosing which compiler's plugin ecosystem you are buying into, not choosing between two implementations of identical capability.

Outside the repository, the relevant comparison is the framework-level integrations. If you use a React meta-framework on Vite, its own template already selects and configures one of these plugins, and adding the plugin yourself would duplicate the work. The plugin is for the case where you are assembling the Vite config yourself.

@vitejs/plugin-rsc is a third option in the same repository but not a substitute for either client plugin. Server Components change the rendering model rather than the transform pipeline, and its README is where the constraints are stated. Treating it as "the newer plugin" and reaching for it on a client-only app would be a misreading of what it does.

Maintenance, release cadence and the MIT licence

The last push to the default branch was on 2026-08-28, the same day [email protected] was released, and [email protected] landed on 2026-08-20. The repository is not archived. That cadence, plus the presence of a CI publish script and a changelog per package, indicates the packages are released independently rather than in lockstep, so an upgrade is a per-package decision: plugin-react and plugin-rsc version numbers will not move together.

Upgrade cost is mostly the changelogs. Each package has its own CHANGELOG.md, linked from the table in the root README, and that is the authoritative place to check what changed between your version and the target. Because the packages are separate, an upgrade to plugin-react does not force a change to plugin-rsc, which limits the blast radius of a version bump.

For contributors rather than consumers, the cost is higher: the workspace enforces pnpm through a preinstall hook, uses simple-git-hooks on postinstall, and runs oxfmt for formatting, eslint for linting, and separate TypeScript projects for scripts, playground, and plugin-react. If you are patching the plugin, that is the toolchain you inherit.

On licensing: the repository is MIT, and the LICENSE file sits at the root alongside the three packages. MIT is permissive and places few obligations on how you use the code, but this is a description of the licence identifier, not legal advice. If your organisation has rules about attribution or about bundling permissively licensed dependencies, read the LICENSE file and your own policy rather than this article.

Editorial conclusion

Adopt @vitejs/plugin-react if you have a standard React app on Vite and want the default path the Vite team maintains; pick @vitejs/plugin-react-swc only if you have decided you do not need Babel plugins, since the repository documents no way to add them back. Do not reach for @vitejs/plugin-rsc unless you are deliberately building a React Server Components setup, because its README is a separate document with its own constraints. Before committing, verify two things yourself: which of the three packages your framework template already pulls in, and whether your build depends on any Babel plugin, since that single fact decides the choice for you.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes