💦 Features

When building a Single-Page-Application (SPA) that is fully rendered on the client side (CSR), it is common to only send a minimal HTML file to the client which only defines a single div as the root of the app and includes links and scripts to load all the necessary assets to render the application.

This common approach will lead to a blank screen for a few seconds while the JS is being loaded and parsed. To improve the user experience we can add a splash screen, which are commonly used in mobile applications, that is displayed while the assets are being loaded and parsed. Then when your application is ready and initialized, the splash screen can be animated out of the way to reveal the application.

With rspack-plugin-splash-screen you get the following:

• 🤹 Framework-agnostic: Works with any frontend framework that uses Rspack or Rsbuild!
• 🎨 Customizable: You can customize the splash screen with your own logo, change colors, and display a loading indicator.
• 🚀 Fast: The splash screen is inlined to the HTML file at build time.
• 🕹️ Full control: You can control when the splash screen is hidden.
• 🔮 Easy to use: Just add the plugin to your Rspack config and you are good to go.

📲 Installation

Install rspack-plugin-splash-screen with your favorite package manager:

npm install -D rspack-plugin-splash-screen

# yarn
yarn add -D rspack-plugin-splash-screen

# pnpm
pnpm add -D rspack-plugin-splash-screen

🧑‍💻 Usage

With Rsbuild

Import the plugin and add it to your Rsbuild config.

The only required option is logoSrc, which is the path (relative to the public directory) of the logo that will be displayed on the splash screen.

import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { RspackSplashScreenPlugin } from 'rspack-plugin-splash-screen';

export default defineConfig({
  plugins: [pluginReact()],
  tools: {
    rspack: {
      plugins: [
        new RspackSplashScreenPlugin({
          logoSrc: 'logo.svg'
        })
      ]
    }
  }
});

With Rspack (standalone)

If you're using Rspack directly without Rsbuild, you can add the plugin to your Rspack config:

import { RspackSplashScreenPlugin } from 'rspack-plugin-splash-screen';

export default {
  plugins: [
    new RspackSplashScreenPlugin({
      logoSrc: 'logo.svg'
    })
  ]
};

[!IMPORTANT]
Logo images are inlined into the HTML file for optimal performance.

• Supported formats: SVG, PNG, JPG/JPEG, GIF, WebP, BMP
• SVG images are embedded directly as inline SVG markup
• Raster images (PNG, JPG, etc.) are automatically base64-encoded and embedded as data URLs
• File size warning: Images larger than 50KB will trigger a warning, as the splash screen should load quickly. Consider optimizing your logo:
  • SVG: Use SVGOMG to optimize SVG files
  • PNG/JPG: Use tools like TinyPNG or Squoosh to compress images

Then in your application code (written in React, Vue, Svelte, whatever), you can hide the splash screen when the application is ready.

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

hideSplashScreen();

For example in a React app, you can hide the splash screen in the useEffect hook.

import { useEffect } from 'react';
import { hideSplashScreen } from 'rspack-plugin-splash-screen/runtime';

export function App() {
  useEffect(() => {
    hideSplashScreen();
  }, []);

  return <div>My App</div>;
}

[!TIP] You should wait until your application is fully initialized before hiding the splash screen. This could include setting up a router, initializing a store, loading translations, authenticating the user, or loading data from an API etc.

🎨 Customization

You can customize the splash screen by providing additional options to the plugin.

minDurationMs

The minimum duration the splash screen should be displayed, even if the hideSplashScreen function has been called. This is useful to prevent the splash screen from flickering in case the app is initialized very quickly.

For example, to display the splash screen for at least 2 seconds:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  minDurationMs: 2000
});

loaderType

What type of loading indicator should be displayed below the logo.

Available options: "line" (default), "dots", "spinner", "pulse", "orbit", "none".

Line (default) - A horizontal progress bar with animated waves:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  loaderType: 'line'
});

Dots - Animated bouncing dots:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  loaderType: 'dots'
});

Spinner - Classic circular spinner:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  loaderType: 'spinner'
});

Pulse - Pulsating circle animation:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  loaderType: 'pulse'
});

Orbit - Four dots orbiting in a circular pattern:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  loaderType: 'orbit'
});

None - Hide the loading indicator:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  loaderType: 'none'
});

loaderBg

The background color of the loading indicator (default #0072f5).

Example:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  loaderType: 'line',
  loaderBg: '#ff0000'
});

splashBg

