vite-plugin-splash-screen

0.2.2 verified Mon Apr 27 auth: no javascript

A Vite plugin that inlines a customizable splash screen (logo, colors, loading indicator) into the HTML output to prevent blank screens during SPA asset loading. Version 0.2.2, actively maintained, framework-agnostic, and lightweight. Differentiators: inlined at build time for instant display, framework-agnostic, full developer control via runtime hiding.

Common errors

error Error: The 'logoSrc' option is required. ↓

cause Missing required 'logoSrc' option when calling splashScreen().

fix

Add logoSrc: 'path/to/logo.svg' to the plugin options.

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

cause Trying to import { hideSplashScreen } from the main package instead of runtime subpath.

fix

Import from 'vite-plugin-splash-screen/runtime'.

Warnings

breaking Only SVG logos are supported. Non-SVG will cause build errors or broken splash screen. ↓

fix Use an SVG file for the logo, and ensure it is in the publicDir.

gotcha The runtime import path is 'vite-plugin-splash-screen/runtime', not the main package. ↓

fix Use 'import { hideSplashScreen } from 'vite-plugin-splash-screen/runtime'.'

gotcha The plugin is ESM-only. Using require() will fail with 'ERR_REQUIRE_ESM'. ↓

fix Use import syntax, or if using CommonJS, use dynamic import().

Install

npm install vite-plugin-splash-screen

yarn add vite-plugin-splash-screen

pnpm add vite-plugin-splash-screen

Imports

splashScreen

wrong

const splashScreen = require('vite-plugin-splash-screen')

correct

import { splashScreen } from 'vite-plugin-splash-screen'

Plugin is ESM-only; require() will fail.

hideSplashScreen

wrong

import { hideSplashScreen } from 'vite-plugin-splash-screen'

correct

import { hideSplashScreen } from 'vite-plugin-splash-screen/runtime'

Runtime export is from a separate subpath to avoid bundling runtime code with the plugin config.

Quickstart

Shows how to configure the plugin with all options and hide the splash screen in a React app.

// vite.config.js
import { defineConfig } from 'vite';
import { splashScreen } from 'vite-plugin-splash-screen';

export default defineConfig({
  plugins: [
    splashScreen({
      logoSrc: 'logo.svg', // place logo.svg in public/
      backgroundColor: '#ffffff',
      title: 'My App',
      minDurationMs: 500,
      style: 'line', // or 'default', 'spinner'
      primaryColor: '#000000',
    }),
  ],
});

// In your app (React example):
// App.tsx
import { useEffect } from 'react';
import { hideSplashScreen } from 'vite-plugin-splash-screen/runtime';

function App() {
  useEffect(() => {
    hideSplashScreen();
  }, []);
  return <div>App loaded</div>;
}

export default App;