@octanejs/tanstack-query-devtools 0.0.0-stage → 0.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dominic Gannaway
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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2021-present Tanner Linsley
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.
package/README.md CHANGED
@@ -1,3 +1,64 @@
1
- # Temporary Holding Version
1
+ # @octanejs/tanstack-query-devtools
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
+ [TanStack Query Devtools](https://tanstack.com/query/latest/docs/framework/react/devtools)
4
+ for [Octane](https://github.com/octanejs/octane).
5
+
6
+ This is an Octane port of `@tanstack/react-query-devtools`. It reuses the
7
+ framework-agnostic `@tanstack/query-devtools` core **unchanged** and ports the thin
8
+ adapter layer: the `ReactQueryDevtools` floating panel and the `ReactQueryDevtoolsPanel`
9
+ embedded panel. It works with [`@octanejs/tanstack-query`](../tanstack-query).
10
+
11
+ ## Installation
12
+
13
+ ```bash
14
+ npm install @octanejs/tanstack-query-devtools @octanejs/tanstack-query
15
+ pnpm add @octanejs/tanstack-query-devtools @octanejs/tanstack-query
16
+ ```
17
+
18
+ ## Usage
19
+
20
+ ```tsx
21
+ import { QueryClient, QueryClientProvider } from '@octanejs/tanstack-query';
22
+ import { ReactQueryDevtools } from '@octanejs/tanstack-query-devtools';
23
+
24
+ const client = new QueryClient();
25
+
26
+ function App() @{
27
+ <QueryClientProvider client={client}>
28
+ <Todos />
29
+ <ReactQueryDevtools initialIsOpen={false} />
30
+ </QueryClientProvider>
31
+ }
32
+ ```
33
+
34
+ `ReactQueryDevtoolsPanel` embeds the panel inline instead of floating it:
35
+
36
+ ```tsx
37
+ import { ReactQueryDevtoolsPanel } from '@octanejs/tanstack-query-devtools';
38
+
39
+ function Debug() @{
40
+ <ReactQueryDevtoolsPanel style={{ height: '400px' }} onClose={() => {}} />
41
+ }
42
+ ```
43
+
44
+ Both components take the same props as their React counterparts, and resolve the
45
+ `QueryClient` from the nearest `QueryClientProvider` unless a `client` prop is passed.
46
+
47
+ ## Development only by default
48
+
49
+ As in the React package, the root entry renders nothing unless
50
+ `process.env.NODE_ENV === 'development'`. Import from the `production` subpath to keep
51
+ the devtools in a production build:
52
+
53
+ ```tsx
54
+ import { ReactQueryDevtools } from '@octanejs/tanstack-query-devtools/production';
55
+ ```
56
+
57
+ ## Differences from `@tanstack/react-query-devtools`
58
+
59
+ - The devtools core instance is created in a lazy `useState` initializer, so a re-render
60
+ does not construct and discard a new core instance.
61
+ - `style` on `ReactQueryDevtoolsPanel` takes Octane's `CSSProperties`, and `onClose` may
62
+ return any value.
63
+
64
+ See [`UPSTREAM.md`](./UPSTREAM.md) for the pinned upstream release and export crosswalk.
package/UPSTREAM.md ADDED
@@ -0,0 +1,47 @@
1
+ # Upstream
2
+
3
+ - Package: `@tanstack/react-query-devtools@5.102.8`
4
+ - Repository: https://github.com/TanStack/query
5
+ - Release tag: `@tanstack/react-query-devtools@5.102.8`, which resolves to commit
6
+ `2969edf32f7e0c48e2a108d84712d6e01edfde21`. npm publishes no `gitHead` for this
7
+ release, so the commit comes from the signed npm provenance and the release tag; it is
8
+ the same commit `@octanejs/tanstack-query` pins for `@tanstack/react-query@5.102.8`.
9
+ - Source and tests: `packages/react-query-devtools/src`, including `src/__tests__`
10
+ - License: MIT; exact upstream text ships as `LICENSE.upstream`.
11
+
12
+ ## Source boundary
13
+
14
+ `audit/upstream.lock.json` pins every regular file in the package subtree that is not a
15
+ monorepo configuration symlink. `upstream/` is byte-exact, unpublished evidence.
16
+ `tests/upstream/` is regenerated from the lock's import rewrites; no divergence patch is
17
+ needed because the two upstream test files run unmodified apart from import repointing.
18
+
19
+ The framework-neutral `@tanstack/query-devtools@5.102.8` (a self-contained Solid bundle with
20
+ no React import) is reused unchanged as a dependency. The query client, `onlineManager`
21
+ and `useQueryClient` come from `@octanejs/tanstack-query`.
22
+
23
+ ## Export crosswalk
24
+
25
+ | Upstream export (`@tanstack/react-query-devtools`) | Disposition |
26
+ | --- | --- |
27
+ | `ReactQueryDevtools` | ported (`src/ReactQueryDevtools.tsrx`) |
28
+ | `ReactQueryDevtoolsPanel` | ported (`src/ReactQueryDevtoolsPanel.tsrx`) |
29
+ | `DevtoolsPanelOptions` (type) | ported |
30
+ | `./production` entry: `ReactQueryDevtools`, `ReactQueryDevtoolsPanel` | ported (`src/production.ts`) |
31
+
32
+ The development-only switch in `src/index.ts` mirrors upstream.
33
+
34
+ ## Divergences
35
+
36
+ - Hooks come from `octane`; `useRef` is typed `HTMLDivElement | null` as Octane requires.
37
+ - The core instance is built in a lazy `useState` initializer (upstream passes an eagerly
38
+ constructed instance, discarded on every re-render after the first). Observable
39
+ behavior is otherwise identical; the upstream suite has no constructor-count assertion.
40
+ - Element construction is authored in `.tsrx`; `className` is written `class`.
41
+ - `CSSProperties` and `OctaneNode` replace `React.CSSProperties` and `React.ReactElement`.
42
+
43
+ ## Behavioral oracle
44
+
45
+ All 37 upstream registrations run unchanged against real React (`tanstack-query-devtools-pristine`)
46
+ and, with import rewrites only, against Octane (`tanstack-query-devtools-adapted`).
47
+ Octane-only conformance and SSR tests live under `tests/conformance` and `tests/ssr`.
package/package.json CHANGED
@@ -1,6 +1,62 @@
1
1
  {
2
2
  "name": "@octanejs/tanstack-query-devtools",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.1",
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "engines": {
7
+ "node": ">=22.22.2"
8
+ },
9
+ "description": "TanStack Query devtools bindings for Octane — reuses @tanstack/query-devtools and ports the React adapter's ReactQueryDevtools and ReactQueryDevtoolsPanel components.",
10
+ "author": {
11
+ "name": "Dominic Gannaway",
12
+ "email": "dg@domgan.com"
13
+ },
14
+ "publishConfig": {
15
+ "access": "public"
16
+ },
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/octanejs/octane.git",
20
+ "directory": "packages/tanstack-query-devtools"
21
+ },
22
+ "main": "src/index.ts",
23
+ "module": "src/index.ts",
24
+ "types": "src/index.ts",
25
+ "files": [
26
+ "src",
27
+ "README.md",
28
+ "UPSTREAM.md",
29
+ "LICENSE.upstream"
30
+ ],
31
+ "exports": {
32
+ ".": "./src/index.ts",
33
+ "./production": "./src/production.ts"
34
+ },
35
+ "dependencies": {
36
+ "@tanstack/query-devtools": "5.102.8"
37
+ },
38
+ "peerDependencies": {
39
+ "@octanejs/tanstack-query": "0.1.63",
40
+ "octane": "^0.11.0"
41
+ },
42
+ "devDependencies": {
43
+ "@octanejs/tanstack-query": "0.1.63",
44
+ "@octanejs/testing-library": "0.1.61",
45
+ "@tanstack/react-query": "5.102.8",
46
+ "@tanstack/react-query-devtools": "5.102.8",
47
+ "@testing-library/jest-dom": "^6.9.1",
48
+ "@testing-library/react": "^16.3.2",
49
+ "@tsrx/react": "^0.4.5",
50
+ "@types/react": "^19.2.17",
51
+ "@types/react-dom": "^19.2.3",
52
+ "esbuild": "^0.28.1",
53
+ "octane": "0.11.0",
54
+ "react": "19.2.7",
55
+ "react-dom": "19.2.7",
56
+ "vitest": "^4.1.10"
57
+ },
58
+ "scripts": {
59
+ "test": "vitest run",
60
+ "typecheck": "octane-tsc -p tsconfig.json"
61
+ }
6
62
  }
@@ -0,0 +1,137 @@
1
+ // Ported from @tanstack/react-query-devtools 5.102.8
2
+ // (https://github.com/TanStack/query/blob/2969edf32f7e0c48e2a108d84712d6e01edfde21/packages/react-query-devtools/src/ReactQueryDevtools.tsx).
3
+ //
4
+ // Octane adaptations:
5
+ // - React hooks (useEffect/useRef/useState) come directly from octane.
6
+ // - `useQueryClient` and `onlineManager` come from @octanejs/tanstack-query.
7
+ // - The framework-agnostic `@tanstack/query-devtools` core is reused UNCHANGED.
8
+ // - The devtools instance is created in a lazy `useState` initializer, so re-renders do not
9
+ // construct (and discard) a new core instance.
10
+ import { useEffect, useRef, useState } from 'octane';
11
+ import { onlineManager, useQueryClient } from '@octanejs/tanstack-query';
12
+ import { TanstackQueryDevtools } from '@tanstack/query-devtools';
13
+ import type {
14
+ DevtoolsButtonPosition,
15
+ DevtoolsErrorType,
16
+ DevtoolsPosition,
17
+ Theme,
18
+ } from '@tanstack/query-devtools';
19
+ import type { QueryClient } from '@octanejs/tanstack-query';
20
+ import type { OctaneNode } from 'octane';
21
+
22
+ export interface DevtoolsOptions {
23
+ /**
24
+ * Set this true if you want the dev tools to default to being open
25
+ */
26
+ initialIsOpen?: boolean;
27
+ /**
28
+ * The position of the TanStack logo to open and close the devtools panel.
29
+ * 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'relative'
30
+ * Defaults to 'bottom-right'.
31
+ */
32
+ buttonPosition?: DevtoolsButtonPosition;
33
+ /**
34
+ * The position of the React Query devtools panel.
35
+ * 'top' | 'bottom' | 'left' | 'right'
36
+ * Defaults to 'bottom'.
37
+ */
38
+ position?: DevtoolsPosition;
39
+ /**
40
+ * Custom instance of QueryClient
41
+ */
42
+ client?: QueryClient;
43
+ /**
44
+ * Use this so you can define custom errors that can be shown in the devtools.
45
+ */
46
+ errorTypes?: Array<DevtoolsErrorType>;
47
+ /**
48
+ * Use this to pass a nonce to the style tag that is added to the document head. This is useful if you are using a Content Security Policy (CSP) nonce to allow inline styles.
49
+ */
50
+ styleNonce?: string;
51
+ /**
52
+ * Use this so you can attach the devtool's styles to specific element in the DOM.
53
+ */
54
+ shadowDOMTarget?: ShadowRoot;
55
+ /**
56
+ * Set this to true to hide disabled queries from the devtools panel.
57
+ */
58
+ hideDisabledQueries?: boolean;
59
+ /**
60
+ * Set this to 'light', 'dark', or 'system' to change the theme of the devtools panel.
61
+ * Defaults to 'system'.
62
+ */
63
+ theme?: Theme;
64
+ }
65
+
66
+ export function ReactQueryDevtools(props: DevtoolsOptions): OctaneNode {
67
+ const queryClient = useQueryClient(props.client);
68
+ const ref = useRef<HTMLDivElement | null>(null);
69
+ const {
70
+ buttonPosition,
71
+ position,
72
+ initialIsOpen,
73
+ errorTypes,
74
+ styleNonce,
75
+ shadowDOMTarget,
76
+ hideDisabledQueries,
77
+ theme,
78
+ } = props;
79
+ // OCTANE DIVERGENCE[lazy-core-construction][conformance:tanstack-query-devtools-constructs-the-core-once-across-re-renders-and-updates-it-in-place]: the core is built in a lazy initializer so re-renders reuse it.
80
+ const [devtools] = useState(
81
+ () =>
82
+ new TanstackQueryDevtools({
83
+ client: queryClient,
84
+ queryFlavor: 'React Query',
85
+ version: '5',
86
+ onlineManager,
87
+ buttonPosition,
88
+ position,
89
+ initialIsOpen,
90
+ errorTypes,
91
+ styleNonce,
92
+ shadowDOMTarget,
93
+ hideDisabledQueries,
94
+ theme,
95
+ }),
96
+ );
97
+
98
+ useEffect(() => {
99
+ devtools.setClient(queryClient);
100
+ }, [queryClient, devtools]);
101
+
102
+ useEffect(() => {
103
+ if (buttonPosition) {
104
+ devtools.setButtonPosition(buttonPosition);
105
+ }
106
+ }, [buttonPosition, devtools]);
107
+
108
+ useEffect(() => {
109
+ if (position) {
110
+ devtools.setPosition(position);
111
+ }
112
+ }, [position, devtools]);
113
+
114
+ useEffect(() => {
115
+ devtools.setInitialIsOpen(initialIsOpen || false);
116
+ }, [initialIsOpen, devtools]);
117
+
118
+ useEffect(() => {
119
+ devtools.setErrorTypes(errorTypes || []);
120
+ }, [errorTypes, devtools]);
121
+
122
+ useEffect(() => {
123
+ devtools.setTheme(theme);
124
+ }, [theme, devtools]);
125
+
126
+ useEffect(() => {
127
+ if (ref.current) {
128
+ devtools.mount(ref.current);
129
+ }
130
+
131
+ return () => {
132
+ devtools.unmount();
133
+ };
134
+ }, [devtools]);
135
+
136
+ return <div dir="ltr" class="tsqd-parent-container" ref={ref}></div>;
137
+ }
@@ -0,0 +1,106 @@
1
+ // Ported from @tanstack/react-query-devtools 5.102.8
2
+ // (https://github.com/TanStack/query/blob/2969edf32f7e0c48e2a108d84712d6e01edfde21/packages/react-query-devtools/src/ReactQueryDevtoolsPanel.tsx).
3
+ //
4
+ // Octane adaptations: see ReactQueryDevtools.tsrx.
5
+ import { useEffect, useRef, useState } from 'octane';
6
+ import { onlineManager, useQueryClient } from '@octanejs/tanstack-query';
7
+ import { TanstackQueryDevtoolsPanel } from '@tanstack/query-devtools';
8
+ import type { DevtoolsErrorType, Theme } from '@tanstack/query-devtools';
9
+ import type { QueryClient } from '@octanejs/tanstack-query';
10
+ import type { CSSProperties, OctaneNode } from 'octane';
11
+
12
+ export interface DevtoolsPanelOptions {
13
+ /**
14
+ * Custom instance of QueryClient
15
+ */
16
+ client?: QueryClient;
17
+ /**
18
+ * Use this so you can define custom errors that can be shown in the devtools.
19
+ */
20
+ errorTypes?: Array<DevtoolsErrorType>;
21
+ /**
22
+ * Use this to pass a nonce to the style tag that is added to the document head. This is useful if you are using a Content Security Policy (CSP) nonce to allow inline styles.
23
+ */
24
+ styleNonce?: string;
25
+ /**
26
+ * Use this so you can attach the devtool's styles to specific element in the DOM.
27
+ */
28
+ shadowDOMTarget?: ShadowRoot;
29
+
30
+ /**
31
+ * Custom styles for the devtools panel
32
+ * @default { height: '500px' }
33
+ * @example { height: '100%' }
34
+ * @example { height: '100%', width: '100%' }
35
+ */
36
+ style?: CSSProperties;
37
+
38
+ /**
39
+ * Callback function that is called when the devtools panel is closed
40
+ */
41
+ onClose?: () => unknown;
42
+ /**
43
+ * Set this to true to hide disabled queries from the devtools panel.
44
+ */
45
+ hideDisabledQueries?: boolean;
46
+ /**
47
+ * Set this to 'light', 'dark', or 'system' to change the theme of the devtools panel.
48
+ * Defaults to 'system'.
49
+ */
50
+ theme?: Theme;
51
+ }
52
+
53
+ export function ReactQueryDevtoolsPanel(props: DevtoolsPanelOptions): OctaneNode {
54
+ const queryClient = useQueryClient(props.client);
55
+ const ref = useRef<HTMLDivElement | null>(null);
56
+ const { errorTypes, styleNonce, shadowDOMTarget, hideDisabledQueries, theme } = props;
57
+ // OCTANE DIVERGENCE[lazy-core-construction][conformance:tanstack-query-devtools-constructs-the-core-once-across-re-renders-and-updates-it-in-place]: the core is built in a lazy initializer so re-renders reuse it.
58
+ const [devtools] = useState(
59
+ () =>
60
+ new TanstackQueryDevtoolsPanel({
61
+ client: queryClient,
62
+ queryFlavor: 'React Query',
63
+ version: '5',
64
+ onlineManager,
65
+ buttonPosition: 'bottom-left',
66
+ position: 'bottom',
67
+ initialIsOpen: true,
68
+ errorTypes,
69
+ styleNonce,
70
+ shadowDOMTarget,
71
+ onClose: props.onClose,
72
+ hideDisabledQueries,
73
+ theme,
74
+ }),
75
+ );
76
+
77
+ useEffect(() => {
78
+ devtools.setClient(queryClient);
79
+ }, [queryClient, devtools]);
80
+
81
+ useEffect(() => {
82
+ devtools.setOnClose(props.onClose ?? (() => {}));
83
+ }, [props.onClose, devtools]);
84
+
85
+ useEffect(() => {
86
+ devtools.setErrorTypes(errorTypes || []);
87
+ }, [errorTypes, devtools]);
88
+
89
+ useEffect(() => {
90
+ devtools.setTheme(theme);
91
+ }, [theme, devtools]);
92
+
93
+ useEffect(() => {
94
+ if (ref.current) {
95
+ devtools.mount(ref.current);
96
+ }
97
+
98
+ return () => {
99
+ devtools.unmount();
100
+ };
101
+ }, [devtools]);
102
+
103
+ return (
104
+ <div style={{ height: '500px', ...props.style }} class="tsqd-parent-container" ref={ref}></div>
105
+ );
106
+ }
package/src/index.ts ADDED
@@ -0,0 +1,21 @@
1
+ // Bundlers replace `process.env.NODE_ENV`; a scaffolded consumer installs no @types/node.
2
+ declare const process: { env: { NODE_ENV?: string } };
3
+
4
+ import * as Devtools from './ReactQueryDevtools.tsrx';
5
+ import * as DevtoolsPanel from './ReactQueryDevtoolsPanel.tsrx';
6
+
7
+ export const ReactQueryDevtools: (typeof Devtools)['ReactQueryDevtools'] =
8
+ process.env.NODE_ENV !== 'development'
9
+ ? function () {
10
+ return null;
11
+ }
12
+ : Devtools.ReactQueryDevtools;
13
+
14
+ export const ReactQueryDevtoolsPanel: (typeof DevtoolsPanel)['ReactQueryDevtoolsPanel'] =
15
+ process.env.NODE_ENV !== 'development'
16
+ ? function () {
17
+ return null;
18
+ }
19
+ : DevtoolsPanel.ReactQueryDevtoolsPanel;
20
+
21
+ export type DevtoolsPanelOptions = DevtoolsPanel.DevtoolsPanelOptions;
@@ -0,0 +1,5 @@
1
+ import * as Devtools from './ReactQueryDevtools.tsrx';
2
+ import * as DevtoolsPanel from './ReactQueryDevtoolsPanel.tsrx';
3
+
4
+ export const ReactQueryDevtools = Devtools.ReactQueryDevtools;
5
+ export const ReactQueryDevtoolsPanel = DevtoolsPanel.ReactQueryDevtoolsPanel;