Vite Runtime Error Overlay

1.1.44 verified Mon Apr 27 auth: no javascript

A lightweight runtime error overlay plugin for Vite that displays runtime errors in-browser (like the Vite dev error overlay but for runtime) and optionally reports them to your backend for logging or auto-fix. Current stable version 1.1.44, released regularly. Ships TypeScript types. Peer dependencies: react >=17.0.0, react-dom >=17.0.0, vite >=5.0.0 <8.0.0. Differentiator: combines runtime error display with optional backend reporting, unlike Vite's built-in compile-time overlay.

Common errors

error TypeError: Cannot read properties of undefined (reading 'includes') ↓

cause reportUrl option is undefined instead of a string.

fix

Set reportUrl to a string or check environment variable is defined.

error Error: [vite] Rollup failed to resolve import "vite-joylo-runtime-overlay" ↓

cause Plugin not installed or incorrect package name.

fix

Run 'npm install -D vite-joylo-runtime-overlay' and verify package.json.

error Uncaught ReferenceError: require is not defined ↓

cause Using require() in an ESM-only package (v1.1+).

fix

Change to 'import runtimeErrorOverlay from 'vite-joylo-runtime-overlay''.

error TypeError: runtimeErrorOverlay is not a function ↓

cause Named import instead of default import.

fix

Use 'import runtimeErrorOverlay from ...' (without curly braces).

Warnings

gotcha Plugin must be added to the plugins array before any other plugins that transform runtime error handling. ↓

fix Place runtimeErrorOverlay() first in the plugins array.

gotcha reportUrl option must be a full URL (including protocol) or empty string. Relative URLs are not supported. ↓

fix Use 'https://example.com/report' or ''.

deprecated The 'autoFix' option was deprecated in v1.1.0; use 'autoFixEndpoint' instead. ↓

fix Replace 'autoFix: true' with 'autoFixEndpoint: 'https://example.com/autofix'.

gotcha Overlay may not appear if the error occurs before React is mounted (e.g., in module scope). ↓

fix Ensure errors are thrown inside React component lifecycle or use a custom error boundary.

breaking In v1.0.0, the plugin used CommonJS exports. v1.1.0 switched to ESM-only. ↓

fix Use import instead of require(). If using CommonJS, stay on v1.0.x or use dynamic import().

Install

npm install vite-joylo-runtime-overlay

yarn add vite-joylo-runtime-overlay

pnpm add vite-joylo-runtime-overlay

Imports

default

wrong

import { runtimeErrorOverlay } from 'vite-joylo-runtime-overlay'

correct

import runtimeErrorOverlay from 'vite-joylo-runtime-overlay'

Default export only. Named import will result in undefined.

VitePluginRuntimeErrorOverlay

wrong

import { VitePluginRuntimeErrorOverlay } from 'vite-joylo-runtime-overlay'

correct

import type { VitePluginRuntimeErrorOverlay } from 'vite-joylo-runtime-overlay'

This is a TypeScript type export, not a value. Use 'import type'.

RuntimeErrorOverlayOptions

wrong

const { RuntimeErrorOverlayOptions } = require('vite-joylo-runtime-overlay')

correct

import type { RuntimeErrorOverlayOptions } from 'vite-joylo-runtime-overlay'

TypeScript type, not available at runtime. ESM-only package, require() fails.

Quickstart

Configures the plugin in Vite with optional backend reporting URL and auto-fix disabled.

// vite.config.ts
import { defineConfig } from 'vite';
import runtimeErrorOverlay from 'vite-joylo-runtime-overlay';

export default defineConfig({
  plugins: [
    runtimeErrorOverlay({
      reportUrl: process.env.ERROR_REPORT_URL ?? '',
      autoFix: false,
      includeStack: true,
    }),
  ],
});