0
# Vuex
1
2
Vuex is a state management pattern and library for Vue.js applications that serves as a centralized store for all components with rules ensuring predictable state mutations. It provides a single source of truth for application state, implements the Flux architecture pattern with actions, mutations, getters, and modules, and integrates seamlessly with Vue's reactivity system.
3
4
## Package Information
5
6
- **Package Name**: vuex
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install vuex`
10
11
## Core Imports
12
13
```typescript
14
import { createStore, useStore } from "vuex";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { createStore, useStore } = require("vuex");
21
```
22
23
Import helpers:
24
25
```typescript
26
import { mapState, mapMutations, mapGetters, mapActions } from "vuex";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import { createStore, useStore } from "vuex";
33
34
// Create store
35
const store = createStore({
36
state: {
37
count: 0,
38
todos: []
39
},
40
mutations: {
41
increment(state) {
42
state.count++;
43
},
44
addTodo(state, todo) {
45
state.todos.push(todo);
46
}
47
},
48
actions: {
49
async incrementAsync({ commit }) {
50
await new Promise(resolve => setTimeout(resolve, 1000));
51
commit('increment');
52
}
53
},
54
getters: {
55
doneTodos(state) {
56
return state.todos.filter(todo => todo.done);
57
}
58
}
59
});
60
61
// In Vue 3 component (Composition API)
62
import { useStore } from "vuex";
63
64
export default {
65
setup() {
66
const store = useStore();
67
68
// Access state
69
const count = computed(() => store.state.count);
70
71
// Commit mutations
72
const increment = () => store.commit('increment');
73
74
// Dispatch actions
75
const incrementAsync = () => store.dispatch('incrementAsync');
76
77
return { count, increment, incrementAsync };
78
}
79
};
80
```
81
82
## Architecture
83
84
Vuex implements the Flux architecture pattern with several key components:
85
86
- **State**: Single state tree that serves as the "single source of truth"
87
- **Mutations**: Synchronous functions that directly modify state
88
- **Actions**: Functions that can contain asynchronous operations and commit mutations
89
- **Getters**: Computed properties for derived state
90
- **Modules**: Namespace and organize store functionality for large applications
91
- **Plugins**: Extend store functionality with custom behaviors
92
93
## Capabilities
94
95
### Store Creation
96
97
Core functionality for creating and configuring Vuex stores with state, mutations, actions, and getters.
98
99
```typescript { .api }
100
function createStore<S>(options: StoreOptions<S>): Store<S>;
101
102
interface StoreOptions<S> {
103
state?: S | (() => S);
104
getters?: GetterTree<S, S>;
105
actions?: ActionTree<S, S>;
106
mutations?: MutationTree<S>;
107
modules?: ModuleTree<S>;
108
plugins?: Plugin<S>[];
109
strict?: boolean;
110
devtools?: boolean;
111
}
112
```
113
114
[Store Management](./store-management.md)
115
116
### Composition API Integration
117
118
Vue 3 Composition API integration for accessing stores in components.
119
120
```typescript { .api }
121
function useStore<S = any>(injectKey?: InjectionKey<Store<S>> | string): Store<S>;
122
123
const storeKey: string;
124
```
125
126
[Composition API](./composition-api.md)
127
128
### Component Helper Functions
129
130
Helper functions for mapping store properties to component computed properties and methods.
131
132
```typescript { .api }
133
function mapState<S>(states: string[]): { [key: string]: Computed };
134
function mapState<S>(namespace: string, states: string[]): { [key: string]: Computed };
135
136
function mapMutations(mutations: string[]): { [key: string]: MutationMethod };
137
function mapMutations(namespace: string, mutations: string[]): { [key: string]: MutationMethod };
138
139
function mapGetters(getters: string[]): { [key: string]: Computed };
140
function mapGetters(namespace: string, getters: string[]): { [key: string]: Computed };
141
142
function mapActions(actions: string[]): { [key: string]: ActionMethod };
143
function mapActions(namespace: string, actions: string[]): { [key: string]: ActionMethod };
144
145
function createNamespacedHelpers(namespace: string): NamespacedMappers;
146
```
147
148
[Component Helpers](./component-helpers.md)
149
150
### Module System
151
152
Modular organization system for complex applications with namespacing and dynamic registration.
153
154
```typescript { .api }
155
interface Module<S, R> {
156
namespaced?: boolean;
157
state?: S | (() => S);
158
getters?: GetterTree<S, R>;
159
actions?: ActionTree<S, R>;
160
mutations?: MutationTree<S>;
161
modules?: ModuleTree<R>;
162
}
163
164
interface ModuleOptions {
165
preserveState?: boolean;
166
}
167
```
168
169
[Module System](./module-system.md)
170
171
### Development Tools
172
173
Development and debugging features including logging plugin and DevTools integration.
174
175
```typescript { .api }
176
function createLogger<S>(options?: LoggerOption<S>): Plugin<S>;
177
178
interface LoggerOption<S> {
179
collapsed?: boolean;
180
filter?: <P extends Payload>(mutation: P, stateBefore: S, stateAfter: S) => boolean;
181
transformer?: (state: S) => any;
182
mutationTransformer?: <P extends Payload>(mutation: P) => any;
183
actionFilter?: <P extends Payload>(action: P, state: S) => boolean;
184
actionTransformer?: <P extends Payload>(action: P) => any;
185
logMutations?: boolean;
186
logActions?: boolean;
187
logger?: Logger;
188
}
189
```
190
191
[Development Tools](./development-tools.md)
192
193
## Core Types
194
195
```typescript { .api }
196
declare class Store<S> {
197
readonly state: S;
198
readonly getters: any;
199
200
install(app: App, injectKey?: InjectionKey<Store<any>> | string): void;
201
202
commit: Commit;
203
dispatch: Dispatch;
204
205
subscribe<P extends MutationPayload>(fn: (mutation: P, state: S) => any, options?: SubscribeOptions): () => void;
206
subscribeAction<P extends ActionPayload>(fn: SubscribeActionOptions<P, S>, options?: SubscribeOptions): () => void;
207
watch<T>(getter: (state: S, getters: any) => T, cb: (value: T, oldValue: T) => void, options?: WatchOptions): () => void;
208
209
registerModule<T>(path: string | string[], module: Module<T, S>, options?: ModuleOptions): void;
210
unregisterModule(path: string | string[]): void;
211
hasModule(path: string | string[]): boolean;
212
213
hotUpdate(options: {
214
actions?: ActionTree<S, S>;
215
mutations?: MutationTree<S>;
216
getters?: GetterTree<S, S>;
217
modules?: ModuleTree<S>;
218
}): void;
219
220
replaceState(state: S): void;
221
}
222
223
interface Dispatch {
224
(type: string, payload?: any, options?: DispatchOptions): Promise<any>;
225
<P extends Payload>(payloadWithType: P, options?: DispatchOptions): Promise<any>;
226
}
227
228
interface Commit {
229
(type: string, payload?: any, options?: CommitOptions): void;
230
<P extends Payload>(payloadWithType: P, options?: CommitOptions): void;
231
}
232
233
interface ActionContext<S, R> {
234
dispatch: Dispatch;
235
commit: Commit;
236
state: S;
237
getters: any;
238
rootState: R;
239
rootGetters: any;
240
}
241
242
interface Payload {
243
type: string;
244
}
245
246
interface MutationPayload extends Payload {
247
payload: any;
248
}
249
250
interface ActionPayload extends Payload {
251
payload: any;
252
}
253
254
type ActionHandler<S, R> = (this: Store<R>, injectee: ActionContext<S, R>, payload?: any) => any;
255
type Getter<S, R> = (state: S, getters: any, rootState: R, rootGetters: any) => any;
256
type Mutation<S> = (state: S, payload?: any) => any;
257
type Plugin<S> = (store: Store<S>) => any;
258
259
interface GetterTree<S, R> {
260
[key: string]: Getter<S, R>;
261
}
262
263
interface ActionTree<S, R> {
264
[key: string]: Action<S, R>;
265
}
266
267
type Action<S, R> = ActionHandler<S, R> | ActionObject<S, R>;
268
269
interface ActionObject<S, R> {
270
root?: boolean;
271
handler: ActionHandler<S, R>;
272
}
273
274
interface MutationTree<S> {
275
[key: string]: Mutation<S>;
276
}
277
278
interface ModuleTree<R> {
279
[key: string]: Module<any, R>;
280
}
281
282
interface DispatchOptions {
283
root?: boolean;
284
}
285
286
interface CommitOptions {
287
silent?: boolean;
288
root?: boolean;
289
}
290
291
interface SubscribeOptions {
292
prepend?: boolean;
293
}
294
295
type ActionSubscriber<P, S> = (action: P, state: S) => any;
296
type ActionErrorSubscriber<P, S> = (action: P, state: S, error: Error) => any;
297
298
interface ActionSubscribersObject<P, S> {
299
before?: ActionSubscriber<P, S>;
300
after?: ActionSubscriber<P, S>;
301
error?: ActionErrorSubscriber<P, S>;
302
}
303
304
type SubscribeActionOptions<P, S> = ActionSubscriber<P, S> | ActionSubscribersObject<P, S>;
305
```