swr-devtools-react 0.0.0-stage → 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Paul Livingstone
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,3 +1,210 @@
1
- # Temporary Holding Version
1
+ # swr-devtools-react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/swr-devtools-react)](https://www.npmjs.com/package/swr-devtools-react)
4
+ [![CI](https://github.com/TheFlyer1983/swr-devtools-react/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TheFlyer1983/swr-devtools-react/actions/workflows/ci.yml)
5
+
6
+ In-app devtools for [SWR](https://swr.vercel.app): see every cache key, then revalidate, edit or delete it from a floating panel. Inspired by TanStack Query Devtools.
7
+
8
+ ![The devtools panel docked at the bottom of the Vite playground, with a key selected and its data shown as a JSON tree](https://raw.githubusercontent.com/TheFlyer1983/swr-devtools-react/main/docs/images/panel.png)
9
+
10
+ ## Features
11
+
12
+ - Every key in the SWR cache, with a status badge (loading, validating, success, error, idle) and the time since its data last changed. The list updates live.
13
+ - Array and object keys shown readably. `useSWRInfinite` and `useSWRSubscription` keys are labelled.
14
+ - Search keys by text, and sort by key, status or last updated.
15
+ - A detail view with the full key, any error, and the data as a collapsible JSON tree.
16
+ - Revalidate, edit or delete a key, or clear the whole cache.
17
+ - Renders inside a Shadow DOM, so your app's CSS can't break it and its CSS can't leak into your app.
18
+ - Renders nothing in production builds, and the code is tree-shaken out.
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ npm install --save-dev swr-devtools-react
24
+ ```
25
+
26
+ ```bash
27
+ pnpm add --save-dev swr-devtools-react
28
+ ```
29
+
30
+ It needs React 18 or 19 and SWR 2 in your app. It's a dev dependency because production builds drop it. If you [force it on for staging](#forcing-it-on-eg-staging), install it as a regular dependency instead.
31
+
32
+ ## Setup
33
+
34
+ Add `<SWRDevtools />` inside your `<SWRConfig>`. There's no provider or middleware to add.
35
+
36
+ ```tsx
37
+ import { SWRConfig } from 'swr';
38
+ import { SWRDevtools } from 'swr-devtools-react';
39
+
40
+ export function Root() {
41
+ return (
42
+ <SWRConfig value={{ fetcher }}>
43
+ <App />
44
+ <SWRDevtools />
45
+ </SWRConfig>
46
+ );
47
+ }
48
+ ```
49
+
50
+ A button labelled "SWR" appears in the corner. Click it to open the panel.
51
+
52
+ The panel shows the cache of the nearest `<SWRConfig>`. If your app has no `<SWRConfig>`, it shows SWR's default global cache, and `<SWRDevtools />` can go anywhere in the tree. With several `<SWRConfig provider>`s, it sees only the nearest one.
53
+
54
+ ## Props
55
+
56
+ ### `<SWRDevtools />`
57
+
58
+ | Prop | Type | Default | Description |
59
+ | ---------------- | -------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
60
+ | `initialIsOpen` | `boolean` | `false` | Start with the panel open. Once the user opens or closes the panel, their choice is saved in `localStorage` and wins over this prop. |
61
+ | `buttonPosition` | `'top-left'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-right'` | `'bottom-right'` | Which corner of the viewport the toggle button sits in. |
62
+ | `position` | `'bottom'` \| `'right'` | `'bottom'` | Where the panel docks. |
63
+
64
+ Drag the panel's edge to resize it, or focus the edge and use the arrow keys. The size is saved in `localStorage` too.
65
+
66
+ The prop types are exported as `SWRDevtoolsProps`, `ButtonPosition` and `PanelPosition`.
67
+
68
+ ### `<SWRDevtoolsPanel />`
69
+
70
+ The panel on its own, with no toggle button and no props. It fills the element you render it in, so give that element a size. Use it to put the devtools in your own layout, such as a sidebar or a tab in another devtools tool.
71
+
72
+ ```tsx
73
+ import { SWRDevtoolsPanel } from 'swr-devtools-react';
74
+
75
+ <SWRConfig value={{ fetcher }}>
76
+ <App />
77
+ <div style={{ height: 400 }}>
78
+ <SWRDevtoolsPanel />
79
+ </div>
80
+ </SWRConfig>;
81
+ ```
82
+
83
+ ## Next.js
84
+
85
+ Both routers work. The package starts with `'use client'`, so you don't need to wrap it in a client component yourself.
86
+
87
+ ### App Router
88
+
89
+ Render `<SWRDevtools />` in your root layout, inside the client component that holds your `<SWRConfig>`:
90
+
91
+ ```tsx
92
+ // app/providers.tsx
93
+ 'use client';
94
+
95
+ import type { ReactNode } from 'react';
96
+ import { SWRConfig } from 'swr';
97
+
98
+ const fetcher = (url: string) => fetch(url).then((res) => res.json());
99
+
100
+ export function Providers({ children }: { children: ReactNode }) {
101
+ return <SWRConfig value={{ fetcher }}>{children}</SWRConfig>;
102
+ }
103
+ ```
104
+
105
+ ```tsx
106
+ // app/layout.tsx (a server component)
107
+ import type { ReactNode } from 'react';
108
+ import { SWRDevtools } from 'swr-devtools-react';
109
+ import { Providers } from './providers';
110
+
111
+ export default function RootLayout({ children }: { children: ReactNode }) {
112
+ return (
113
+ <html lang="en">
114
+ <body>
115
+ <Providers>
116
+ {children}
117
+ <SWRDevtools />
118
+ </Providers>
119
+ </body>
120
+ </html>
121
+ );
122
+ }
123
+ ```
124
+
125
+ `<SWRConfig>` with a fetcher has to live in a client component, because a server component can't pass a function as a prop. `<SWRDevtools />` can sit in the server layout as long as it's inside `<Providers>`.
126
+
127
+ ### Pages Router
128
+
129
+ Put it in `pages/_app.tsx`, so every page gets it:
130
+
131
+ ```tsx
132
+ // pages/_app.tsx
133
+ import type { AppProps } from 'next/app';
134
+ import { SWRConfig } from 'swr';
135
+ import { SWRDevtools } from 'swr-devtools-react';
136
+
137
+ const fetcher = (url: string) => fetch(url).then((res) => res.json());
138
+
139
+ export default function MyApp({ Component, pageProps }: AppProps) {
140
+ return (
141
+ <SWRConfig value={{ fetcher }}>
142
+ <Component {...pageProps} />
143
+ <SWRDevtools />
144
+ </SWRConfig>
145
+ );
146
+ }
147
+ ```
148
+
149
+ The devtools render only in the browser, after hydration, so they don't cause hydration mismatches.
150
+
151
+ ## Production builds
152
+
153
+ `<SWRDevtools />` and `<SWRDevtoolsPanel />` render nothing when `process.env.NODE_ENV` is `production`. Your bundler (Vite, Next.js, webpack) replaces that check at build time, so a production build contains no devtools code. You don't need to wrap them in your own check.
154
+
155
+ ### Forcing it on (e.g. staging)
156
+
157
+ Staging builds usually have `NODE_ENV=production` too. To keep the devtools there, import from `swr-devtools-react/production`, which skips the check. Gate the import behind your own build-time flag, so it stays out of the real production bundle:
158
+
159
+ ```tsx
160
+ import { lazy, Suspense } from 'react';
161
+ import { SWRDevtools } from 'swr-devtools-react';
162
+
163
+ // The flag must be replaced at build time (here, Vite's `import.meta.env`), and
164
+ // the `import()` must sit inside the check. Then a build with the flag off
165
+ // drops the devtools.
166
+ const SWRDevtoolsProduction =
167
+ import.meta.env.VITE_ENABLE_SWR_DEVTOOLS === 'true'
168
+ ? lazy(() =>
169
+ import('swr-devtools-react/production').then((module) => ({
170
+ default: module.SWRDevtools
171
+ }))
172
+ )
173
+ : null;
174
+
175
+ export function Devtools() {
176
+ if (!SWRDevtoolsProduction) return <SWRDevtools />;
177
+ return (
178
+ <Suspense fallback={null}>
179
+ <SWRDevtoolsProduction />
180
+ </Suspense>
181
+ );
182
+ }
183
+ ```
184
+
185
+ Render `<Devtools />` inside your `<SWRConfig>`, where `<SWRDevtools />` would go. In Next.js, use a `NEXT_PUBLIC_` variable through `process.env` instead of `import.meta.env`.
186
+
187
+ Two things keep the devtools in the bundle:
188
+
189
+ - **A runtime flag**, such as a query param. It only controls whether the devtools load. The bundler can't know its value, so the devtools stay in the build.
190
+ - **A `lazy()` call outside the check.** Bundlers keep it even when the flag is off. In a Vite build this put the whole panel in the main bundle.
191
+
192
+ A static `import ... from 'swr-devtools-react/production'` also ships the devtools in every build that includes it.
193
+
194
+ ## Known limits
195
+
196
+ - **Deleting a key** removes it from the cache and tells mounted hooks. A hook using `keepPreviousData` keeps showing its last data until it next fetches, because SWR keeps that copy inside the hook.
197
+ - **Clear all** on SWR 2.5 or later uses SWR's `unload()`, which also cancels in-flight requests and drops `keepPreviousData` copies. On older SWR it deletes keys one by one, with the same limit as above.
198
+ - **Several caches.** Only the nearest `<SWRConfig>`'s cache is shown. Choosing between caches is tracked in [#25](https://github.com/TheFlyer1983/swr-devtools-react/issues/25).
199
+
200
+ ## Roadmap
201
+
202
+ Next up are a TanStack Devtools plugin, observer counts per key, and a light theme that follows the system setting. The [spec](https://github.com/TheFlyer1983/swr-devtools-react/blob/main/docs/SPEC.md) lists what's planned, and the [project board](https://github.com/users/TheFlyer1983/projects/7) shows what's in progress.
203
+
204
+ ## Contributing
205
+
206
+ See [CONTRIBUTING.md](https://github.com/TheFlyer1983/swr-devtools-react/blob/main/CONTRIBUTING.md) for local setup, the playgrounds and how PRs work.
207
+
208
+ ## Licence
209
+
210
+ [MIT](https://github.com/TheFlyer1983/swr-devtools-react/blob/main/LICENSE)
@@ -0,0 +1,15 @@
1
+ 'use client';
2
+ import { a as PanelPosition, i as SWRDevtoolsProps, n as ButtonPosition, r as SWRDevtools$1, t as SWRDevtoolsPanel$1 } from "./production-C15b5Ipu.js";
3
+ /**
4
+ * A floating button that opens the devtools panel. Renders nothing when
5
+ * `NODE_ENV` is `production`; import from `swr-devtools-react/production` to
6
+ * force it on.
7
+ */
8
+ export declare const SWRDevtools: typeof SWRDevtools$1;
9
+ /**
10
+ * The devtools panel on its own, with no floating button. Renders nothing when
11
+ * `NODE_ENV` is `production`; import from `swr-devtools-react/production` to
12
+ * force it on.
13
+ */
14
+ export declare const SWRDevtoolsPanel: typeof SWRDevtoolsPanel$1;
15
+ export type { ButtonPosition, PanelPosition, SWRDevtoolsProps };
package/dist/index.js ADDED
@@ -0,0 +1,17 @@
1
+ 'use client';
2
+ import { n as SWRDevtools$1, t as SWRDevtoolsPanel$1 } from "./production-BQanzhqs.js";
3
+ // src/index.ts
4
+ const isProduction = process.env.NODE_ENV === "production";
5
+ /**
6
+ * A floating button that opens the devtools panel. Renders nothing when
7
+ * `NODE_ENV` is `production`; import from `swr-devtools-react/production` to
8
+ * force it on.
9
+ */
10
+ const SWRDevtools = isProduction ? () => null : SWRDevtools$1;
11
+ /**
12
+ * The devtools panel on its own, with no floating button. Renders nothing when
13
+ * `NODE_ENV` is `production`; import from `swr-devtools-react/production` to
14
+ * force it on.
15
+ */
16
+ const SWRDevtoolsPanel = isProduction ? () => null : SWRDevtoolsPanel$1;
17
+ export { SWRDevtools, SWRDevtoolsPanel };