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
```