VuePress NProgress Plugin

The VuePress NProgress Plugin integrates NProgress, a JavaScript progress bar library, to provide visual feedback during page navigation and loading in VuePress documentation sites. It automatically displays a slim progress bar at the top of the page during route transitions, enhancing user experience by providing visual feedback when content is being loaded.

Package Information

• Package Name: @vuepress/plugin-nprogress
• Package Type: npm
• Language: JavaScript (ES6+ with modules)
• Installation: npm install @vuepress/plugin-nprogress

Core Imports

As a VuePress plugin, this package is typically used through VuePress configuration rather than direct imports:

// .vuepress/config.js
module.exports = {
  plugins: [
    '@vuepress/plugin-nprogress'
  ]
}

Direct plugin object access (for plugin development):

const nprogressPlugin = require('@vuepress/plugin-nprogress');

Client-side code uses ES6 modules:

import Vue from 'vue';
import nprogress from 'nprogress';

Basic Usage

Standard Plugin Installation

Install the plugin in your VuePress site configuration:

// .vuepress/config.js
module.exports = {
  plugins: [
    '@vuepress/plugin-nprogress'
  ]
}

The plugin will automatically:

• Display a progress bar during page navigation
• Hide the progress bar when navigation completes
• Style the progress bar to match your VuePress theme

Alternative Configuration Syntax

// .vuepress/config.js
module.exports = {
  plugins: {
    '@vuepress/plugin-nprogress': {}
  }
}

Capabilities

Plugin Configuration

The main plugin export that defines VuePress plugin configuration.

/**
 * VuePress plugin configuration object
 * @type {import('@vuepress/types').Plugin}
 */
module.exports = {
  clientRootMixin: string;
  enhanceAppFiles: string;
}

The plugin configuration provides:

• clientRootMixin: Path to Vue mixin that handles router integration
• enhanceAppFiles: Path to file that imports necessary stylesheets

Client-Side Navigation Integration

The plugin includes a Vue mixin that automatically integrates with VuePress router:

/**
 * Vue mixin for NProgress integration
 * Automatically mounted when VuePress loads
 */
export default {
  mounted() {
    // Configure NProgress and set up router hooks
    // Sets showSpinner: false and integrates with Vue Router
  }
}

Router Integration Features:

• Progress Start: Automatically starts progress bar when navigating to different routes
• Progress Complete: Automatically completes progress bar when navigation finishes
• Sidebar Management: Closes sidebar after navigation completes
• Performance Optimization: Only shows progress for actual route changes using !Vue.component(to.name) check to avoid showing progress for cached components

Styling Configuration

The plugin includes custom Stylus styling that integrates with VuePress theming:

// Progress bar styling variables
$nprogressColor ?= $accentColor

// Progress bar elements
#nprogress
  pointer-events none
  .bar
    background $nprogressColor
    position fixed
    z-index 1031
    top 0
    left 0
    width 100%
    height 2px
  .peg
    display block
    position absolute
    right 0px
    width 100px
    height 100%
    box-shadow 0 0 10px $nprogressColor, 0 0 5px $nprogressColor
    opacity 1.0
    transform rotate(3deg) translate(0px, -4px)
  .spinner
    display block
    position fixed
    z-index 1031
    top 15px
    right 15px

Styling Features:

• Theme Integration: Uses VuePress $accentColor for progress bar color
• Responsive Design: Adapts to different screen sizes
• Clean Appearance: Spinner is disabled by default for cleaner look
• Customizable: Can be overridden with custom CSS

Architecture

The plugin follows VuePress plugin architecture patterns:

• Plugin Entry: Main index.js exports plugin configuration object
• Client-Side Integration: Uses VuePress clientRootMixin to integrate with Vue app lifecycle
• Asset Enhancement: Uses enhanceAppFiles to include necessary stylesheets
• Router Hooks: Leverages Vue Router beforeEach and afterEach hooks for navigation tracking
• Zero Configuration: Works out-of-the-box with no required configuration options

Integration Points

VuePress Plugin System

• Implements the VuePress Plugin interface from @vuepress/types
• Provides clientRootMixin and enhanceAppFiles configuration options
• Automatically loaded by VuePress build system

Vue Router Integration

• Hooks into $router.beforeEach for navigation start detection
• Hooks into $router.afterEach for navigation completion
• Conditionally shows progress based on route changes and component caching

NProgress Library

• Uses nprogress.configure({ showSpinner: false }) for initialization
• Calls nprogress.start() when navigation begins
• Calls nprogress.done() when navigation completes

Dependencies

• @vuepress/types@1.9.10: VuePress TypeScript definitions for plugin interface
• nprogress@^0.2.0: Core NProgress library for progress bar functionality

Notes

• No Configuration Options: The plugin requires no user configuration
• Automatic Operation: Works automatically once installed in VuePress config
• Theme Compatible: Integrates seamlessly with VuePress theming system
• Performance Optimized: Only displays progress for actual navigation, not cached route transitions
• Accessibility: Provides visual feedback for users during potentially slow page loads