The background color of the splash screen (default #ffffff).

Example:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  splashBg: '#000000'
});

minify

Whether to minify the injected HTML and CSS using SWC (default true).

Minification reduces the size of the injected splash screen code but adds a small build-time cost. You can disable it if you prefer unminified output or if you're experiencing issues with minification.

Example:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  minify: false // Disable minification
});

id

Custom ID for the splash screen element and CSS classes (default rpss).

This option is useful for avoiding conflicts with other plugins or libraries that might use the same IDs. When you change the ID, all CSS classes, CSS variables, and the global API will use your custom ID.

Example:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  id: 'my-splash' // Changes element ID, classes, and CSS variables to use 'my-splash'
});

With a custom ID:

• Element ID becomes #my-splash instead of #rpss
• CSS classes become .my-splash-* instead of .rpss-*
• CSS variables become --my-splash-* instead of --rpss-*
• Global API becomes window.__MY_SPLASH__ instead of window.__RPSS__

shouldProcessFile

Custom function to determine which files should be processed by the plugin (default: processes all .html files).

This option is useful when the default .html extension check is not enough to detect only the entrypoint HTML file. For example, if your build outputs multiple HTML files but you only want to add the splash screen to specific ones.

The function receives the filename (including path) as a parameter and should return true if the file should be processed, false otherwise.

Example - Only process the main index.html file:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  shouldProcessFile: (filename) => filename === 'index.html'
});

Example - Process only HTML files in the root directory:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  shouldProcessFile: (filename) => {
    // Only process HTML files that don't contain a path separator
    return filename.endsWith('.html') && !filename.includes('/');
  }
});

Example - Exclude specific HTML files:

new RspackSplashScreenPlugin({
  logoSrc: 'logo.svg',
  shouldProcessFile: (filename) => {
    // Process all HTML files except 404.html
    return filename.endsWith('.html') && !filename.includes('404.html');
  }
});

Dynamic colors

If your app supports theming (eg. light and dark mode), you can dynamically change the colors of the splash screen using CSS variables.

The following CSS variables are available:

• --vpss-bg-splash - Splash screen background color (default #ffffff)
• --vpss-bg-loader - Loading indicator background color (default #0072f5)

⚠️ Note: in order to avoid flickering of colors you should set the CSS variables before the splash screen is rendered! You can achieve this by including a small inline script in your HTML template that sets up the CSS variables based on the user's preferred color scheme.

<!-- Example: Set CSS variables based on user's color scheme preference -->
<script>
  const prefersDark = window.matchMedia(
    '(prefers-color-scheme: dark)'
  ).matches;
  const root = document.documentElement;

  if (prefersDark) {
    root.style.setProperty('--vpss-bg-splash', '#242424');
    root.style.setProperty('--vpss-bg-loader', '#ffcb29');
  } else {
    root.style.setProperty('--vpss-bg-splash', '#ffffff');
    root.style.setProperty('--vpss-bg-loader', '#b18500');
  }
</script>

🛠️ Advanced usage

Prevent showing splash screen with URL search parameter

In some cases you might want to prevent the splash screen from being displayed, eg. if you need to manually trigger a page refresh in your application code after the splash screen has been hidden. For example when the user changes the language and you need to reload the page to apply the new translations, or when the user switches workspaces in your application.

In these cases it is probably better to not show the splash screen even though technically the app is being initialized from scratch again as the user has already seen the splash screen once.

You can prevent the splash screen from being displayed by adding a URL search parameter to the URL before reloading the page.

const params = new URLSearchParams(location.search);
params.set('vpss', 'false');
window.location.search = params.toString();

The added search parameter will be automatically removed by the plugin when the splash screen is initialized after the page reload, so you don't need to remove it manually yourself.

🧪 Testing

The plugin includes comprehensive E2E tests using Playwright to ensure reliability:

# Run tests
pnpm run test

# Run tests with UI mode for debugging
pnpm run test:ui

# Build plugin and example before testing
pnpm run test:build

The test suite validates:

• Splash screen display on initial load
• Logo and loader elements presence
• Hide functionality and timing
• CSS variables and styling
• Global API (window.__RPSS__) availability
• Animation and z-index behavior
• minDurationMs option enforcement

See tests/README.md for more details.

🙏 Attribution

This plugin is a fork of the original vite-plugin-splash-screen by Teemu Taskula, adapted to work with Rspack and Rsbuild. The core functionality and design remain the same, with modifications made to support the Rspack plugin API instead of Vite's plugin system.