@real-router/browser-plugin 0.10.1 → 0.10.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +56 -111
- package/dist/cjs/index.d.ts +3 -3
- package/dist/esm/index.d.mts +3 -3
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,22 +1,20 @@
|
|
|
1
1
|
# @real-router/browser-plugin
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@real-router/browser-plugin)
|
|
4
|
+
[](https://www.npmjs.com/package/@real-router/browser-plugin)
|
|
5
|
+
[](https://bundlejs.com/?q=@real-router/browser-plugin&treeshake=[*])
|
|
6
|
+
[](../../LICENSE)
|
|
5
7
|
|
|
6
|
-
Browser History API integration for Real-Router. Synchronizes router state with browser URL and handles back/forward navigation.
|
|
8
|
+
> Browser History API integration for [Real-Router](https://github.com/greydragon888/real-router). Synchronizes router state with browser URL and handles back/forward navigation.
|
|
7
9
|
|
|
8
10
|
## Installation
|
|
9
11
|
|
|
10
12
|
```bash
|
|
11
13
|
npm install @real-router/browser-plugin
|
|
12
|
-
# or
|
|
13
|
-
pnpm add @real-router/browser-plugin
|
|
14
|
-
# or
|
|
15
|
-
yarn add @real-router/browser-plugin
|
|
16
|
-
# or
|
|
17
|
-
bun add @real-router/browser-plugin
|
|
18
14
|
```
|
|
19
15
|
|
|
16
|
+
**Peer dependency:** `@real-router/core`
|
|
17
|
+
|
|
20
18
|
## Quick Start
|
|
21
19
|
|
|
22
20
|
```typescript
|
|
@@ -25,165 +23,112 @@ import { browserPluginFactory } from "@real-router/browser-plugin";
|
|
|
25
23
|
|
|
26
24
|
const router = createRouter([
|
|
27
25
|
{ name: "home", path: "/" },
|
|
28
|
-
{ name: "
|
|
29
|
-
{ name: "cart", path: "/cart" },
|
|
26
|
+
{ name: "users", path: "/users/:id" },
|
|
30
27
|
]);
|
|
31
28
|
|
|
32
|
-
// Basic usage
|
|
33
29
|
router.usePlugin(browserPluginFactory());
|
|
34
|
-
|
|
35
|
-
// With options
|
|
36
|
-
router.usePlugin(
|
|
37
|
-
browserPluginFactory({
|
|
38
|
-
base: "/app",
|
|
39
|
-
}),
|
|
40
|
-
);
|
|
41
|
-
|
|
42
|
-
await router.start();
|
|
30
|
+
await router.start(); // path inferred from browser location
|
|
43
31
|
```
|
|
44
32
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
## Configuration
|
|
33
|
+
## Options
|
|
48
34
|
|
|
49
35
|
```typescript
|
|
50
|
-
router.usePlugin(
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
}),
|
|
55
|
-
);
|
|
56
|
-
|
|
57
|
-
router.navigate("products", { id: "123" });
|
|
58
|
-
// URL: http://example.com/app/products/123
|
|
36
|
+
router.usePlugin(browserPluginFactory({
|
|
37
|
+
base: "/app", // Base path prefix for all routes
|
|
38
|
+
forceDeactivate: true, // Bypass canDeactivate guards on back/forward
|
|
39
|
+
}));
|
|
59
40
|
```
|
|
60
41
|
|
|
61
|
-
| Option
|
|
62
|
-
|
|
63
|
-
| `base`
|
|
64
|
-
| `forceDeactivate` | `boolean` | `true`
|
|
65
|
-
|
|
66
|
-
> **Looking for hash routing?** Use [`@real-router/hash-plugin`](https://www.npmjs.com/package/@real-router/hash-plugin) instead.
|
|
67
|
-
|
|
68
|
-
See [Wiki](https://github.com/greydragon888/real-router/wiki/browser-plugin#3-configuration-options) for detailed option descriptions and examples.
|
|
42
|
+
| Option | Type | Default | Description |
|
|
43
|
+
|--------|------|---------|-------------|
|
|
44
|
+
| `base` | `string` | `""` | Base path for all routes (e.g., `"/app"` → URLs start with `/app/...`) |
|
|
45
|
+
| `forceDeactivate` | `boolean` | `true` | Bypass `canDeactivate` guards on browser back/forward |
|
|
69
46
|
|
|
70
|
-
|
|
47
|
+
> **Hash routing?** Use [`@real-router/hash-plugin`](https://www.npmjs.com/package/@real-router/hash-plugin) instead.
|
|
71
48
|
|
|
72
|
-
##
|
|
49
|
+
## Router Extensions
|
|
73
50
|
|
|
74
|
-
The plugin extends the router instance with
|
|
51
|
+
The plugin extends the router instance with three methods via [`extendRouter()`](https://github.com/greydragon888/real-router/wiki/plugin-architecture):
|
|
75
52
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
Build full URL with base path
|
|
79
|
-
`
|
|
80
|
-
`params
|
|
81
|
-
Returns: `string` — full URL\
|
|
82
|
-
[Wiki](https://github.com/greydragon888/real-router/wiki/browser-plugin#5-router-interaction)
|
|
53
|
+
| Method | Returns | Description |
|
|
54
|
+
|--------|---------|-------------|
|
|
55
|
+
| `buildUrl(name, params?)` | `string` | Build full URL with base path |
|
|
56
|
+
| `matchUrl(url)` | `State \| undefined` | Parse URL to router state |
|
|
57
|
+
| `replaceHistoryState(name, params?, title?)` | `void` | Update browser URL without triggering navigation |
|
|
83
58
|
|
|
84
59
|
```typescript
|
|
85
60
|
router.buildUrl("users", { id: "123" });
|
|
86
61
|
// => "/app/users/123" (with base "/app")
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
#### `router.matchUrl(url: string): State | undefined`
|
|
90
62
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
Returns: `State | undefined`\
|
|
94
|
-
[Wiki](https://github.com/greydragon888/real-router/wiki/browser-plugin#5-router-interaction)
|
|
95
|
-
|
|
96
|
-
```typescript
|
|
97
|
-
router.navigate("page1");
|
|
98
|
-
router.navigate("page2");
|
|
99
|
-
router.navigate("page3");
|
|
63
|
+
router.matchUrl("/app/users/123");
|
|
64
|
+
// => { name: "users", params: { id: "123" }, path: "/users/123" }
|
|
100
65
|
|
|
101
|
-
//
|
|
102
|
-
|
|
103
|
-
// URL and router state remain synchronized
|
|
66
|
+
// Update URL silently (no transition, no guards)
|
|
67
|
+
router.replaceHistoryState("users", { id: "456" });
|
|
104
68
|
```
|
|
105
69
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
Update browser URL without triggering navigation.\
|
|
109
|
-
`name: string` — route name\
|
|
110
|
-
`params?: Params` — route parameters\
|
|
111
|
-
`title?: string` — page title\
|
|
112
|
-
Returns: `void`\
|
|
113
|
-
[Wiki](https://github.com/greydragon888/real-router/wiki/browser-plugin#5-router-interaction)
|
|
70
|
+
### `buildUrl` vs `buildPath`
|
|
114
71
|
|
|
115
72
|
```typescript
|
|
116
|
-
router.
|
|
73
|
+
router.buildPath("users", { id: 1 }); // "/users/1" — core, no base
|
|
74
|
+
router.buildUrl("users", { id: 1 }); // "/app/users/1" — plugin, with base
|
|
117
75
|
```
|
|
118
76
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
## Usage Examples
|
|
122
|
-
|
|
123
|
-
### With Base Path
|
|
77
|
+
### `replaceHistoryState` vs `navigate({ replace: true })`
|
|
124
78
|
|
|
125
79
|
```typescript
|
|
126
|
-
router.
|
|
127
|
-
|
|
128
|
-
base: "/app",
|
|
129
|
-
}),
|
|
130
|
-
);
|
|
131
|
-
|
|
132
|
-
router.navigate("users", { id: "123" });
|
|
133
|
-
// URL: /app/users/123
|
|
80
|
+
router.replaceHistoryState(name, params); // URL only, no transition
|
|
81
|
+
router.navigate(name, params, { replace: true }); // Full transition + URL update
|
|
134
82
|
```
|
|
135
83
|
|
|
136
|
-
|
|
84
|
+
## Form Protection
|
|
85
|
+
|
|
86
|
+
Set `forceDeactivate: false` to respect `canDeactivate` guards on back/forward:
|
|
137
87
|
|
|
138
88
|
```typescript
|
|
139
|
-
router.usePlugin(
|
|
140
|
-
browserPluginFactory({
|
|
141
|
-
forceDeactivate: false,
|
|
142
|
-
}),
|
|
143
|
-
);
|
|
89
|
+
router.usePlugin(browserPluginFactory({ forceDeactivate: false }));
|
|
144
90
|
|
|
145
91
|
import { getLifecycleApi } from "@real-router/core/api";
|
|
146
92
|
|
|
147
93
|
const lifecycle = getLifecycleApi(router);
|
|
148
94
|
lifecycle.addDeactivateGuard("checkout", () => (toState, fromState) => {
|
|
149
|
-
return !hasUnsavedChanges(); // false blocks
|
|
95
|
+
return !hasUnsavedChanges(); // false blocks back/forward
|
|
150
96
|
});
|
|
151
97
|
```
|
|
152
98
|
|
|
153
|
-
---
|
|
154
|
-
|
|
155
99
|
## SSR Support
|
|
156
100
|
|
|
157
|
-
The plugin is SSR-safe
|
|
101
|
+
The plugin is SSR-safe — automatically detects the environment and falls back to no-ops:
|
|
158
102
|
|
|
159
103
|
```typescript
|
|
160
104
|
// Server-side — no errors, methods return safe defaults
|
|
161
105
|
router.usePlugin(browserPluginFactory());
|
|
162
|
-
router.buildUrl("home");
|
|
163
|
-
router.matchUrl("/path");
|
|
106
|
+
router.buildUrl("home"); // returns path without base
|
|
107
|
+
router.matchUrl("/path"); // returns undefined
|
|
164
108
|
```
|
|
165
109
|
|
|
166
|
-
---
|
|
167
|
-
|
|
168
110
|
## Documentation
|
|
169
111
|
|
|
170
|
-
Full documentation
|
|
112
|
+
Full documentation: [Wiki — browser-plugin](https://github.com/greydragon888/real-router/wiki/browser-plugin)
|
|
171
113
|
|
|
172
114
|
- [Configuration Options](https://github.com/greydragon888/real-router/wiki/browser-plugin#3-configuration-options)
|
|
173
115
|
- [Lifecycle Hooks](https://github.com/greydragon888/real-router/wiki/browser-plugin#4-lifecycle-hooks)
|
|
174
|
-
- [Router Methods](https://github.com/greydragon888/real-router/wiki/browser-plugin#5-router-interaction)
|
|
175
116
|
- [Behavior & Edge Cases](https://github.com/greydragon888/real-router/wiki/browser-plugin#8-behavior)
|
|
176
117
|
- [Migration from router5](https://github.com/greydragon888/real-router/wiki/browser-plugin#11-migration-from-router5)
|
|
177
118
|
|
|
178
|
-
---
|
|
179
|
-
|
|
180
119
|
## Related Packages
|
|
181
120
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
121
|
+
| Package | Description |
|
|
122
|
+
|---------|-------------|
|
|
123
|
+
| [@real-router/core](https://www.npmjs.com/package/@real-router/core) | Core router (required peer dependency) |
|
|
124
|
+
| [@real-router/hash-plugin](https://www.npmjs.com/package/@real-router/hash-plugin) | Hash-based routing (`#/path`) |
|
|
125
|
+
| [@real-router/react](https://www.npmjs.com/package/@real-router/react) | React integration |
|
|
126
|
+
| [@real-router/logger-plugin](https://www.npmjs.com/package/@real-router/logger-plugin) | Development logging |
|
|
127
|
+
|
|
128
|
+
## Contributing
|
|
129
|
+
|
|
130
|
+
See [contributing guidelines](../../CONTRIBUTING.md) for development setup and PR process.
|
|
186
131
|
|
|
187
132
|
## License
|
|
188
133
|
|
|
189
|
-
MIT © [Oleg Ivanov](https://github.com/greydragon888)
|
|
134
|
+
[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -33,11 +33,11 @@ declare function browserPluginFactory(opts?: Partial<BrowserPluginOptions>, brow
|
|
|
33
33
|
type TransitionPhase = "deactivating" | "activating";
|
|
34
34
|
type TransitionReason = "success" | "blocked" | "cancelled" | "error";
|
|
35
35
|
interface TransitionMeta {
|
|
36
|
-
readonly reload?: boolean;
|
|
37
|
-
readonly redirected?: boolean;
|
|
38
36
|
phase: TransitionPhase;
|
|
39
|
-
from?: string;
|
|
40
37
|
reason: TransitionReason;
|
|
38
|
+
reload?: boolean;
|
|
39
|
+
redirected?: boolean;
|
|
40
|
+
from?: string;
|
|
41
41
|
blocker?: string;
|
|
42
42
|
segments: {
|
|
43
43
|
deactivated: string[];
|
package/dist/esm/index.d.mts
CHANGED
|
@@ -33,11 +33,11 @@ declare function browserPluginFactory(opts?: Partial<BrowserPluginOptions>, brow
|
|
|
33
33
|
type TransitionPhase = "deactivating" | "activating";
|
|
34
34
|
type TransitionReason = "success" | "blocked" | "cancelled" | "error";
|
|
35
35
|
interface TransitionMeta {
|
|
36
|
-
readonly reload?: boolean;
|
|
37
|
-
readonly redirected?: boolean;
|
|
38
36
|
phase: TransitionPhase;
|
|
39
|
-
from?: string;
|
|
40
37
|
reason: TransitionReason;
|
|
38
|
+
reload?: boolean;
|
|
39
|
+
redirected?: boolean;
|
|
40
|
+
from?: string;
|
|
41
41
|
blocker?: string;
|
|
42
42
|
segments: {
|
|
43
43
|
deactivated: string[];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@real-router/browser-plugin",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.2",
|
|
4
4
|
"type": "commonjs",
|
|
5
5
|
"description": "Browser integration plugin with History API, hash routing, and popstate support",
|
|
6
6
|
"main": "./dist/cjs/index.js",
|
|
@@ -45,13 +45,13 @@
|
|
|
45
45
|
},
|
|
46
46
|
"sideEffects": false,
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@real-router/core": "^0.
|
|
48
|
+
"@real-router/core": "^0.37.0"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
51
|
"@testing-library/jest-dom": "6.9.1",
|
|
52
52
|
"jsdom": "28.1.0",
|
|
53
|
-
"browser-env": "^0.1.
|
|
54
|
-
"type-guards": "^0.3.
|
|
53
|
+
"browser-env": "^0.1.4",
|
|
54
|
+
"type-guards": "^0.3.7"
|
|
55
55
|
},
|
|
56
56
|
"scripts": {
|
|
57
57
|
"test": "vitest",
|