0
# @vue/cli-plugin-router
1

2
@vue/cli-plugin-router is a Vue CLI plugin that automatically adds Vue Router support to Vue.js applications. It provides code generation functionality to set up routing infrastructure, including router configuration, route definitions, and navigation components for both Vue 2 and Vue 3 projects.
3

4
## Package Information
5

6
- **Package Name**: @vue/cli-plugin-router
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `vue add router`
10

11
## Core Imports
12

13
The plugin is typically invoked through Vue CLI rather than imported directly:
14

15
```bash
16
vue add router
17
```
18

19
For programmatic usage (advanced use cases):
20

21
```javascript
22
const routerPlugin = require("@vue/cli-plugin-router");
23
const routerGenerator = require("@vue/cli-plugin-router/generator");
24
const routerPrompts = require("@vue/cli-plugin-router/prompts");
25
```
26

27
## Basic Usage
28

29
The most common usage is through Vue CLI's add command:
30

31
```bash
32
# Add router plugin to existing Vue project
33
vue add router
34

35
# The plugin will prompt for configuration:
36
# ? Use history mode for router? (Y/n)
37
```
38

39
This automatically:
40
- Installs the appropriate vue-router version (3.x for Vue 2, 4.x for Vue 3)
41
- Creates router configuration files
42
- Generates basic route components (Home, About)
43
- Updates App.vue with navigation
44
- Configures the application entry point
45

46
## Capabilities
47

48
### Plugin Entry Point
49

50
Main plugin function that integrates with Vue CLI's plugin system.
51

52
```javascript { .api }
53
/**
54
 * Main plugin entry point (currently empty implementation)
55
 * @param api - Vue CLI plugin API instance
56
 * @param options - Plugin configuration options
57
 */
58
function routerPlugin(api: PluginAPI, options: PluginOptions): void;
59

60
interface PluginOptions {
61
  [key: string]: any;
62
}
63
```
64

65
### Plugin Prompts Configuration
66

67
Defines interactive prompts shown when the plugin is invoked.
68

69
```javascript { .api }
70
/**
71
 * Plugin prompts configuration for user interaction
72
 */
73
const prompts: PromptDefinition[];
74

75
interface PromptDefinition {
76
  name: string;
77
  type: 'confirm' | 'input' | 'list' | 'checkbox';
78
  message: string;
79
  description?: string;
80
  default?: any;
81
  choices?: any[];
82
  when?: (answers: any) => boolean;
83
}
84
```
85

86
The router plugin defines one prompt:
87

88
```javascript { .api }
89
const historyModePrompt: PromptDefinition = {
90
  name: 'historyMode',
91
  type: 'confirm',
92
  message: 'Use history mode for router? (Requires proper server setup for index fallback in production)',
93
  description: 'By using the HTML5 History API, the URLs don\'t need the \'#\' character anymore.'
94
};
95
```
96

97
### Generator Function
98

99
Core generator that performs the router setup and file generation.
100

101
```javascript { .api }
102
/**
103
 * Main generator function that configures router in Vue projects
104
 * @param api - Vue CLI Generator API instance
105
 * @param options - User-selected options from prompts
106
 * @param rootOptions - Project-level configuration options
107
 */
108
function routerGenerator(
109
  api: GeneratorAPI,
110
  options: RouterOptions,
111
  rootOptions: RootOptions
112
): void;
113

114
interface RouterOptions {
115
  historyMode?: boolean;
116
}
117

118
interface RootOptions {
119
  vueVersion?: '2' | '3';
120
  cssPreprocessor?: string;
121
  bare?: boolean;
122
}
123
```
124

125
### Vue 3 AST Transformer
126

127
Transforms Vue 3 application entry files to inject router usage.
128

129
```javascript { .api }
130
/**
131
 * AST transformer for injecting router usage in Vue 3 apps
132
 * @param file - File object containing source code
133
 * @param api - Transformation API with jscodeshift instance
134
 * @returns Transformed source code as string
135
 */
136
function injectUseRouter(file: FileInfo, api: TransformAPI): string;
137

138
interface FileInfo {
139
  path: string;
140
  source: string;
141
}
142

143
interface TransformAPI {
144
  jscodeshift: JSCodeshift;
145
}
146
```
147

148
### Generator API Methods
149

150
The plugin utilizes Vue CLI's Generator API methods for code generation:
151

