feat: add initial utils package (#166)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: AlemTuzlak

.changeset/rare-owls-find.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/devtools-utils': patch
+---
+
+initial release of utils

knip.json

@@ -1,8 +1,13 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "ignoreDependencies": ["@size-limit/preset-small-lib", "@faker-js/faker"],
+  "ignoreDependencies": ["@faker-js/faker"],
   "ignoreWorkspaces": ["examples/**"],
   "workspaces": {
+    "packages/devtools-utils": {
+      "ignoreDependencies": ["react", "solid-js", "@types/react"],
+      "entry": ["**/vite.config.solid.ts", "**/src/solid/**"],
+      "project": ["**/vite.config.solid.ts", "**/src/solid/**"]
+    },
     "packages/solid-devtools": {
       "ignore": ["**/core.tsx"]
     }

packages/devtools-utils/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @tanstack/devtools-utils
+
+This package is still under active development and might have breaking changes in the future. Please use it with caution.

packages/devtools-utils/README.md

@@ -0,0 +1,10 @@
+// @ts-check
+
+import rootConfig from '../../eslint.config.js'
+
+export default [
+  ...rootConfig,
+  {
+    rules: {},
+  },
+]

packages/devtools-utils/eslint.config.js

@@ -0,0 +1,76 @@
+{
+  "name": "@tanstack/devtools-utils",
+  "version": "0.0.0",
+  "description": "TanStack Devtools utilities for creating your own devtools.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/devtools.git",
+    "directory": "packages/devtools"
+  },
+  "homepage": "https://tanstack.com/devtools",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "devtools"
+  ],
+  "type": "module",
+  "exports": {
+    "./react": {
+      "import": {
+        "types": "./dist/react/esm/index.d.ts",
+        "default": "./dist/react/esm/index.js"
+      }
+    },
+    "./solid": {
+      "import": {
+        "types": "./dist/solid/esm/index.d.ts",
+        "default": "./dist/solid/esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@tanstack/devtools-ui": "workspace:^"
+  },
+  "peerDependencies": {
+    "@types/react": ">=19.0.0",
+    "react": ">=19.0.0",
+    "solid-js": ">=1.9.7"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@types/react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist/",
+    "src"
+  ],
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:build": "publint --strict",
+    "build": "vite build && vite build --config ./vite.config.solid.ts "
+  },
+  "devDependencies": {
+    "vite-plugin-solid": "^2.11.8"
+  }
+}

packages/devtools-utils/package.json

@@ -0,0 +1,2 @@
+export * from './panel'
+export * from './plugin'

packages/devtools-utils/src/react/index.ts

@@ -0,0 +1,55 @@
+import { useEffect, useRef } from 'react'
+
+export interface DevtoolsPanelProps {
+  theme?: 'light' | 'dark'
+}
+
+/**
+ * Creates a React component that dynamically imports and mounts a devtools panel. SSR friendly.
+ * @param devtoolsPackageName The name of the devtools package to be imported, e.g., '@tanstack/devtools-react'
+ * @param importName The name of the export to be imported from the devtools package (e.g., 'default' or 'DevtoolsCore')
+ * @returns A React component that mounts the devtools
+ * @example
+ * ```tsx
+ * // if the export is default
+ * const [ReactDevtoolsPanel, NoOpReactDevtoolsPanel] = createReactPanel('@tanstack/devtools-react')
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // if the export is named differently
+ * const [ReactDevtoolsPanel, NoOpReactDevtoolsPanel] = createReactPanel('@tanstack/devtools-react', 'DevtoolsCore')
+ * ```
+ */
+export function createReactPanel<
+  TComponentProps extends DevtoolsPanelProps | undefined,
+  TCoreDevtoolsClass extends {
+    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    unmount: () => void
+  },
+>(CoreClass: new () => TCoreDevtoolsClass) {
+  function Panel(props: TComponentProps) {
+    const devToolRef = useRef<HTMLDivElement>(null)
+    const devtools = useRef<TCoreDevtoolsClass | null>(null)
+    useEffect(() => {
+      if (devtools.current) return
+
+      devtools.current = new CoreClass()
+
+      if (devToolRef.current) {
+        devtools.current.mount(devToolRef.current, props?.theme ?? 'dark')
+      }
+
+      return () => {
+        devtools.current?.unmount()
+      }
+    }, [props?.theme])
+
+    return <div style={{ height: '100%' }} ref={devToolRef} />
+  }
+
+  function NoOpPanel(_props: TComponentProps) {
+    return <></>
+  }
+  return [Panel, NoOpPanel] as const
+}

packages/devtools-utils/src/react/panel.tsx

@@ -0,0 +1,23 @@
+import type { JSX } from 'react'
+import type { DevtoolsPanelProps } from './panel'
+
+export function createReactPlugin(
+  name: string,
+  Component: (props: DevtoolsPanelProps) => JSX.Element,
+) {
+  function Plugin() {
+    return {
+      name: name,
+      render: (_el: HTMLElement, theme: 'light' | 'dark') => (
+        <Component theme={theme} />
+      ),
+    }
+  }
+  function NoOpPlugin() {
+    return {
+      name: name,
+      render: (_el: HTMLElement, _theme: 'light' | 'dark') => <></>,
+    }
+  }
+  return [Plugin, NoOpPlugin] as const
+}

packages/devtools-utils/src/react/plugin.tsx

@@ -0,0 +1,118 @@
+/** @jsxImportSource solid-js - we use Solid.js as JSX here */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { constructCoreClass } from './class'
+
+const lazyImportMock = vi.fn((fn) => fn())
+const renderMock = vi.fn()
+const portalMock = vi.fn((props: any) => <div>{props.children}</div>)
+
+vi.mock('solid-js', async () => {
+  const actual = await vi.importActual<any>('solid-js')
+  return {
+    ...actual,
+    lazy: lazyImportMock,
+  }
+})
+
+vi.mock('solid-js/web', async () => {
+  const actual = await vi.importActual<any>('solid-js/web')
+  return {
+    ...actual,
+    render: renderMock,
+    Portal: portalMock,
+  }
+})
+
+describe('constructCoreClass', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+  it('should export DevtoolsCore and NoOpDevtoolsCore classes and make no calls to Solid.js primitives', () => {
+    const [DevtoolsCore, NoOpDevtoolsCore] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    expect(DevtoolsCore).toBeDefined()
+    expect(NoOpDevtoolsCore).toBeDefined()
+    expect(lazyImportMock).not.toHaveBeenCalled()
+  })
+
+  it('DevtoolsCore should call solid primitives when mount is called', async () => {
+    const [DevtoolsCore, _] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const instance = new DevtoolsCore()
+    await instance.mount(document.createElement('div'), 'dark')
+    expect(renderMock).toHaveBeenCalled()
+  })
+
+  it('DevtoolsCore should throw if mount is called twice without unmounting', async () => {
+    const [DevtoolsCore, _] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const instance = new DevtoolsCore()
+    await instance.mount(document.createElement('div'), 'dark')
+    await expect(
+      instance.mount(document.createElement('div'), 'dark'),
+    ).rejects.toThrow('Devtools is already mounted')
+  })
+
+  it('DevtoolsCore should throw if unmount is called before mount', () => {
+    const [DevtoolsCore, _] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const instance = new DevtoolsCore()
+    expect(() => instance.unmount()).toThrow('Devtools is not mounted')
+  })
+
+  it('DevtoolsCore should allow mount after unmount', async () => {
+    const [DevtoolsCore, _] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const instance = new DevtoolsCore()
+    await instance.mount(document.createElement('div'), 'dark')
+    instance.unmount()
+    await expect(
+      instance.mount(document.createElement('div'), 'dark'),
+    ).resolves.not.toThrow()
+  })
+
+  it('NoOpDevtoolsCore should not call any solid primitives when mount is called', async () => {
+    const [_, NoOpDevtoolsCore] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const noOpInstance = new NoOpDevtoolsCore()
+    await noOpInstance.mount(document.createElement('div'), 'dark')
+
+    expect(lazyImportMock).not.toHaveBeenCalled()
+    expect(renderMock).not.toHaveBeenCalled()
+    expect(portalMock).not.toHaveBeenCalled()
+  })
+
+  it('NoOpDevtoolsCore should not throw if mount is called multiple times', async () => {
+    const [_, NoOpDevtoolsCore] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const noOpInstance = new NoOpDevtoolsCore()
+    await noOpInstance.mount(document.createElement('div'), 'dark')
+    await expect(
+      noOpInstance.mount(document.createElement('div'), 'dark'),
+    ).resolves.not.toThrow()
+  })
+
+  it('NoOpDevtoolsCore should not throw if unmount is called before mount', () => {
+    const [_, NoOpDevtoolsCore] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const noOpInstance = new NoOpDevtoolsCore()
+    expect(() => noOpInstance.unmount()).not.toThrow()
+  })
+
+  it('NoOpDevtoolsCore should not throw if unmount is called after mount', async () => {
+    const [_, NoOpDevtoolsCore] = constructCoreClass(() => (
+      <div>Test Component</div>
+    ))
+    const noOpInstance = new NoOpDevtoolsCore()
+    await noOpInstance.mount(document.createElement('div'), 'dark')
+    expect(() => noOpInstance.unmount()).not.toThrow()
+  })
+})