Nuxt Loaders

Simple loading screen engine for Nuxt 4+.

• ✨  Release Notes

Features

• 🔄 Automatic Loader Registration: Automatically registers loader components from your specified directory as global components.
• 🛣️ Route-based Configuration: Assign specific loaders to different routes using routeRules.
• 🎨 TailwindCSS Integration: Includes TailwindCSS support out of the box.
• ⚡ Zero Configuration: Works with sensible defaults, but is fully customizable.

Quick Setup

1. Add nuxt-loaders dependency to your project:

npx nuxi module add nuxt-loaders

2. Add nuxt-loaders to the modules section of nuxt.config.ts (if not already added by nuxi):

export default defineNuxtConfig({
  modules: ["nuxt-loaders"],
});

That's it! You can now use Nuxt Loaders in your Nuxt app ✨

Configuration

You can configure the module in your nuxt.config.ts. The components in loadersDir will be automatically imported and can be referenced by name in routeRules.

export default defineNuxtConfig({
  modules: ["nuxt-loaders"],
  loaders: {
    // Directory containing your loader components
    // Default: 'app/components/loaders'
    loadersDir: "app/components/loaders",

    // Automatically setup the module
    // Default: true
    autoSetup: true,

    // Define rules for which loader to use on which route
    routeRules: {
      "/": "MyLoader",
      "/admin/*": "AdminLoader",
    },
  },
});

Options

| Option | Type | Default | Description | | ------------ | ------------------------ | -------------------------- | --------------------------------------------------- | | loadersDir | string | 'app/components/loaders' | Directory where your loader components are located. | | autoSetup | boolean | true | Whether to automatically setup the module. | | routeRules | Record<string, string> | {} | Map of route patterns to loader component names. |

Usage

1. Add the Loader Component: Add the <Loader /> component to your app.vue (or layout) and control its visibility using useLoader.

   <script setup lang="ts">
   const { isLoading } = useLoader();
   </script>
   
   <template>
     <Loader v-if="isLoading" />
     <NuxtPage />
   </template>

2. Create your loader components: Place them in app/components/loaders (or your configured loadersDir).

3. Configure Route Rules: Use routeRules in your nuxt.config.ts to specify which loader should be active for specific routes.

Example loader component (app/components/loaders/MyLoader.vue):

<template>
  <div class="loader">Loading...</div>
</template>

Contribution

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.