vite-plugin-boot-screen

A Vite plugin that automatically injects a splash/loading screen into your app. It detects when your Vue/React app has mounted and gracefully fades out. Also supports manual mode — keep the splash visible until your async initialization (data fetching, permission loading, etc.) is complete.

Features

• Zero intrusion — no changes to your business code, just add one line in Vite config
• Smart detection — uses MutationObserver to detect when the app mounts
• Anti-flicker — built-in minTime ensures the splash is visible long enough
• Manual mode — control exactly when the splash closes via window.__splashDone()
• Type safe — ships a client type declaration for full TypeScript support
• Fallback — force-closes after 2s to prevent the page from getting stuck

Install

pnpm add -D vite-plugin-boot-screen

Usage

Auto mode (default)

Splash screen closes automatically after the app mounts:

// vite.config.ts
import splashScreen from "vite-plugin-boot-screen";

export default {
  plugins: [
    splashScreen({
      minTime: 800,
      appMountId: "app",
    }),
  ],
};

Manual mode

Keep the splash visible until your async initialization is done:

// vite.config.ts
import splashScreen from "vite-plugin-boot-screen";

export default {
  plugins: [
    splashScreen({
      hideOn: "manual",
      doneCallbackName: "__splashDone", // optional, this is the default
    }),
  ],
};

// main.ts
import { createApp } from "vue";
import App from "./App.vue";

const app = createApp(App);
app.mount("#app");

// Mount completes, but splash stays visible
// until you explicitly call window.__splashDone()
async function init() {
  await fetchUserPermissions();
  await loadAppConfig();
  window.__splashDone?.(); // splash closes here
}

init();

TypeScript Support

To get type hints for window.__splashDone, add the following reference to your project's env.d.ts (or vite-env.d.ts):

/// <reference types="vite-plugin-boot-screen/client" />

This augments the global Window interface so window.__splashDone is fully typed with JSDoc.

If you use a custom doneCallbackName, declare it yourself in your env.d.ts:

interface Window {
  myCustomDone?: () => void;
}

Options

| Option | Type | Default | Description | | ------------------ | ----------------------- | ---------------- | --------------------------------------------------------------------------- | | minTime | number | 600 | Minimum display time in ms | | template | string | built-in | Custom HTML for the splash screen | | style | string | built-in | Custom CSS for the splash screen | | appMountId | string | 'app' | Mount point ID to observe (used in mounted mode) | | hideOn | 'mounted' \| 'manual' | 'mounted' | When to close: after mount detection, or manually via window.__splashDone | | doneCallbackName | string | '__splashDone' | Global function name for manual close (only used when hideOn: 'manual') |

Custom Template & Style

You can fully customize the splash screen's HTML and CSS:

splashScreen({
  template: `
    <div id="vite-splash-screen">
      <div style="display:flex;flex-direction:column;align-items:center;gap:20px;">
        <svg width="80" height="80" viewBox="0 0 100 100" fill="none">
          <circle cx="50" cy="50" r="45" fill="#10B981"/>
          <text x="50" y="65" text-anchor="middle" fill="white" font-size="40" font-weight="bold">S</text>
        </svg>
        <div style="font-size:24px;font-weight:800;color:#111827;">Scilit</div>
        <div class="splash-spinner"></div>
      </div>
    </div>
  `,
  style: `
    #vite-splash-screen {
      position: fixed;
      inset: 0;
      display: flex;
      justify-content: center;
      align-items: center;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      z-index: 9999;
      opacity: 1;
      transition: opacity 0.3s ease-out, visibility 0.3s ease-out;
    }
    #vite-splash-screen.hidden {
      opacity: 0;
      visibility: hidden;
    }
    .splash-spinner {
      width: 36px;
      height: 36px;
      border: 3px solid rgba(255,255,255,0.3);
      border-top-color: #fff;
      border-radius: 50%;
      animation: splash-spin 0.8s linear infinite;
    }
    @keyframes splash-spin {
      to { transform: rotate(360deg); }
    }
  `,
});

Note: Your template must contain an element with id="vite-splash-screen" — the plugin uses this ID to fade out and remove the splash screen.

You can fully customize the splash screen's HTML and CSS:

splashScreen({
  template: `
    <div id="vite-splash-screen">
      <div style="display:flex;flex-direction:column;align-items:center;gap:20px;">
        <svg width="80" height="80" viewBox="0 0 100 100" fill="none">
          <circle cx="50" cy="50" r="45" fill="#10B981"/>
          <text x="50" y="65" text-anchor="middle" fill="white" font-size="40" font-weight="bold">S</text>
        </svg>
        <div style="font-size:24px;font-weight:800;color:#111827;">Scilit</div>
        <div class="splash-spinner"></div>
      </div>
    </div>
  `,
  style: `
    #vite-splash-screen {
      position: fixed;
      inset: 0;
      display: flex;
      justify-content: center;
      align-items: center;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      z-index: 9999;
      opacity: 1;
      transition: opacity 0.3s ease-out, visibility 0.3s ease-out;
    }
    #vite-splash-screen.hidden {
      opacity: 0;
      visibility: hidden;
    }
    .splash-spinner {
      width: 36px;
      height: 36px;
      border: 3px solid rgba(255,255,255,0.3);
      border-top-color: #fff;
      border-radius: 50%;
      animation: splash-spin 0.8s linear infinite;
    }
    @keyframes splash-spin {
      to { transform: rotate(360deg); }
    }
  `,
});

Note: Your template must contain an element with id="vite-splash-screen" — the plugin uses this ID to fade out and remove the splash screen.

License

MIT