What is @vitejs/plugin-react?
The @vitejs/plugin-react package is a plugin for Vite that enables React fast refresh and other React-specific optimizations in a Vite project. It provides out-of-the-box configuration for a seamless development experience when working with React and Vite.
What are @vitejs/plugin-react's main functionalities?
Fast Refresh
Enables React Fast Refresh, which allows you to get instant feedback for changes in your React components during development without losing component state.
import reactRefresh from '@vitejs/plugin-react';
export default {
plugins: [reactRefresh()],
};
JSX Transform
Automatically transforms JSX without the need for importing React in every file, thanks to the new JSX transform introduced in React 17.
import reactRefresh from '@vitejs/plugin-react';
export default {
plugins: [reactRefresh()],
};
Custom Babel Configuration
Allows for custom Babel configurations to be used alongside the plugin, enabling advanced use cases and compatibility with additional Babel plugins.
import reactRefresh from '@vitejs/plugin-react';
export default {
plugins: [reactRefresh({ babel: { plugins: ['@babel/plugin-syntax-dynamic-import'] } })],
};
Other packages similar to @vitejs/plugin-react
react-refresh-webpack-plugin
A Webpack plugin that enables React Fast Refresh. It is similar to @vitejs/plugin-react in providing hot reloading capabilities but is specific to Webpack-based projects.
babel-preset-react-app
This Babel preset includes the necessary Babel plugins for React applications created with Create React App. It handles JSX transformation and other React optimizations but does not provide hot reloading on its own.
craco
CRACO (Create React App Configuration Override) is an npm package that allows you to customize the Create React App configuration without ejecting. It can be used to modify Babel and Webpack configurations, similar to how @vitejs/plugin-react allows for custom configurations in a Vite project.
@vitejs/plugin-react
The all-in-one Vite plugin for React projects.
- enable Fast Refresh in development
- use the automatic JSX runtime
- avoid manual
import React
in .jsx
and .tsx
modules - dedupe the
react
and react-dom
packages - use custom Babel plugins/presets
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()]
})
Filter which files use Fast Refresh
By default, Fast Refresh is used by files ending with .js
, .jsx
, .ts
, and .tsx
, except for files with a node_modules
parent directory.
In some situations, you may not want a file to act as a HMR boundary, instead preferring that the changes propagate higher in the stack before being handled. In these cases, you can provide an include
and/or exclude
option, which can be a regex, a picomatch pattern, or an array of either. Files matching include
and not exclude
will use Fast Refresh. The defaults are always applied.
react({
exclude: /\.stories\.(t|j)sx?$/,
include: '**/*.tsx'
})
Opting out of the automatic JSX runtime
By default, the plugin uses the automatic JSX runtime. However, if you encounter any issues, you may opt out using the jsxRuntime
option.
react({
jsxRuntime: 'classic'
})
Babel configuration
The babel
option lets you add plugins, presets, and other configuration to the Babel transformation performed on each JSX/TSX file.
react({
babel: {
presets: [...],
plugins: [...],
babelrc: true,
configFile: true,
}
})
Proposed syntax
If you are using ES syntax that are still in proposal status (e.g. class properties), you can selectively enable them with the babel.parserOpts.plugins
option:
react({
babel: {
parserOpts: {
plugins: ['decorators-legacy']
}
}
})
This option does not enable code transformation. That is handled by esbuild.
Note: TypeScript syntax is handled automatically.
Here's the complete list of Babel parser plugins.
Middleware mode
In middleware mode, you should make sure your entry index.html
file is transformed by Vite. Here's an example for an Express server:
app.get('/', async (req, res, next) => {
try {
let html = fs.readFileSync(path.resolve(root, 'index.html'), 'utf-8')
html = await viteServer.transformIndexHtml(req.url, html)
res.send(html)
} catch (e) {
return next(e)
}
})
Otherwise, you'll probably get this error:
Uncaught Error: @vitejs/plugin-react can't detect preamble. Something is wrong.