In a Vite project, what does adding a framework plugin such as @vitejs/plugin-vue or @vitejs/plugin-react to the plugins array actually do?
answer
- what the core already compiles
- a file format Vite cannot read
- a build-tool plugin, not app code
- presets flattened, falsy entries skipped
- React's plugin is about the dev loop
basics
~20 sA framework plugin teaches Vite's pipeline what it cannot do alone: plugin-vue compiles .vue files into JavaScript and wires their hot updates, and plugin-react adds Fast Refresh and the automatic JSX runtime. It runs in Vite, not in the app.
solid answer
~40 sVite core already handles JavaScript, TypeScript, `.jsx` and `.tsx`, CSS and asset imports, but it has no rule for a `.vue` single-file component. `@vitejs/plugin-vue` hooks into the same pipeline every plugin uses: it turns each `.vue` file into JavaScript the browser can run and handles its hot updates under `vite`. `@vitejs/plugin-react` differs in kind: JSX compiles without it, so what it adds is React Fast Refresh in development and the automatic JSX runtime. Either one goes into `plugins` in `vite.config`; that array also accepts presets (nested arrays, flattened internally) and ignores falsy entries. These are build-tool plugins that run in the Vite process while it serves or builds, unlike a Vue app plugin installed with `app.use()`, which runs in the browser.
code
typescript · 11 linesimport { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { articlePreview } from './build/article-preview'
export default defineConfig(({ command }) => ({
plugins: [
vue(),
// false during vite build, and Vite skips falsy entries
command === 'serve' && articlePreview(),
],
}))go deeper
Know that Vite core compiles JavaScript, TypeScript, JSX and CSS, and that a .vue file needs @vitejs/plugin-vue listed in the plugins array of vite.config.
Explain that a framework plugin uses the same hooks as any Vite plugin to transform its files and handle hot updates, and that presets are flattened and falsy entries skipped.
Show judgment about what each plugin really adds: plugin-react mostly serves the development loop, so broken in-place updates are a plugin-setup question first, not a JSX-compilation one.
Weigh standardising on the Vite-maintained framework plugins against community or SWC-based variants, considering maintainers, upgrade timing alongside Vite majors and how much custom transform work teams need.
## What Vite does without any plugin Vite's core pipeline already understands most of what a modern frontend imports. Out of the box it: - transpiles **TypeScript** (`.ts`, `.tsx`) by stripping types, without type-checking them; - compiles **JSX** in `.jsx` and `.tsx` files; - processes **CSS** imports and CSS Modules, and pre-processors such as Sass once their package is installed; - turns **asset imports** such as images and fonts into URLs, and JSON into modules. What it does not know is a framework's own file format or its development tooling. A `.vue` **single-file component** is neither JavaScript, TypeScript nor CSS, so without help Vite has no rule that turns it into a module and the import fails. ## What a framework plugin adds A **framework plugin** is an ordinary Vite plugin: an object with a `name` and hooks, published by the framework's maintainers or by the Vite team. It runs inside the Vite process while `vite` serves or `vite build` builds, and it hooks into the same pipeline as any other plugin. It transforms the files its framework owns and takes part in hot updates. | Plugin | What it adds to Vite | |---|---| | `@vitejs/plugin-vue` | Vue 3 single-file components: each `.vue` file becomes JavaScript the browser can run, with hot updates in dev | | `@vitejs/plugin-vue-jsx` | Vue 3 specific JSX: hot updates, global component resolving, directives and slots | | `@vitejs/plugin-react` | React Fast Refresh in development and the automatic JSX runtime | | `@vitejs/plugin-react-swc` | The same React role, using SWC instead of Vite's built-in transformer during development | The two families differ in kind. Vue's plugin is **required**: without it a `.vue` import cannot be compiled at all. React's plugin is mostly about the **development loop**: JSX would still compile without it, but edits would no longer be swapped in place by Fast Refresh. ## How you add one 1. Install the package as a dev dependency, for example `npm add -D @vitejs/plugin-vue`. 2. Import its factory function in `vite.config.ts`. 3. Call it inside the `plugins` array, passing options where needed, such as `react({ jsxRuntime: 'classic' })`. ```ts import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], }) ``` The factory shape is a convention across the ecosystem: calling the function returns the actual plugin object, or several of them, and its arguments are the plugin's options. **How the `plugins` array behaves.** Three rules matter once more than one plugin is listed: - **Presets are flattened.** A framework integration may return an array of plugins from one call. Vite flattens nested arrays internally, so `plugins: [framework()]` is enough. - **Falsy entries are ignored.** `command === 'serve' && articlePreview()` evaluates to `false` during a build, and Vite skips it. This is the usual way to switch a plugin on or off. - **Order matters.** Plugins run in array order within their tier, and a plugin can move itself earlier or later with `enforce`. A plugin that must see another framework file's raw source is placed before that framework's plugin or marked `enforce: 'pre'`. ## A build-tool plugin is not an app plugin Vue also has **app plugins**, installed with `app.use(plugin)`. Those run in the browser, inside the application, and add things such as global properties or provided services. A Vite plugin runs in the build tool and is never shipped to the browser itself; what reaches the browser is the code it generated. Confusing the two sends people searching `vite.config` for a runtime feature, or calling `app.use()` with something that only makes sense at build time. ## Configuring and debugging a framework plugin Framework plugins take options like any factory. `@vitejs/plugin-react`, for example, processes `.js`, `.jsx`, `.ts` and `.tsx` files by default and excludes `/node_modules/`; its `include` option can add another extension, such as `.mdx`, to the files that get Fast Refresh. When something goes wrong, the plugin's `name` appears in Vite's warnings and errors, which tells you which plugin rejected a file. For a closer look, the community plugin `vite-plugin-inspect` shows every module's intermediate state after each plugin, which makes it visible whether the framework plugin ran on a file at all and what it produced. ## Common mistakes - Expecting Vite to compile `.vue` files natively. - Assuming JSX needs a framework plugin before it compiles at all. - Installing a plugin package and forgetting to add it to `plugins`. - Filtering `false` out of the `plugins` array by hand, which Vite already does. - Blaming Vite's JSX handling when in-place updates stop working, instead of checking the React plugin's `include` and `exclude` settings.
- Does a .tsx component in a React project need @vitejs/plugin-react before Vite can compile it?No. Vite compiles `.jsx` and `.tsx` out of the box, so the component builds without the plugin. What you lose is React Fast Refresh: an edit no longer swaps the component in place, so the update falls back to a page reload. You also lose the plugin's JSX-runtime and `include` / `exclude` options. The plugin is about the development loop and React-specific settings, not about making JSX legal.
- Why does a Vue project that writes components in JSX add a second plugin?`@vitejs/plugin-vue` handles `.vue` files only. For JSX written for Vue, Vite's docs point to `@vitejs/plugin-vue-jsx`, which adds Vue 3 specific handling: hot updates, global component resolving, directives and slots. A project that mixes single-file components and `.tsx` components therefore lists both plugins in `plugins`.
- Vite needs a React plugin before any .jsx file can compile.
- Vite compiles .vue files natively and the Vue plugin only adds hot updates.
- A Vite plugin and a Vue app plugin installed with app.use are the same thing.
- Framework plugins are switched on in package.json rather than in vite.config.
- Returning several plugins as one nested array breaks the plugins option.