npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

vite-plugin-splash-screen

v0.0.2

Published

Vite plugin for adding a splash screen to your app

Downloads

347

Readme

Demo of vite-plugin-splash-screen with line style loading indicator

💦 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 vite-plugin-splash-screen you get the following:

  • 🤹 Framework-agnostic: Works with any frontend framework that uses Vite!
  • 🎨 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 Vite config and you are good to go.

📲 Installation

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

npm install -D vite-plugin-splash-screen

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

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

🧑‍💻 Usage

Import the plugin and add it to you Vite config.

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

import { splashScreen } from "vite-plugin-splash-screen";

export default defineConfig({
  plugins: [
    /* ...other plugins... */
    splashScreen({
      logoSrc: "logo.svg",
    }),
  ],
});

[!IMPORTANT]
Only SVG logos are supported at the moment so that the logo can be inlined to the HTML file.

Make sure the logo has appropriate dimensions and is optimized for the web. See SVGOMG for optimizing SVG files.

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 "vite-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 "vite-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:

splashScreen({
  logoSrc: "logo.svg",
  minDurationMs: 2000,
});

loaderType

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

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

With "dots" you get the following loading indicator:

splashScreen({
  logoSrc: "logo.svg",
  loaderType: "dots",
});

Demo of vite-plugin-splash-screen with dots style loading indicator

Provide "none" to hide the loading indicator:

splashScreen({
  logoSrc: "logo.svg",
  loaderType: "none",
});

Demo of vite-plugin-splash-screen with no loading indicator

loaderBg

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

Example:

splashScreen({
  logoSrc: "logo.svg",
  loaderType: "line",
  loaderBg: "#ff0000",
});

splashBg

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

Example:

splashScreen({
  logoSrc: "logo.svg",
  splashBg: "#000000",
});

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 easily achieve this by utilizing the vite-plugin-color-scheme plugin to inline a small script to setup the CSS variables based on the user's preferred color scheme.

// vite.config.ts
import { splashScreen } from "vite-plugin-splash-screen";
import { colorScheme } from "vite-plugin-color-scheme";

export default defineConfig({
  plugins: [
    colorScheme({
      defaultScheme: "light",
      variables: {
        light: {
          "--vpss-bg-splash": "#ffffff",
          "--vpss-bg-loader": "#b18500",
        },
        dark: {
          "--vpss-bg-splash": "#242424",
          "--vpss-bg-loader": "#ffcb29",
        },
      },
    }),
    splashScreen({
      /* ...your options... */
    }),
  ],
});