0
# @vue/cli-plugin-vuex
1

2
@vue/cli-plugin-vuex is a Vue CLI plugin that automatically integrates Vuex state management into Vue.js projects. It provides seamless setup for both Vue 2 and Vue 3 projects with appropriate version-specific configurations and includes TypeScript support when applicable.
3

4
## Package Information
5

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

11
## Core Imports
12

13
This plugin operates through the Vue CLI system and doesn't require direct imports. Installation is handled via the Vue CLI:
14

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

19
For accessing generated store in your application:
20

21
```javascript
22
// Vue 2 projects - automatically injected
23
import store from './store'
24

25
// Vue 3 projects - automatically injected and configured
26
import store from './store'
27
```
28

29
## Basic Usage
30

31
After installation, the plugin automatically:
32

33
1. Adds appropriate Vuex dependency to your project
34
2. Creates a basic store structure in `src/store/index.js`
35
3. Configures your main entry file to use the store
36

37
```javascript
38
// Generated store structure (Vue 2)
39
import Vue from 'vue'
40
import Vuex from 'vuex'
41

42
Vue.use(Vuex)
43

44
export default new Vuex.Store({
45
  state: {},
46
  getters: {},
47
  mutations: {},
48
  actions: {},
49
  modules: {}
50
})
51
```
52

53
```javascript
54
// Generated store structure (Vue 3)
55
import { createStore } from 'vuex'
56

57
export default createStore({
58
  state: {},
59
  getters: {},
60
  mutations: {},
61
  actions: {},
62
  modules: {}
63
})
64
```
65

66
## Capabilities
67

68
### Plugin Entry Point
69

70
The main plugin function that gets called by Vue CLI during installation. This is an empty function as all functionality is handled by the generator.
71

72
```javascript { .api }
73
/**
74
 * Main plugin entry point - called by Vue CLI (currently empty implementation)
75
 * @param api - Vue CLI plugin API instance  
76
 * @param options - Plugin configuration options (defaults to empty object)
77
 */
78
function plugin(api: any, options: object = {}): void;
79
```
80

81
### Generator Function
82

83
Core generator that performs the Vuex integration setup.
84

85
```javascript { .api }
86
/**
87
 * Generator function that adds Vuex to Vue projects
88
 * @param api - Vue CLI generator API instance
89
 * @param options - Plugin options (defaults to empty object)
90
 * @param rootOptions - Root project options including Vue version
91
 */
92
function generator(
93
  api: GeneratorAPI,
94
  options: object = {},
95
  rootOptions: object = {}
96
): void;
97

98
interface GeneratorAPI {
99
  /** Entry file path (typically main.js or main.ts) */
100
  entryFile: string;
101
  /** Flag indicating if plugin is being invoked */
102
  invoking: boolean;
103
  /** Inject import statements into a file */
104
  injectImports(file: string, imports: string): void;
105
  /** Inject root options into Vue instance (Vue 2) */
106
  injectRootOptions(file: string, options: string): void;
107
  /** Apply JavaScript transformations to a file using jscodeshift */
108
  transformScript(file: string, transformer: (file: FileInfo, api: JSCAPI) => string): void;
109
  /** Add dependencies to package.json */
110
  extendPackage(packageData: object): void;
111
  /** Render template files to project */
112
  render(templatePath: string, data?: object): void;
113
  /** Check if a plugin is installed */
114
  hasPlugin(pluginName: string): boolean;
115
}
116
```
117

118
### Vue 3 Script Transformer
119

120
Transform function for Vue 3 applications to inject store usage.
121

