Vite Plugin React Fallback Throttle

0.1.3 verified Mon Apr 27 auth: no javascript

Vite plugin that configures FALLBACK_THROTTLE_MS in React 19 to control the delay before showing a Suspense fallback. Current stable version is 0.1.3, released with OIDC trusted publishing and immutable releases for supply chain security. Supports Vite 2.3+ up to 8, and Vitest Browser Mode. It resolves a common React 19 Suspense issue where reducing the throttle delay improves UX by showing fallbacks faster during navigation. Ships TypeScript types. Unlike manual configuration, this plugin handles environment detection and pre-bundled dependency patching automatically.

Common errors

error Error: The plugin react-fallback-throttle requires a function export, but got an object. ↓

cause Using import reactFallbackThrottle from ... incorrectly as a plugin object without invoking the function.

fix

Call the imported function: reactFallbackThrottle({ throttleMs: 300 }).

error TypeError: reactFallbackThrottle is not a function ↓

cause Trying to use CommonJS require() on an ESM-only package.

fix

Use import reactFallbackThrottle from 'vite-plugin-react-fallback-throttle'.

error Vite: The plugin 'react-fallback-throttle' is not supported by your version of Vite. ↓

cause Using a Vite version outside the supported range (>=2.3.0 <9.0.0).

fix

Update Vite to a compatible version: npm install vite@6.

Warnings

gotcha The plugin only works with React 19 (react-dom ^19.0.0). Using it with older React versions will have no effect. ↓

fix Ensure your project uses react-dom@^19.0.0.

gotcha The default export is a function that returns a Vite plugin object, not the plugin object itself. Forgetting to call it with options will cause an error. ↓

fix Always invoke the imported function: reactFallbackThrottle({ throttleMs: 300 }).

breaking In v0.1.0, the plugin could not correctly handle pre-bundled React DOM dependencies. This was fixed in v0.1.1. ↓

fix Upgrade to v0.1.1 or later.

gotcha The plugin does not support CommonJS require(); it is ESM-only. Using require() will fail at runtime. ↓

fix Use dynamic import() or switch to ESM.

Install

npm install vite-plugin-react-fallback-throttle

yarn add vite-plugin-react-fallback-throttle

pnpm add vite-plugin-react-fallback-throttle

Imports

reactFallbackThrottle

wrong

const reactFallbackThrottle = require('vite-plugin-react-fallback-throttle')

correct

import reactFallbackThrottle from 'vite-plugin-react-fallback-throttle'

ESM-only package; does not support CommonJS require. The default export is a function.

ReactFallbackThrottleOptions

wrong

import { ReactFallbackThrottleOptions } from 'vite-plugin-react-fallback-throttle'

correct

import type { ReactFallbackThrottleOptions } from 'vite-plugin-react-fallback-throttle'

Options type is only available as a type import; value import will fail at runtime.

Plugin

wrong

import { vitePluginReactFallbackThrottle } from 'vite-plugin-react-fallback-throttle'

correct

import reactFallbackThrottle from 'vite-plugin-react-fallback-throttle'

The default export is the Vite plugin function; there is no named export for it.

Quickstart

Shows how to add the plugin to a Vite config with React 19 and a custom throttle delay of 200ms.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import reactFallbackThrottle from 'vite-plugin-react-fallback-throttle';

export default defineConfig({
  plugins: [
    react(),
    reactFallbackThrottle({ throttleMs: 200 }),
  ],
});