Vite Plugin App Loading

0.5.4 verified Mon Apr 27 auth: no javascript

vite-plugin-app-loading (v0.5.4) is a Vite plugin that injects a custom loading animation into the HTML entry point during development and production builds, which automatically hides when the app mounts. It uses a virtual import `virtual:app-loading` to expose a `loadingFadeOut()` function for manual dismissal. The plugin supports custom HTML/CSS loading animations via a configurable path. It requires Vite ^6.0.0, ^7.0.0, or ^8.0.0 as a peer dependency. TypeScript types are shipped via `vite-plugin-app-loading/client`. Updated regularly with dependency bumps and build tool changes (e.g., tsup replaced by tsdown in v0.4.0).

Common errors

error Cannot find module 'virtual:app-loading' or its corresponding type declarations. ↓

cause Missing TypeScript reference for the virtual module.

fix

Add "vite-plugin-app-loading/client" to compilerOptions.types in tsconfig.json, or add /// <reference types="vite-plugin-app-loading/client" /> in a .d.ts file.

error TypeError: AppLoading is not a function ↓

cause Importing the plugin as a named import instead of default.

fix

Use import AppLoading from 'vite-plugin-app-loading' (no braces).

error Module not found: Error: Can't resolve 'vite-plugin-app-loading' ↓

cause Package not installed or missing peer dependency Vite >=6.

fix

Run npm i vite-plugin-app-loading -D and ensure a compatible Vite version (6, 7, or 8) is installed.

error TypeError: failed to fetch (loading HTML not found) ↓

cause Custom loading.html path is incorrect or file doesn't exist at the given relative path.

fix

Verify the path (e.g., AppLoading('src/loading.html')) and ensure the file exists at that relative path from project root.

Warnings

breaking Package renamed from `vite-plugin-vue-app-loading` to `vite-plugin-app-loading` in v0.3.0. ↓

fix Uninstall old package: `npm rm vite-plugin-vue-app-loading` and install new: `npm i vite-plugin-app-loading -D`. Update import path.

gotcha Virtual import must be `virtual:app-loading`, not a direct file path. ↓

fix Use `import { loadingFadeOut } from 'virtual:app-loading'` exactly.

breaking Vite peer dependency constraint: v0.5.x requires Vite ^6.0.0, ^7.0.0, or ^8.0.0. ↓

fix Upgrade to Vite 6, 7, or 8. For earlier Vite versions, pin to vite-plugin-app-loading@0.4.x.

gotcha Custom loading.html path is resolved relative to project root, not an absolute path. ↓

fix Pass relative path from project root (e.g., `AppLoading('src/loading.html')`) or resolve absolutely using `path.resolve`.

gotcha TypeScript virtual module typing requires explicit reference via `vite-plugin-app-loading/client`. ↓

fix Add `/// <reference types="vite-plugin-app-loading/client" />` in a .d.ts file or add `"vite-plugin-app-loading/client"` to compilerOptions.types in tsconfig.json.

Install

npm install vite-plugin-app-loading

yarn add vite-plugin-app-loading

pnpm add vite-plugin-app-loading

Imports

AppLoading (default)

wrong

import { AppLoading } from 'vite-plugin-app-loading'

correct

import AppLoading from 'vite-plugin-app-loading'

Uses default export – named import will fail.

loadingFadeOut (virtual)

wrong

import { loadingFadeOut } from 'vite-plugin-app-loading'

correct

import { loadingFadeOut } from 'virtual:app-loading'

Virtual module path is `virtual:app-loading`, not the package name.

client types reference

wrong

/// <reference types="vite-plugin-app-loading" />

correct

/// <reference types="vite-plugin-app-loading/client" />

Use `/client` path to access virtual module types.

Quickstart

Shows minimal setup: import the plugin and add it to the Vite config. Also demonstrates calling loadingFadeOut from virtual module.

// vite.config.ts
import AppLoading from 'vite-plugin-app-loading'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    AppLoading(), // uses built-in loading.html
  ],
})