{"id":22568,"library":"vite-joylo-runtime-overlay","title":"Vite Runtime Error Overlay","description":"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.","status":"active","version":"1.1.44","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","vite","plugin","overlay","runtime","error","joylo","typescript"],"install":[{"cmd":"npm install vite-joylo-runtime-overlay","lang":"bash","label":"npm"},{"cmd":"yarn add vite-joylo-runtime-overlay","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-joylo-runtime-overlay","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"JSX runtime required for overlay components","package":"react","optional":false},{"reason":"DOM rendering for overlay","package":"react-dom","optional":false},{"reason":"Plugin API dependency, required at build/run time","package":"vite","optional":false}],"imports":[{"note":"Default export only. Named import will result in undefined.","wrong":"import { runtimeErrorOverlay } from 'vite-joylo-runtime-overlay'","symbol":"default","correct":"import runtimeErrorOverlay from 'vite-joylo-runtime-overlay'"},{"note":"This is a TypeScript type export, not a value. Use 'import type'.","wrong":"import { VitePluginRuntimeErrorOverlay } from 'vite-joylo-runtime-overlay'","symbol":"VitePluginRuntimeErrorOverlay","correct":"import type { VitePluginRuntimeErrorOverlay } from 'vite-joylo-runtime-overlay'"},{"note":"TypeScript type, not available at runtime. ESM-only package, require() fails.","wrong":"const { RuntimeErrorOverlayOptions } = require('vite-joylo-runtime-overlay')","symbol":"RuntimeErrorOverlayOptions","correct":"import type { RuntimeErrorOverlayOptions } from 'vite-joylo-runtime-overlay'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport runtimeErrorOverlay from 'vite-joylo-runtime-overlay';\n\nexport default defineConfig({\n  plugins: [\n    runtimeErrorOverlay({\n      reportUrl: process.env.ERROR_REPORT_URL ?? '',\n      autoFix: false,\n      includeStack: true,\n    }),\n  ],\n});","lang":"typescript","description":"Configures the plugin in Vite with optional backend reporting URL and auto-fix disabled."},"warnings":[{"fix":"Place runtimeErrorOverlay() first in the plugins array.","message":"Plugin must be added to the plugins array before any other plugins that transform runtime error handling.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use 'https://example.com/report' or ''.","message":"reportUrl option must be a full URL (including protocol) or empty string. Relative URLs are not supported.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace 'autoFix: true' with 'autoFixEndpoint: 'https://example.com/autofix'.","message":"The 'autoFix' option was deprecated in v1.1.0; use 'autoFixEndpoint' instead.","severity":"deprecated","affected_versions":">=1.1.0"},{"fix":"Ensure errors are thrown inside React component lifecycle or use a custom error boundary.","message":"Overlay may not appear if the error occurs before React is mounted (e.g., in module scope).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import instead of require(). If using CommonJS, stay on v1.0.x or use dynamic import().","message":"In v1.0.0, the plugin used CommonJS exports. v1.1.0 switched to ESM-only.","severity":"breaking","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Set reportUrl to a string or check environment variable is defined.","cause":"reportUrl option is undefined instead of a string.","error":"TypeError: Cannot read properties of undefined (reading 'includes')"},{"fix":"Run 'npm install -D vite-joylo-runtime-overlay' and verify package.json.","cause":"Plugin not installed or incorrect package name.","error":"Error: [vite] Rollup failed to resolve import \"vite-joylo-runtime-overlay\""},{"fix":"Change to 'import runtimeErrorOverlay from 'vite-joylo-runtime-overlay''.","cause":"Using require() in an ESM-only package (v1.1+).","error":"Uncaught ReferenceError: require is not defined"},{"fix":"Use 'import runtimeErrorOverlay from ...' (without curly braces).","cause":"Named import instead of default import.","error":"TypeError: runtimeErrorOverlay is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}