0
# vuex-router-sync
1

2
vuex-router-sync provides seamless synchronization between Vue Router and Vuex store state, enabling developers to access current route information directly from the Vuex store. It creates an immutable route module in the store that automatically updates when navigation occurs, eliminating the need for manual route state management.
3

4
## Package Information
5

6
- **Package Name**: vuex-router-sync
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install vuex-router-sync`
10

11
## Core Imports
12

13
```javascript
14
import { sync } from 'vuex-router-sync';
15
```
16

17
For TypeScript:
18

19
```typescript
20
import { sync, type SyncOptions } from 'vuex-router-sync';
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { sync } = require('vuex-router-sync');
27
```
28

29
## Basic Usage
30

31
```javascript
32
import { sync } from 'vuex-router-sync';
33
import store from './vuex/store'; // vuex store instance
34
import router from './router';    // vue-router instance
35

36
// Sync router and store - returns unsync callback
37
const unsync = sync(store, router);
38

39
// Route information is now available in store
40
console.log(store.state.route.path);   // current path
41
console.log(store.state.route.params); // current params
42
console.log(store.state.route.query);  // current query
43

44
// Later, during app teardown
45
unsync(); // Clean up synchronization
46
```
47

48
## Architecture
49

50
vuex-router-sync works by:
51

52
1. **Module Registration**: Creates a `route` module in the Vuex store containing current route state
53
2. **Bidirectional Sync**: Watches for changes in both router navigation and store state
54
3. **Immutable State**: Route state is frozen and immutable, derived from the URL as the source of truth
55
4. **Cleanup Support**: Returns an unsync function for proper resource cleanup
56

57
The synchronized route state includes:
58
- `path` - Current route path
59
- `params` - Route parameters object
60
- `query` - Query parameters object  
61
- `fullPath` - Complete path including query and hash
62
- `hash` - URL hash
63
- `name` - Route name
64
- `meta` - Route metadata
65
- `from` - Previous route (during navigation)
66

67
## Capabilities
68

69
### Synchronization
70

71
Creates synchronization between Vue Router and Vuex store.
72

73
```javascript { .api }
74
/**
75
 * Synchronizes Vue Router and Vuex store state
76
 * @param {Object} store - Vuex store instance
77
 * @param {Object} router - Vue Router instance
78
 * @param {SyncOptions} [options] - Configuration options
79
 * @returns {() => void} Unsync callback function for cleanup
80
 */
81
function sync(store, router, options);
82
```
83

84
```typescript { .api }
85
/**
86
 * TypeScript declaration for sync function
87
 */
88
function sync(
89
  store: Store<any>,
90
  router: VueRouter,
91
  options?: SyncOptions
92
): () => void;
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
import { sync } from 'vuex-router-sync';
99

100
// Basic synchronization with default module name 'route'
101
const unsync = sync(store, router);
102

103
// Custom module name
104
const unsync = sync(store, router, { moduleName: 'router' });
105

106
// Access route data from store
107
store.state.route.path;      // "/users/123"
108
store.state.route.params;    // { id: "123" }
109
store.state.route.query;     // { tab: "profile" }
110
store.state.route.fullPath;  // "/users/123?tab=profile#settings"
111
```
112

113
## Types
114

115
```typescript { .api }
116
import { Store } from 'vuex';
117
import VueRouter from 'vue-router';
118

119
interface SyncOptions {
120
  /** Name of the module to register in Vuex store (defaults to 'route') */
121
  moduleName?: string;
122
}
123

124
interface RouteState {
125
  /** Current route name */
126
  name: string | null;
127
  /** Current route path */
128
  path: string;
129
  /** URL hash */
130
  hash: string;
131
  /** Query parameters object */
132
  query: Record<string, string | (string | null)[]>;
133
  /** Route parameters object */
134
  params: Record<string, string>;
135
  /** Full path including query and hash */
136
  fullPath: string;
137
  /** Route metadata */
138
  meta: any;
139
  /** Previous route (when navigating) */
140
  from?: RouteState;
141
}
142
```
143

144
## Error Handling
145

146
The sync function assumes valid Vuex store and Vue Router instances. No specific errors are thrown, but improper usage may lead to:
147

148
- Store module registration failures if the store is not properly initialized
149
- Router hook registration failures if the router is not properly initialized
150
- Memory leaks if the returned unsync function is not called during cleanup
151

152
## Peer Dependencies
153

154
- `vue-router` ^3.0.0
155
- `vuex` ^3.0.0