Registry / web-framework / vite-plugin-app-loading

vite-plugin-app-loading

library0.5.4jsnpmunverified

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).

web-framework

npm install vite-plugin-app-loading

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-APP-LO

vite-plugin-app-loading

web-frameworkjavascriptv0.5.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AppLoading (default)

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

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

Uses default export – named import will fail.

loadingFadeOut (virtual)

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

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

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

client types reference

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

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

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

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 ], })

Debug

Known issues

breakingPackage 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.

affects: <0.3.0

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

fix

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

affects: >=0.1.0

breakingVite 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.

affects: >=0.5.0

gotchaCustom 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`.

affects: >=0.1.0

gotchaTypeScript 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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.

TypeError: AppLoading is not a function

Importing the plugin as a named import instead of default.

fix

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

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

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.

TypeError: failed to fetch (loading HTML not found)

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.

Upgrade

Version history

0.5.4latest on npm

Audit

Dependencies

viterequiredpeer dependency – requires Vite ^6.0.0, ^7.0.0, or ^8.0.0

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/hooray/vite-plugin-app-loading ↗

packagehttps://www.npmjs.com/package/vite-plugin-app-loading ↗