Installation
npm install vite-plugin-react-scan
pnpm add vite-plugin-react-scan
yarn add vite-plugin-react-scan
Usage
Add the plugin to your vite.config.ts:
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import reactScan from 'vite-plugin-react-scan';
export default defineConfig({
plugins: [
react(),
reactScan({
enable: process.env.NODE_ENV === 'development',
}),
],
});
Plugin Options
enable
boolean
default:"process.env.NODE_ENV === 'development'"
Enable or disable the plugin.reactScan({
enable: true,
})
Custom React Scan options to pass to the scan() function.See Configuration Options for all available options.reactScan({
scanOptions: {
enabled: true,
showToolbar: true,
log: false,
animationSpeed: 'fast',
},
})
Enable debug logging for the plugin.reactScan({
debug: true,
})
- Plugin initialization
- File transformations
- Script injection
- Build events
Automatically add display names to React components.reactScan({
autoDisplayNames: true,
})
Enabling this option will add Babel transformations to your build process, which may increase build time slightly.
How It Works
Development Mode
In development, the plugin:
- Excludes
react-scan from Vite’s dependency optimization
- Injects a script tag that imports and initializes React Scan
- Optionally transforms JSX files to add component display names
Example injected script:
<script type="module">
import { scan } from '/@id/react-scan';
(async () => {
try {
scan({ enabled: true });
} catch (error) {
console.error('[vite-plugin-react-scan] Scan failed:', error);
}
})();
</script>
Production Mode
In production builds, the plugin:
- Bundles
react-scan as a static asset
- Injects the script at the beginning of your HTML
- Initializes React Scan with your configured options
React Scan is disabled by default in production. Only use dangerouslyForceRunInProduction for debugging purposes.
Configuration Examples
Basic Setup
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import reactScan from 'vite-plugin-react-scan';
export default defineConfig({
plugins: [
react(),
reactScan(),
],
});
Custom Options
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import reactScan from 'vite-plugin-react-scan';
export default defineConfig({
plugins: [
react(),
reactScan({
enable: process.env.NODE_ENV === 'development',
scanOptions: {
enabled: true,
showToolbar: true,
log: false,
animationSpeed: 'fast',
trackUnnecessaryRenders: true,
},
}),
],
});
With Display Names
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import reactScan from 'vite-plugin-react-scan';
export default defineConfig({
plugins: [
react(),
reactScan({
autoDisplayNames: true,
}),
],
});
Environment-Based Configuration
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import reactScan from 'vite-plugin-react-scan';
export default defineConfig(({ mode }) => ({
plugins: [
react(),
reactScan({
enable: mode === 'development',
scanOptions: {
log: mode === 'development' && process.env.VERBOSE === 'true',
trackUnnecessaryRenders: process.env.TRACK_RENDERS === 'true',
},
}),
],
}));
Debug Mode
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import reactScan from 'vite-plugin-react-scan';
export default defineConfig({
plugins: [
react(),
reactScan({
debug: true,
scanOptions: {
_debug: 'verbose',
},
}),
],
});
Troubleshooting
React Scan not appearing
-
Verify the plugin is loaded:
// vite.config.ts should have:
plugins: [react(), reactScan()]
-
Check browser console for errors
-
Enable debug mode:
reactScan({ debug: true })
Plugin conflicts
Ensure react() plugin comes before reactScan():
plugins: [
react(), // ✅ First
reactScan(), // ✅ Second
]
Build errors
If you encounter build errors with autoDisplayNames:
reactScan({
autoDisplayNames: false, // Disable this option
})
See Also