0
# Router Creation
1

2
Core router creation functions for SPA and MPA applications with comprehensive page lifecycle management, universal routing, and page stack management.
3

4
## Capabilities
5

6
### createRouter
7

8
Creates a single-page application (SPA) router with universal routing support, page stack management, and full lifecycle integration.
9

10
```typescript { .api }
11
/**
12
 * Creates a single-page application (SPA) router
13
 * @param history - Browser/hash history instance for navigation
14
 * @param app - Application component instance with lifecycle methods
15
 * @param config - Router configuration for SPA mode
16
 * @param framework - Framework type ('react', 'vue', 'solid', 'preact')
17
 * @returns Function to unsubscribe from history listener
18
 */
19
function createRouter(
20
  history: History,
21
  app: AppInstance,
22
  config: SpaRouterConfig,
23
  framework?: string
24
): () => void;
25
```
26

27
**Usage Example:**
28

29
```typescript
30
import { createRouter, createHashHistory } from "@tarojs/router";
31

32
const history = createHashHistory();
33
const app = {
34
  onLaunch: (options) => console.log("App launched", options),
35
  onShow: (options) => console.log("App shown", options),
36
  onHide: () => console.log("App hidden"),
37
  onError: (error) => console.error("App error", error)
38
};
39

40
const config = {
41
  routes: [
42
    { 
43
      path: "/home", 
44
      load: () => import("./pages/home"),
45
      navigationBarTitleText: "Home" 
46
    },
47
    { 
48
      path: "/profile", 
49
      load: () => import("./pages/profile"),
50
      navigationBarTitleText: "Profile" 
51
    }
52
  ],
53
  router: {
54
    mode: "hash",
55
    basename: "/",
56
    pathname: "/home"
57
  },
58
  pages: ["/home", "/profile"],
59
  window: {
60
    navigationBarBackgroundColor: "#000000",
61
    navigationBarTextStyle: "white"
62
  }
63
};
64

65
const unsubscribe = createRouter(history, app, config, "react");
66

67
// Clean up when needed
68
// unsubscribe();
69
```
70

71
### createMultiRouter
72

73
Creates a multi-page application (MPA) router for applications that use traditional page navigation patterns.
74

75
```typescript { .api }
76
/**
77
 * Creates a multi-page application (MPA) router
78
 * @param history - Browser/hash history instance (custom MPA implementation)
79
 * @param app - Application component instance with lifecycle methods
80
 * @param config - Router configuration for MPA mode
81
 * @param framework - Framework type ('react', 'vue', 'solid', 'preact')
82
 * @returns Promise that resolves when router is initialized
83
 */
84
function createMultiRouter(
85
  history: History,
86
  app: AppInstance,
87
  config: MpaRouterConfig,
88
  framework?: string
89
): Promise<void>;
90
```
91

92
**Usage Example:**
93

94
```typescript
95
import { createMultiRouter, createMpaHistory } from "@tarojs/router";
96

97
const history = createMpaHistory();
98
const app = {
99
  onLaunch: (options) => console.log("App launched", options),
100
  onShow: (options) => console.log("App shown", options),
101
  onHide: () => console.log("App hidden")
102
};
103

104
const config = {
105
  route: {
106
    path: "/current-page",
107
    load: () => import("./pages/current"),
108
    navigationBarTitleText: "Current Page"
109
  },
110
  pageName: "/current-page",
111
  router: {
112
    mode: "multi",
113
    basename: "/",
114
    pathname: "/current-page"
115
  },
116
  window: {
117
    navigationBarBackgroundColor: "#ffffff",
118
    navigationBarTextStyle: "black"
119
  }
120
};
121

122
await createMultiRouter(history, app, config, "react");
123
```
124

125
### App Mount Functions
126

127
Functions to mount the application with or without tabbar support.
128

129
```typescript { .api }
130
/**
131
 * Mounts the application without tabbar support
132
 * @param config - Router configuration
133
 * @param history - History instance (unused parameter)
134
 * @param appId - App element ID, defaults to 'app'
135
 */
136
function handleAppMount(
137
  config: SpaRouterConfig | MpaRouterConfig,
138
  history: History,
139
  appId?: string
140
): void;
141

142
/**
143
 * Mounts the application with tabbar container support
144
 * @param config - Router configuration
145
 * @param history - History instance for tabbar navigation
146
 * @param appId - App element ID, defaults to 'app'
147
 */
148
function handleAppMountWithTabbar(
149
  config: SpaRouterConfig | MpaRouterConfig,
150
  history: History,
151
  appId?: string
152
): void;
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import { handleAppMount, handleAppMountWithTabbar } from "@tarojs/router";
159

160
// Mount without tabbar
161
handleAppMount(config, history, "my-app");
162

163
// Mount with tabbar (for apps with bottom navigation)
164
handleAppMountWithTabbar(config, history, "my-app");
165
```
166

167
## Configuration Types
168

169
```typescript { .api }
170
interface SpaRouterConfig extends AppConfig {
171
  /** Array of route configurations for SPA routing */
172
  routes: Route[];
173
  /** Router configuration object */
174
  router: Router;
175
  /** Optional pull-down refresh component */
176
  PullDownRefresh?: any;
177
}
178

179
interface MpaRouterConfig extends AppConfig {
180
  /** Single route configuration for current page */
181
  route: Route;
182
  /** Current page name/path */
183
  pageName: string;
184
  /** Router configuration object */
185
  router: Router;
186
  /** Optional pull-down refresh component */
187
  PullDownRefresh?: any;
188
}
189

190
interface Route extends PageConfig {
191
  /** Route path pattern */
192
  path?: string;
193
  /** Async function to load page component */
194
  load?: () => Promise<any>;
195
}
196

197
interface Router {
198
  /** Router mode: 'hash', 'browser', or 'multi' */
199
  mode: IH5RouterConfig['mode'];
200
  /** Base path for all routes */
201
  basename: string;
202
  /** Custom route aliases mapping */
203
  customRoutes?: Record<string, string | string[]>;
204
  /** Current pathname */
205
  pathname: string;
206
  /** Force a specific path (overrides current pathname) */
207
  forcePath?: string;
208
  /** Enable enhanced animation support (requires :has() selector support) */
209
  enhanceAnimation?: boolean;
210
}
211
```