152
```javascript { .api }
153
interface GeneratorAPI {
154
  /** Inject import statements into the entry file */
155
  injectImports(file: string, imports: string): void;
156
  
157
  /** Apply AST transformations to a script file */
158
  transformScript(file: string, transformer: Function): void;
159
  
160
  /** Inject options into Vue root instance (Vue 2) */
161
  injectRootOptions(file: string, options: string): void;
162
  
163
  /** Add dependencies to package.json */
164
  extendPackage(packageModifications: PackageModifications): void;
165
  
166
  /** Render template files to the project */
167
  render(templatePath: string, data: TemplateData): void;
168
  
169
  /** Check if another plugin is installed */
170
  hasPlugin(pluginName: string): boolean;
171
  
172
  /** Boolean indicating if plugin is being invoked */
173
  invoking: boolean;
174
  
175
  /** Path to the main entry file */
176
  entryFile: string;
177
}
178

179
interface PackageModifications {
180
  dependencies?: Record<string, string>;
181
  devDependencies?: Record<string, string>;
182
  scripts?: Record<string, string>;
183
}
184

185
interface TemplateData {
186
  /** Whether to use HTML5 History API (true) or hash mode (false) */
187
  historyMode?: boolean;
188
  /** Whether Babel or TypeScript plugins are present for compilation */
189
  doesCompile?: boolean;
190
  /** Whether TypeScript plugin is installed */
191
  hasTypeScript?: boolean;
192
}
193
```
194

195
## Generated Project Structure
196

197
When the plugin runs, it creates the following files:
198

199
### Router Configuration (Vue 2)
200
```javascript
201
// src/router/index.js
202
import Vue from 'vue'
203
import VueRouter from 'vue-router'
204
import HomeView from '../views/HomeView.vue'
205

206
Vue.use(VueRouter)
207

208
const routes = [
209
  {
210
    path: '/',
211
    name: 'home',
212
    component: HomeView
213
  },
214
  {
215
    path: '/about',
216
    name: 'about',
217
    component: () => import('../views/AboutView.vue')
218
  }
219
]
220

221
const router = new VueRouter({
222
  mode: 'history', // Only if historyMode: true
223
  base: process.env.BASE_URL,
224
  routes
225
})
226

227
export default router
228
```
229

230
### Router Configuration (Vue 3)
231
```javascript
232
// src/router/index.js
233
import { createRouter, createWebHistory, createWebHashHistory } from 'vue-router'
234
import HomeView from '../views/HomeView.vue'
235

236
const routes = [
237
  {
238
    path: '/',
239
    name: 'home',
240
    component: HomeView
241
  },
242
  {
243
    path: '/about',
244
    name: 'about',
245
    component: () => import('../views/AboutView.vue')
246
  }
247
]
248

249
const router = createRouter({
250
  // Uses createWebHistory if historyMode: true, createWebHashHistory if historyMode: false
251
  history: createWebHistory(process.env.BASE_URL), // or createWebHashHistory()
252
  routes
253
})
254

255
export default router
256
```
257

258
### View Components
259
The plugin generates two basic view components:
260

261
- `src/views/HomeView.vue` - Home page component
262
- `src/views/AboutView.vue` - About page component (lazy-loaded)
263

264
### Updated App Component
265
Modifies `src/App.vue` to include router navigation:
266

267
```vue
268
<template>
269
  <div id="app">
270
    <nav>
271
      <router-link to="/">Home</router-link> |
272
      <router-link to="/about">About</router-link>
273
    </nav>
274
    <router-view/>
275
  </div>
276
</template>
277
```
278

279
## Configuration Options
280

281
### History Mode
282
Controls the router mode:
283
- `historyMode: true` - Uses HTML5 History API (clean URLs without #)
284
- `historyMode: false` - Uses hash mode (URLs with # fragment)
285

286
### Vue Version Detection
287
Automatically detects Vue version and installs appropriate router version:
288
- Vue 2: `vue-router@^3.5.1`
289
- Vue 3: `vue-router@^4.0.3`
290

291
### TypeScript Support
292
When TypeScript plugin is detected, the generated templates include proper type annotations:
293
- Router configuration uses `RouteConfig` (Vue 2) or `RouteRecordRaw` (Vue 3) types
294
- Generated files use `.ts` extensions when appropriate
295
- Imports include type definitions from vue-router
296
- Converts generated files to TypeScript automatically during invocation
297

298
### Integration Features
299
- **Babel Integration**: Enables dynamic imports for code splitting
300
- **CSS Preprocessor Support**: Adapts styling in generated components
301
- **Bare Project Mode**: Simplified setup for minimal projects
302

303
## Dependencies
304

305
### Runtime Dependencies
306
- `@vue/cli-shared-utils@^5.0.9` - Shared utilities for Vue CLI plugins
307

308
### Peer Dependencies
309
- `@vue/cli-service@^3.0.0 || ^4.0.0 || ^5.0.0-0` - Vue CLI service
310

311
### Generated Dependencies
312
- `vue-router@^3.5.1` (for Vue 2 projects)
313
- `vue-router@^4.0.3` (for Vue 3 projects)
314

315
## Error Handling
316

317
The plugin gracefully handles various scenarios:
318
- Automatically detects Vue version and uses appropriate router API
319
- Integrates with existing plugins (Babel, TypeScript) when present
320
- Converts files to TypeScript during invocation if TypeScript plugin exists
321
- Provides appropriate fallbacks for different build configurations