122
```javascript { .api }
123
/**
124
 * jscodeshift transformer for Vue 3 main entry files
125
 * Modifies createApp() calls to include .use(store)
126
 * @param file - File object containing source code
127
 * @param api - jscodeshift API with transformation utilities
128
 * @returns Transformed source code
129
 */
130
function injectUseStore(
131
  file: FileInfo,
132
  api: JSCAPI
133
): string;
134

135
interface FileInfo {
136
  /** Source code of the file */
137
  source: string;
138
  /** File path */
139
  path: string;
140
}
141

142
interface JSCAPI {
143
  /** jscodeshift core transformation library */
144
  jscodeshift: JSCodeshift;
145
}
146

147
interface JSCodeshift {
148
  /** Create AST from source code */
149
  (source: string): Collection;
150
  /** Call expression AST node constructor */
151
  CallExpression: CallExpressionBuilder;
152
  /** Member expression AST node constructor */
153
  MemberExpression: MemberExpressionBuilder;
154
  /** Identifier AST node constructor */
155
  Identifier: IdentifierBuilder;
156
  /** Create a call expression node */
157
  callExpression(callee: any, args: any[]): any;
158
  /** Create a member expression node */
159
  memberExpression(object: any, property: any): any;
160
  /** Create an identifier node */
161
  identifier(name: string): any;
162
}
163

164
interface Collection {
165
  /** Find nodes matching criteria */
166
  find(nodeType: any, filter?: (node: any) => boolean): Collection;
167
  /** Replace matched nodes */
168
  replaceWith(replacement: (path: any) => any): Collection;
169
  /** Output transformed source code */
170
  toSource(): string;
171
}
172

173
interface CallExpressionBuilder {
174
  /** Check if node is a call expression */
175
  check(node: any): boolean;
176
}
177

178
interface MemberExpressionBuilder {
179
  /** Check if node is a member expression */
180
  check(node: any): boolean;
181
}
182

183
interface IdentifierBuilder {
184
  /** Check if node is an identifier */
185
  check(node: any): boolean;
186
}
187
```
188

189
## Generated Dependencies
190

191
The plugin automatically adds the appropriate Vuex version based on your Vue version:
192

193
### Vue 2 Projects
194
- **vuex**: ^3.6.2
195

196
### Vue 3 Projects  
197
- **vuex**: ^4.0.0
198

199
## Generated Files
200

201
### Store Structure
202

203
The plugin creates `src/store/index.js` with a basic Vuex store structure:
204

205
**Vue 2 Template:**
206
```javascript
207
import Vue from 'vue'
208
import Vuex from 'vuex'
209

210
Vue.use(Vuex)
211

212
export default new Vuex.Store({
213
  state: {},
214
  getters: {},
215
  mutations: {},
216
  actions: {},
217
  modules: {}
218
})
219
```
220

221
**Vue 3 Template:**
222
```javascript
223
import { createStore } from 'vuex'
224

225
export default createStore({
226
  state: {},
227
  getters: {},
228
  mutations: {},
229
  actions: {},
230
  modules: {}
231
})
232
```
233

234
### Main Entry File Modifications
235

236
**Vue 2 Projects:**
237
- Adds `import store from './store'`
238
- Injects `store` into root Vue options
239

240
**Vue 3 Projects:**
241
- Adds `import store from './store'`
242
- Transforms `createApp()` calls to `createApp().use(store)`
243

244
## TypeScript Integration
245

246
When the TypeScript plugin is detected during installation:
247
- Automatically converts generated JavaScript files to TypeScript
248
- Uses `@vue/cli-plugin-typescript/generator/convert` for file conversion
249
- Maintains type safety and proper TypeScript configurations
250

251
## Plugin Architecture Integration
252

253
This plugin follows Vue CLI plugin architecture patterns:
254

255
### Installation Flow
256
1. Plugin entry point is called by Vue CLI
257
2. Generator function performs the actual setup
258
3. Files are rendered from templates based on Vue version
259
4. Dependencies are added to package.json
260
5. Main entry file is modified to include store integration
261
6. TypeScript conversion happens if TypeScript plugin is present
262

263
### API Integration Points
264
- Integrates with Vue CLI's generator API
265
- Uses jscodeshift for code transformations
266
- Follows Vue CLI's plugin naming and structure conventions
267
- Supports both invocation time and post-installation scenarios