@real-router/browser-plugin 0.10.1 → 0.10.3
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 +59 -109
- package/dist/cjs/index.d.ts +3 -3
- package/dist/cjs/metafile-cjs.json +1 -1
- 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,117 @@ 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
36
|
router.usePlugin(
|
|
51
37
|
browserPluginFactory({
|
|
52
|
-
base: "/app",
|
|
53
|
-
forceDeactivate: true,
|
|
38
|
+
base: "/app", // Base path prefix for all routes
|
|
39
|
+
forceDeactivate: true, // Bypass canDeactivate guards on back/forward
|
|
54
40
|
}),
|
|
55
41
|
);
|
|
56
|
-
|
|
57
|
-
router.navigate("products", { id: "123" });
|
|
58
|
-
// URL: http://example.com/app/products/123
|
|
59
42
|
```
|
|
60
43
|
|
|
61
|
-
| Option | Type | Default | Description
|
|
62
|
-
| ----------------- | --------- | ------- |
|
|
63
|
-
| `base` | `string` | `""` | Base path for all routes (e.g., `"/app"`)
|
|
64
|
-
| `forceDeactivate` | `boolean` | `true` | Bypass `canDeactivate` guards on browser back/forward
|
|
65
|
-
|
|
66
|
-
> **Looking for hash routing?** Use [`@real-router/hash-plugin`](https://www.npmjs.com/package/@real-router/hash-plugin) instead.
|
|
44
|
+
| Option | Type | Default | Description |
|
|
45
|
+
| ----------------- | --------- | ------- | ---------------------------------------------------------------------- |
|
|
46
|
+
| `base` | `string` | `""` | Base path for all routes (e.g., `"/app"` → URLs start with `/app/...`) |
|
|
47
|
+
| `forceDeactivate` | `boolean` | `true` | Bypass `canDeactivate` guards on browser back/forward |
|
|
67
48
|
|
|
68
|
-
|
|
49
|
+
> **Hash routing?** Use [`@real-router/hash-plugin`](https://www.npmjs.com/package/@real-router/hash-plugin) instead.
|
|
69
50
|
|
|
70
|
-
|
|
51
|
+
## Router Extensions
|
|
71
52
|
|
|
72
|
-
|
|
53
|
+
The plugin extends the router instance with three methods via [`extendRouter()`](https://github.com/greydragon888/real-router/wiki/plugin-architecture):
|
|
73
54
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
`name: string` — route name\
|
|
80
|
-
`params?: Params` — route parameters\
|
|
81
|
-
Returns: `string` — full URL\
|
|
82
|
-
[Wiki](https://github.com/greydragon888/real-router/wiki/browser-plugin#5-router-interaction)
|
|
55
|
+
| Method | Returns | Description |
|
|
56
|
+
| -------------------------------------------- | -------------------- | ------------------------------------------------ |
|
|
57
|
+
| `buildUrl(name, params?)` | `string` | Build full URL with base path |
|
|
58
|
+
| `matchUrl(url)` | `State \| undefined` | Parse URL to router state |
|
|
59
|
+
| `replaceHistoryState(name, params?, title?)` | `void` | Update browser URL without triggering navigation |
|
|
83
60
|
|
|
84
61
|
```typescript
|
|
85
62
|
router.buildUrl("users", { id: "123" });
|
|
86
63
|
// => "/app/users/123" (with base "/app")
|
|
87
|
-
```
|
|
88
64
|
|
|
89
|
-
|
|
65
|
+
router.matchUrl("/app/users/123");
|
|
66
|
+
// => { name: "users", params: { id: "123" }, path: "/users/123" }
|
|
90
67
|
|
|
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");
|
|
100
|
-
|
|
101
|
-
// User clicks back twice rapidly
|
|
102
|
-
// Plugin ensures router ends at page1
|
|
103
|
-
// URL and router state remain synchronized
|
|
68
|
+
// Update URL silently (no transition, no guards)
|
|
69
|
+
router.replaceHistoryState("users", { id: "456" });
|
|
104
70
|
```
|
|
105
71
|
|
|
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)
|
|
72
|
+
### `buildUrl` vs `buildPath`
|
|
114
73
|
|
|
115
74
|
```typescript
|
|
116
|
-
router.
|
|
75
|
+
router.buildPath("users", { id: 1 }); // "/users/1" — core, no base
|
|
76
|
+
router.buildUrl("users", { id: 1 }); // "/app/users/1" — plugin, with base
|
|
117
77
|
```
|
|
118
78
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
## Usage Examples
|
|
122
|
-
|
|
123
|
-
### With Base Path
|
|
79
|
+
### `replaceHistoryState` vs `navigate({ replace: true })`
|
|
124
80
|
|
|
125
81
|
```typescript
|
|
126
|
-
router.
|
|
127
|
-
|
|
128
|
-
base: "/app",
|
|
129
|
-
}),
|
|
130
|
-
);
|
|
131
|
-
|
|
132
|
-
router.navigate("users", { id: "123" });
|
|
133
|
-
// URL: /app/users/123
|
|
82
|
+
router.replaceHistoryState(name, params); // URL only, no transition
|
|
83
|
+
router.navigate(name, params, { replace: true }); // Full transition + URL update
|
|
134
84
|
```
|
|
135
85
|
|
|
136
|
-
|
|
86
|
+
## Form Protection
|
|
87
|
+
|
|
88
|
+
Set `forceDeactivate: false` to respect `canDeactivate` guards on back/forward:
|
|
137
89
|
|
|
138
90
|
```typescript
|
|
139
|
-
router.usePlugin(
|
|
140
|
-
browserPluginFactory({
|
|
141
|
-
forceDeactivate: false,
|
|
142
|
-
}),
|
|
143
|
-
);
|
|
91
|
+
router.usePlugin(browserPluginFactory({ forceDeactivate: false }));
|
|
144
92
|
|
|
145
93
|
import { getLifecycleApi } from "@real-router/core/api";
|
|
146
94
|
|
|
147
95
|
const lifecycle = getLifecycleApi(router);
|
|
148
|
-
lifecycle.addDeactivateGuard(
|
|
149
|
-
|
|
150
|
-
|
|
96
|
+
lifecycle.addDeactivateGuard(
|
|
97
|
+
"checkout",
|
|
98
|
+
(router, getDep) => (toState, fromState) => {
|
|
99
|
+
return !hasUnsavedChanges(); // false blocks back/forward
|
|
100
|
+
},
|
|
101
|
+
);
|
|
151
102
|
```
|
|
152
103
|
|
|
153
|
-
---
|
|
154
|
-
|
|
155
104
|
## SSR Support
|
|
156
105
|
|
|
157
|
-
The plugin is SSR-safe
|
|
106
|
+
The plugin is SSR-safe — automatically detects the environment and falls back to no-ops:
|
|
158
107
|
|
|
159
108
|
```typescript
|
|
160
109
|
// Server-side — no errors, methods return safe defaults
|
|
161
110
|
router.usePlugin(browserPluginFactory());
|
|
162
|
-
router.buildUrl("home"); //
|
|
163
|
-
router.matchUrl("/path"); //
|
|
111
|
+
router.buildUrl("home"); // returns path without base
|
|
112
|
+
router.matchUrl("/path"); // returns undefined
|
|
164
113
|
```
|
|
165
114
|
|
|
166
|
-
---
|
|
167
|
-
|
|
168
115
|
## Documentation
|
|
169
116
|
|
|
170
|
-
Full documentation
|
|
117
|
+
Full documentation: [Wiki — browser-plugin](https://github.com/greydragon888/real-router/wiki/browser-plugin)
|
|
171
118
|
|
|
172
119
|
- [Configuration Options](https://github.com/greydragon888/real-router/wiki/browser-plugin#3-configuration-options)
|
|
173
120
|
- [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
121
|
- [Behavior & Edge Cases](https://github.com/greydragon888/real-router/wiki/browser-plugin#8-behavior)
|
|
176
122
|
- [Migration from router5](https://github.com/greydragon888/real-router/wiki/browser-plugin#11-migration-from-router5)
|
|
177
123
|
|
|
178
|
-
---
|
|
179
|
-
|
|
180
124
|
## Related Packages
|
|
181
125
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
126
|
+
| Package | Description |
|
|
127
|
+
| -------------------------------------------------------------------------------------- | -------------------------------------- |
|
|
128
|
+
| [@real-router/core](https://www.npmjs.com/package/@real-router/core) | Core router (required peer dependency) |
|
|
129
|
+
| [@real-router/hash-plugin](https://www.npmjs.com/package/@real-router/hash-plugin) | Hash-based routing (`#/path`) |
|
|
130
|
+
| [@real-router/react](https://www.npmjs.com/package/@real-router/react) | React integration |
|
|
131
|
+
| [@real-router/logger-plugin](https://www.npmjs.com/package/@real-router/logger-plugin) | Development logging |
|
|
132
|
+
|
|
133
|
+
## Contributing
|
|
134
|
+
|
|
135
|
+
See [contributing guidelines](../../CONTRIBUTING.md) for development setup and PR process.
|
|
186
136
|
|
|
187
137
|
## License
|
|
188
138
|
|
|
189
|
-
MIT © [Oleg Ivanov](https://github.com/greydragon888)
|
|
139
|
+
[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[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.
|
|
1
|
+
{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"../type-guards/dist/esm/index.mjs":{"bytes":3451,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"../browser-env/dist/esm/index.mjs":{"bytes":4153,"imports":[{"path":"../type-guards/dist/esm/index.mjs","kind":"import-statement","original":"type-guards"},{"path":"@real-router/core","kind":"import-statement","external":true},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/constants.ts":{"bytes":493,"imports":[{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/url-utils.ts":{"bytes":703,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/plugin.ts":{"bytes":2944,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/url-utils.ts","kind":"import-statement","original":"./url-utils"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/validation.ts":{"bytes":288,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/factory.ts":{"bytes":1517,"imports":[{"path":"@real-router/core/api","kind":"import-statement","external":true},{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"src/plugin.ts","kind":"import-statement","original":"./plugin"},{"path":"src/url-utils.ts","kind":"import-statement","original":"./url-utils"},{"path":"src/validation.ts","kind":"import-statement","original":"./validation"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/index.ts":{"bytes":1311,"imports":[{"path":"src/factory.ts","kind":"import-statement","original":"./factory"},{"path":"../type-guards/dist/esm/index.mjs","kind":"import-statement","original":"type-guards"},{"path":"/home/runner/work/real-router/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.19.4_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js.map":{"imports":[],"exports":[],"inputs":{},"bytes":8921},"dist/cjs/index.js":{"imports":[{"path":"@real-router/core/api","kind":"import-statement","external":true},{"path":"@real-router/core","kind":"import-statement","external":true}],"exports":["browserPluginFactory","isState"],"entryPoint":"src/index.ts","inputs":{"src/factory.ts":{"bytesInOutput":831},"../type-guards/dist/esm/index.mjs":{"bytesInOutput":2337},"../browser-env/dist/esm/index.mjs":{"bytesInOutput":4761},"src/constants.ts":{"bytesInOutput":126},"src/url-utils.ts":{"bytesInOutput":442},"src/plugin.ts":{"bytesInOutput":1790},"src/validation.ts":{"bytesInOutput":63},"src/index.ts":{"bytesInOutput":0}},"bytes":10596}}}
|
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.3",
|
|
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.38.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.5",
|
|
54
|
+
"type-guards": "^0.3.7"
|
|
55
55
|
},
|
|
56
56
|
"scripts": {
|
|
57
57
|
"test": "vitest",
|