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