0
# VuePress NProgress Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @vuepress/plugin-nprogress
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6+ with modules)
9
- **Installation**: `npm install @vuepress/plugin-nprogress`
10

11
## Core Imports
12

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

15
```javascript
16
// .vuepress/config.js
17
module.exports = {
18
  plugins: [
19
    '@vuepress/plugin-nprogress'
20
  ]
21
}
22
```
23

24
Direct plugin object access (for plugin development):
25

26
```javascript
27
const nprogressPlugin = require('@vuepress/plugin-nprogress');
28
```
29

30
Client-side code uses ES6 modules:
31

32
```javascript
33
import Vue from 'vue';
34
import nprogress from 'nprogress';
35
```
36

37
## Basic Usage
38

39
### Standard Plugin Installation
40

41
Install the plugin in your VuePress site configuration:
42

43
```javascript
44
// .vuepress/config.js
45
module.exports = {
46
  plugins: [
47
    '@vuepress/plugin-nprogress'
48
  ]
49
}
50
```
51

52
The plugin will automatically:
53
- Display a progress bar during page navigation
54
- Hide the progress bar when navigation completes
55
- Style the progress bar to match your VuePress theme
56

57
### Alternative Configuration Syntax
58

59
```javascript
60
// .vuepress/config.js
61
module.exports = {
62
  plugins: {
63
    '@vuepress/plugin-nprogress': {}
64
  }
65
}
66
```
67

68
## Capabilities
69

70
### Plugin Configuration
71

72
The main plugin export that defines VuePress plugin configuration.
73

74
```javascript { .api }
75
/**
76
 * VuePress plugin configuration object
77
 * @type {import('@vuepress/types').Plugin}
78
 */
79
module.exports = {
80
  clientRootMixin: string;
81
  enhanceAppFiles: string;
82
}
83
```
84

85
The plugin configuration provides:
86
- `clientRootMixin`: Path to Vue mixin that handles router integration
87
- `enhanceAppFiles`: Path to file that imports necessary stylesheets
88

89
### Client-Side Navigation Integration
90

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

93
```javascript { .api }
94
/**
95
 * Vue mixin for NProgress integration
96
 * Automatically mounted when VuePress loads
97
 */
98
export default {
99
  mounted() {
100
    // Configure NProgress and set up router hooks
101
    // Sets showSpinner: false and integrates with Vue Router
102
  }
103
}
104
```
105

106
#### Router Integration Features:
107
- **Progress Start**: Automatically starts progress bar when navigating to different routes
108
- **Progress Complete**: Automatically completes progress bar when navigation finishes
109
- **Sidebar Management**: Closes sidebar after navigation completes
110
- **Performance Optimization**: Only shows progress for actual route changes using `!Vue.component(to.name)` check to avoid showing progress for cached components
111

112
### Styling Configuration
113

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

116
```stylus { .api }
117
// Progress bar styling variables
118
$nprogressColor ?= $accentColor
119

120
// Progress bar elements
121
#nprogress
122
  pointer-events none
123
  .bar
124
    background $nprogressColor
125
    position fixed
126
    z-index 1031
127
    top 0
128
    left 0
129
    width 100%
130
    height 2px
131
  .peg
132
    display block
133
    position absolute
134
    right 0px
135
    width 100px
136
    height 100%
137
    box-shadow 0 0 10px $nprogressColor, 0 0 5px $nprogressColor
138
    opacity 1.0
139
    transform rotate(3deg) translate(0px, -4px)
140
  .spinner
141
    display block
142
    position fixed
143
    z-index 1031
144
    top 15px
145
    right 15px
146
```
147

148
#### Styling Features:
149
- **Theme Integration**: Uses VuePress `$accentColor` for progress bar color
150
- **Responsive Design**: Adapts to different screen sizes
151
- **Clean Appearance**: Spinner is disabled by default for cleaner look
152
- **Customizable**: Can be overridden with custom CSS
153

154
## Architecture
155

156
The plugin follows VuePress plugin architecture patterns:
157

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

164
## Integration Points
165

166
### VuePress Plugin System
167
- Implements the VuePress `Plugin` interface from `@vuepress/types`
168
- Provides `clientRootMixin` and `enhanceAppFiles` configuration options
169
- Automatically loaded by VuePress build system
170

171
### Vue Router Integration
172
- Hooks into `$router.beforeEach` for navigation start detection
173
- Hooks into `$router.afterEach` for navigation completion
174
- Conditionally shows progress based on route changes and component caching
175

176
### NProgress Library
177
- Uses `nprogress.configure({ showSpinner: false })` for initialization
178
- Calls `nprogress.start()` when navigation begins
179
- Calls `nprogress.done()` when navigation completes
180

181
## Dependencies
182

183
- **@vuepress/types@1.9.10**: VuePress TypeScript definitions for plugin interface
184
- **nprogress@^0.2.0**: Core NProgress library for progress bar functionality
185

186
## Notes
187

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