@next-box/link-extra 0.1.0 → 0.1.1
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 +136 -2
- package/dist/production.analysis.txt +15 -15
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,142 @@
|
|
|
1
1
|
# @next-box/link-extra
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A configurable link component for React applications, primarily designed for Next.js.
|
|
4
4
|
|
|
5
5
|
[](https://badge.fury.io/js/%40next-box%2Flink-extra)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Next.js is a powerful framework for building modern React applications, particularly with its support for React Server Components and server-side rendering. However, these features can introduce some differences in navigation behaviour compared with traditional client-side applications.
|
|
9
|
+
|
|
10
|
+
Client-side navigation can sometimes feel unresponsive when the destination requires server-side work, with the browser waiting for the new route to begin rendering before the UI changes. This has been discussed in the Next.js community, including [Slow route navigation](https://github.com/vercel/next.js/discussions/65150) and [How to indicate loading during pagination](https://github.com/vercel/next.js/discussions/55481).
|
|
11
|
+
|
|
12
|
+
Next.js also maintains a client-side Router Cache to improve navigation performance. While this is useful for many applications, there are cases where an application needs to ensure that navigation retrieves the latest version of a route. The ability to opt out of this client-side caching has been discussed in [Opt-out of client cache](https://github.com/vercel/next.js/discussions/54162), and the distinction between the Router Cache and server-side caching is discussed in [Deep Dive: Caching and Revalidating](https://github.com/vercel/next.js/discussions/54075).
|
|
13
|
+
|
|
14
|
+
Finally, applications often have their own link components and design systems. Integrating these with Next.js `Link` can be awkward, particularly when an application needs the `href` applied to its own anchor element rather than having Next.js render the anchor itself. This has been discussed in the Next.js community, including [Add back `passHref` to the new next/link component](https://github.com/vercel/next.js/discussions/49508) and [Remove `legacyBehavior` from Link component on Next.js 15](https://github.com/vercel/next.js/discussions/67987).
|
|
15
|
+
|
|
16
|
+
`@next-box/link-extra` provides a wrapper around the Next.js `Link` component that addresses these concerns while retaining Next.js client-side navigation.
|
|
17
|
+
|
|
18
|
+
## What it provides
|
|
19
|
+
|
|
20
|
+
### Loading feedback
|
|
21
|
+
|
|
22
|
+
A navigation can take some time to begin rendering, particularly when the destination requires server-side work. `@next-box/link-extra` can display a custom loading component if navigation has not completed within a configurable timeout.
|
|
23
|
+
|
|
24
|
+
If the route transition completes before the timeout, no loading indicator is displayed. If it takes longer, the loading component is rendered automatically.
|
|
25
|
+
|
|
26
|
+
### Router cache control
|
|
27
|
+
|
|
28
|
+
`@next-box/link-extra` provides the `disableRouterCache` prop for cases where an application needs to bypass the Next.js client-side Router Cache.
|
|
29
|
+
|
|
30
|
+
When enabled, the link adds a cache-busting query parameter to the destination URL. This is enabled by default.
|
|
31
|
+
|
|
32
|
+
### Custom link components
|
|
33
|
+
|
|
34
|
+
The library separates the Next.js navigation link from the component used to render the actual link.
|
|
35
|
+
|
|
36
|
+
This allows applications to provide their own link component for styling and design-system requirements while retaining Next.js navigation behaviour.
|
|
37
|
+
|
|
38
|
+
## Installation
|
|
39
|
+
|
|
40
|
+
```shell
|
|
41
|
+
npm add @next-box/link-extra
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Usage
|
|
45
|
+
|
|
46
|
+
### Create a link provider
|
|
47
|
+
|
|
48
|
+
`LinkProvider` supplies the Next.js link, your own link component, and the loading component used by `Link`.
|
|
49
|
+
|
|
50
|
+
It also receives the current pathname so that it can detect when a navigation has completed.
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
import Link from 'next/link';
|
|
54
|
+
import { usePathname } from 'next/navigation';
|
|
55
|
+
import {
|
|
56
|
+
LinkProvider,
|
|
57
|
+
} from '@next-box/link-extra';
|
|
58
|
+
|
|
59
|
+
const LinkProviderWrapper = ({
|
|
60
|
+
children,
|
|
61
|
+
}: {
|
|
62
|
+
children: ReactNode;
|
|
63
|
+
}) => {
|
|
64
|
+
const pathname = usePathname();
|
|
65
|
+
|
|
66
|
+
return (
|
|
67
|
+
<LinkProvider
|
|
68
|
+
LoadingComponent={Loading}
|
|
69
|
+
NextLink={Link}
|
|
70
|
+
OwnLink={YourLink}
|
|
71
|
+
pathname={pathname}
|
|
72
|
+
>
|
|
73
|
+
{children}
|
|
74
|
+
</LinkProvider>
|
|
75
|
+
);
|
|
76
|
+
};
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
For Next.js applications using the App Router, the provider should be placed in a client component because it uses React context and client-side navigation state.
|
|
80
|
+
|
|
81
|
+
### Render a link
|
|
82
|
+
|
|
83
|
+
Once the provider has been configured, use the `Link` component in place of your normal Next.js link.
|
|
84
|
+
|
|
85
|
+
```tsx
|
|
86
|
+
import { Link } from '@next-box/link-extra';
|
|
87
|
+
|
|
88
|
+
const Component = () => {
|
|
89
|
+
return (
|
|
90
|
+
<Link href="/dashboard">
|
|
91
|
+
Dashboard
|
|
92
|
+
</Link>
|
|
93
|
+
);
|
|
94
|
+
};
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Disable Router Cache
|
|
98
|
+
|
|
99
|
+
Router cache busting is enabled by default.
|
|
100
|
+
|
|
101
|
+
To allow Next.js to use its normal Router Cache behaviour for an individual link, set `disableRouterCache` to `false`:
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
<Link
|
|
105
|
+
href="/dashboard"
|
|
106
|
+
disableRouterCache={false}
|
|
107
|
+
>
|
|
108
|
+
Dashboard
|
|
109
|
+
</Link>
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Configure loading behaviour
|
|
113
|
+
|
|
114
|
+
The loading timeout defaults to `500ms`. This can be changed through `LinkProvider`:
|
|
115
|
+
|
|
116
|
+
```tsx
|
|
117
|
+
<LinkProvider
|
|
118
|
+
LoadingComponent={Loading}
|
|
119
|
+
NextLink={Link}
|
|
120
|
+
OwnLink={YourLink}
|
|
121
|
+
pathname={pathname}
|
|
122
|
+
loadingTimeout={1000}
|
|
123
|
+
>
|
|
124
|
+
{children}
|
|
125
|
+
</LinkProvider>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The loading component is only rendered when a link navigation remains in progress beyond the configured timeout.
|
|
129
|
+
|
|
130
|
+
### Prevent loading for a link
|
|
131
|
+
|
|
132
|
+
The loading state is only triggered when the link represents navigation to a different URL and the click has not been prevented.
|
|
133
|
+
|
|
134
|
+
This means links that point to the current location, or clicks where `event.preventDefault()` has been called, do not trigger the loading indicator.
|
|
135
|
+
|
|
136
|
+
## Changelog
|
|
137
|
+
|
|
138
|
+
See the [changelog](../../CHANGELOG.md) for features, fixes, and other changes included in each major, minor, and patch release.
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
`@next-box/link-extra` is [MIT Licensed](LICENSE).
|
|
@@ -1,46 +1,46 @@
|
|
|
1
1
|
-----------------------------
|
|
2
2
|
Rollup File Analysis
|
|
3
3
|
-----------------------------
|
|
4
|
-
bundle size: 4.
|
|
4
|
+
bundle size: 4.759 KB
|
|
5
5
|
original size: 5.717 KB
|
|
6
|
-
code reduction:
|
|
6
|
+
code reduction: 16.76 %
|
|
7
7
|
module count: 5
|
|
8
8
|
|
|
9
9
|
██████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
|
|
10
10
|
file: /src/helpers.ts
|
|
11
|
-
bundle space:
|
|
12
|
-
rendered size: 1.
|
|
11
|
+
bundle space: 36.81 %
|
|
12
|
+
rendered size: 1.752 KB
|
|
13
13
|
original size: 1.739 KB
|
|
14
|
-
code reduction: 0
|
|
14
|
+
code reduction: 0 %
|
|
15
15
|
dependents: 2
|
|
16
16
|
- /src/Link.tsx
|
|
17
17
|
- /src/index.ts
|
|
18
18
|
|
|
19
19
|
█████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
|
|
20
20
|
file: /src/LinkProvider.tsx
|
|
21
|
-
bundle space: 35.
|
|
22
|
-
rendered size: 1.
|
|
21
|
+
bundle space: 35.91 %
|
|
22
|
+
rendered size: 1.709 KB
|
|
23
23
|
original size: 2.064 KB
|
|
24
|
-
code reduction:
|
|
24
|
+
code reduction: 17.2 %
|
|
25
25
|
dependents: 2
|
|
26
26
|
- /src/useLinkExtra.ts
|
|
27
27
|
- /src/index.ts
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
|
|
30
30
|
file: /src/Link.tsx
|
|
31
|
-
bundle space:
|
|
32
|
-
rendered size: 1.
|
|
31
|
+
bundle space: 25.93 %
|
|
32
|
+
rendered size: 1.234 KB
|
|
33
33
|
original size: 1.544 KB
|
|
34
|
-
code reduction:
|
|
34
|
+
code reduction: 20.08 %
|
|
35
35
|
dependents: 1
|
|
36
36
|
- /src/index.ts
|
|
37
37
|
|
|
38
38
|
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
|
|
39
39
|
file: /src/useLinkExtra.ts
|
|
40
|
-
bundle space: 1.
|
|
41
|
-
rendered size:
|
|
40
|
+
bundle space: 1.34 %
|
|
41
|
+
rendered size: 64 Bytes
|
|
42
42
|
original size: 213 Bytes
|
|
43
|
-
code reduction:
|
|
43
|
+
code reduction: 69.95 %
|
|
44
44
|
dependents: 2
|
|
45
45
|
- /src/Link.tsx
|
|
46
46
|
- /src/index.ts
|
package/package.json
CHANGED