@tanstack/devtools 0.6.24 → 0.8.0

package/src/context/devtools-context.test.ts

@@ -1,6 +1,10 @@
 import { beforeEach, describe, expect, it } from 'vitest'
 import { TANSTACK_DEVTOOLS_STATE } from '../utils/storage'
-import { getStateFromLocalStorage } from './devtools-context'
+import {
+  getExistingStateFromStorage,
+  getStateFromLocalStorage,
+} from './devtools-context'
+import type { TanStackDevtoolsPlugin } from './devtools-context'
 
 describe('getStateFromLocalStorage', () => {
   beforeEach(() => {
@@ -56,4 +60,267 @@ describe('getStateFromLocalStorage', () => {
     const state = getStateFromLocalStorage(undefined)
     expect(state).toEqual(undefined)
   })
+
+  it('should return undefined when no localStorage state exists (allowing defaultOpen to be applied)', () => {
+    // No existing state in localStorage - this allows defaultOpen logic to trigger
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'plugin1',
+        render: () => {},
+        name: 'Plugin 1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        render: () => {},
+        name: 'Plugin 2',
+        defaultOpen: false,
+      },
+      {
+        id: 'plugin3',
+        render: () => {},
+        name: 'Plugin 3',
+        defaultOpen: true,
+      },
+    ]
+
+    // When undefined is returned, getExistingStateFromStorage will fill activePlugins with defaultOpen plugins
+    const state = getStateFromLocalStorage(plugins)
+    expect(state).toEqual(undefined)
+  })
+
+  it('should preserve existing activePlugins from localStorage (defaultOpen should not override)', () => {
+    const mockState = {
+      activePlugins: ['plugin2'],
+      settings: {
+        theme: 'dark',
+      },
+    }
+    localStorage.setItem(TANSTACK_DEVTOOLS_STATE, JSON.stringify(mockState))
+
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'plugin1',
+        render: () => {},
+        name: 'Plugin 1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        render: () => {},
+        name: 'Plugin 2',
+        defaultOpen: false,
+      },
+    ]
+
+    const state = getStateFromLocalStorage(plugins)
+    // Should keep existing activePlugins - defaultOpen logic won't override in getExistingStateFromStorage
+    expect(state?.activePlugins).toEqual(['plugin2'])
+  })
+
+  it('should automatically activate a single plugin when no active plugins exist', () => {
+    // No existing state in localStorage
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'only-plugin',
+        render: () => {},
+        name: 'Only Plugin',
+      },
+    ]
+
+    const state = getStateFromLocalStorage(plugins)
+    // Should return undefined - the single plugin activation happens in getExistingStateFromStorage
+    expect(state).toEqual(undefined)
+  })
+})
+
+describe('getExistingStateFromStorage - integration tests', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('should automatically activate a single plugin when no localStorage state exists', () => {
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'only-plugin',
+        render: () => {},
+        name: 'Only Plugin',
+      },
+    ]
+
+    const state = getExistingStateFromStorage(undefined, plugins)
+    expect(state.state.activePlugins).toEqual(['only-plugin'])
+    expect(state.plugins).toHaveLength(1)
+    expect(state.plugins![0]?.id).toBe('only-plugin')
+  })
+
+  it('should activate plugins with defaultOpen: true when no localStorage state exists', () => {
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'plugin1',
+        render: () => {},
+        name: 'Plugin 1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        render: () => {},
+        name: 'Plugin 2',
+        defaultOpen: false,
+      },
+      {
+        id: 'plugin3',
+        render: () => {},
+        name: 'Plugin 3',
+        defaultOpen: true,
+      },
+    ]
+
+    const state = getExistingStateFromStorage(undefined, plugins)
+    expect(state.state.activePlugins).toEqual(['plugin1', 'plugin3'])
+    expect(state.plugins).toHaveLength(3)
+  })
+
+  it('should limit defaultOpen plugins to MAX_ACTIVE_PLUGINS (3) when 5 have defaultOpen: true', () => {
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'plugin1',
+        render: () => {},
+        name: 'Plugin 1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        render: () => {},
+        name: 'Plugin 2',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin3',
+        render: () => {},
+        name: 'Plugin 3',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin4',
+        render: () => {},
+        name: 'Plugin 4',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin5',
+        render: () => {},
+        name: 'Plugin 5',
+        defaultOpen: true,
+      },
+    ]
+
+    const state = getExistingStateFromStorage(undefined, plugins)
+    // Should only activate first 3 plugins
+    expect(state.state.activePlugins).toEqual(['plugin1', 'plugin2', 'plugin3'])
+    expect(state.state.activePlugins).toHaveLength(3)
+    expect(state.state.activePlugins).not.toContain('plugin4')
+    expect(state.state.activePlugins).not.toContain('plugin5')
+    // All 5 plugins should still be in the plugins array
+    expect(state.plugins).toHaveLength(5)
+  })
+
+  it('should preserve existing activePlugins from localStorage even when plugins have defaultOpen', () => {
+    const mockState = {
+      activePlugins: ['plugin2', 'plugin4'],
+      settings: {
+        theme: 'dark',
+      },
+    }
+    localStorage.setItem(TANSTACK_DEVTOOLS_STATE, JSON.stringify(mockState))
+
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'plugin1',
+        render: () => {},
+        name: 'Plugin 1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        render: () => {},
+        name: 'Plugin 2',
+        defaultOpen: false,
+      },
+      {
+        id: 'plugin3',
+        render: () => {},
+        name: 'Plugin 3',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin4',
+        render: () => {},
+        name: 'Plugin 4',
+        defaultOpen: false,
+      },
+    ]
+
+    const state = getExistingStateFromStorage(undefined, plugins)
+    // Should preserve the localStorage state, not use defaultOpen
+    expect(state.state.activePlugins).toEqual(['plugin2', 'plugin4'])
+    expect(state.plugins).toHaveLength(4)
+  })
+
+  it('should return empty activePlugins when no defaultOpen and multiple plugins', () => {
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'plugin1',
+        render: () => {},
+        name: 'Plugin 1',
+      },
+      {
+        id: 'plugin2',
+        render: () => {},
+        name: 'Plugin 2',
+      },
+      {
+        id: 'plugin3',
+        render: () => {},
+        name: 'Plugin 3',
+      },
+    ]
+
+    const state = getExistingStateFromStorage(undefined, plugins)
+    expect(state.state.activePlugins).toEqual([])
+    expect(state.plugins).toHaveLength(3)
+  })
+
+  it('should handle single plugin with defaultOpen: false by activating it anyway', () => {
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'only-plugin',
+        render: () => {},
+        name: 'Only Plugin',
+        defaultOpen: false,
+      },
+    ]
+
+    const state = getExistingStateFromStorage(undefined, plugins)
+    // Single plugin should be activated regardless of defaultOpen flag
+    expect(state.state.activePlugins).toEqual(['only-plugin'])
+  })
+
+  it('should merge config settings into the returned state', () => {
+    const plugins: Array<TanStackDevtoolsPlugin> = [
+      {
+        id: 'plugin1',
+        render: () => {},
+        name: 'Plugin 1',
+      },
+    ]
+
+    const config = {
+      theme: 'light' as const,
+    }
+
+    const state = getExistingStateFromStorage(config as any, plugins)
+    expect(state.settings.theme).toBe('light')
+    expect(state.state.activePlugins).toEqual(['plugin1'])
+  })
 })

package/src/context/devtools-context.tsx

@@ -1,5 +1,6 @@
 import { createContext, createEffect } from 'solid-js'
 import { createStore } from 'solid-js/store'
+import { getDefaultActivePlugins } from '../utils/get-default-active-plugins'
 import { tryParseJson } from '../utils/sanitize'
 import {
   TANSTACK_DEVTOOLS_SETTINGS,
@@ -49,6 +50,12 @@ export interface TanStackDevtoolsPlugin {
    * If not provided, it will be generated based on the name.
    */
   id?: string
+  /**
+   * Whether the plugin should be open by default when there are no active plugins.
+   * If true, this plugin will be added to activePlugins on initial load when activePlugins is empty.
+   * @default false
+   */
+  defaultOpen?: boolean
   /**
    * Render the plugin UI by using the provided element. This function will be called
    * when the plugin tab is clicked and expected to be mounted.
@@ -127,26 +134,39 @@ export function getStateFromLocalStorage(
   return existingState
 }
 
-const getExistingStateFromStorage = (
+export const getExistingStateFromStorage = (
   config?: TanStackDevtoolsConfig,
   plugins?: Array<TanStackDevtoolsPlugin>,
 ) => {
   const existingState = getStateFromLocalStorage(plugins)
   const settings = getSettings()
 
+  const pluginsWithIds =
+    plugins?.map((plugin, i) => {
+      const id = generatePluginId(plugin, i)
+      return {
+        ...plugin,
+        id,
+      }
+    }) || []
+
+  // If no active plugins exist, add plugins with defaultOpen: true
+  // Or if there's only 1 plugin, activate it automatically
+  let activePlugins = existingState?.activePlugins || []
+
+  const shouldFillWithDefaultOpenPlugins =
+    activePlugins.length === 0 && pluginsWithIds.length > 0
+  if (shouldFillWithDefaultOpenPlugins) {
+    activePlugins = getDefaultActivePlugins(pluginsWithIds)
+  }
+
   const state: DevtoolsStore = {
     ...initialState,
-    plugins:
-      plugins?.map((plugin, i) => {
-        const id = generatePluginId(plugin, i)
-        return {
-          ...plugin,
-          id,
-        }
-      }) || [],
+    plugins: pluginsWithIds,
     state: {
       ...initialState.state,
       ...existingState,
+      activePlugins,
     },
     settings: {
       ...initialState.settings,

package/src/context/devtools-store.ts

@@ -18,6 +18,10 @@ type TriggerPosition =
   | 'middle-left'
   | 'middle-right'
 
+type TriggerProps = {
+  theme: 'light' | 'dark'
+}
+
 export type DevtoolsStore = {
   settings: {
     /**
@@ -61,15 +65,17 @@ export type DevtoolsStore = {
      * @default "dark"
      */
     theme: 'light' | 'dark'
-    /**
-     * The image used for the dev tools trigger
-     * @default TanStackLogo
-     */
-    triggerImage: string
+
     /**
      * Whether the trigger should be completely hidden or not (you can still open with the hotkey)
      */
     triggerHidden?: boolean
+    /**
+     * An optional custom function to render the dev tools trigger component.
+     * If provided, it replaces the default trigger button.
+     * @default undefined
+     */
+    customTrigger?: (el: HTMLElement, props: TriggerProps) => void
   }
   state: {
     activeTab: TabName
@@ -95,8 +101,8 @@ export const initialState: DevtoolsStore = {
       window.matchMedia('(prefers-color-scheme: dark)').matches
         ? 'dark'
         : 'light',
-    triggerImage: '',
     triggerHidden: false,
+    customTrigger: undefined,
   },
   state: {
     activeTab: 'plugins',

package/src/context/use-devtools-context.ts

@@ -1,4 +1,5 @@
 import { createEffect, createMemo, useContext } from 'solid-js'
+import { MAX_ACTIVE_PLUGINS } from '../utils/constants.js'
 import { DevtoolsContext } from './devtools-context.jsx'
 import { useDrawContext } from './draw-context.jsx'
 
@@ -50,7 +51,7 @@ export const usePlugins = () => {
       const updatedPlugins = isActive
         ? prev.state.activePlugins.filter((id) => id !== pluginId)
         : [...prev.state.activePlugins, pluginId]
-      if (updatedPlugins.length > 3) return prev
+      if (updatedPlugins.length > MAX_ACTIVE_PLUGINS) return prev
       return {
         ...prev,
         state: {

package/src/devtools.tsx

@@ -1,7 +1,8 @@
-import { Show, createEffect, createSignal } from 'solid-js'
+import { Show, createEffect, createSignal, onCleanup } from 'solid-js'
 import { createShortcut } from '@solid-primitives/keyboard'
 import { Portal } from 'solid-js/web'
 import { ThemeContextProvider } from '@tanstack/devtools-ui'
+import { devtoolsEventClient } from '@tanstack/devtools-client'
 import {
   useDevtoolsSettings,
   useHeight,
@@ -31,14 +32,36 @@ export default function DevTools() {
   const pip = usePiPWindow()
   let panelRef: HTMLDivElement | undefined = undefined
   const [isResizing, setIsResizing] = createSignal(false)
+
   const toggleOpen = () => {
     if (pip().pipWindow) {
       return
     }
     const open = isOpen()
-    setIsOpen(!open)
-    setPersistOpen(!open)
+    const newState = !open
+    setIsOpen(newState)
+    setPersistOpen(newState)
+
+    // Emit event when user toggles devtools
+    devtoolsEventClient.emit('trigger-toggled', { isOpen: newState })
   }
+
+  // Listen for trigger-toggled events to control devtools
+  createEffect(() => {
+    const unsubscribe = devtoolsEventClient.on('trigger-toggled', (event) => {
+      if (pip().pipWindow) {
+        return
+      }
+      const payload = event.payload as unknown as { isOpen: boolean }
+      const shouldBeOpen = payload.isOpen
+      if (shouldBeOpen !== isOpen()) {
+        setIsOpen(shouldBeOpen)
+        setPersistOpen(shouldBeOpen)
+      }
+    })
+
+    onCleanup(unsubscribe)
+  })
   // Used to resize the panel
   const handleDragStart = (
     panelElement: HTMLDivElement | undefined,
@@ -175,11 +198,7 @@ export default function DevTools() {
                   : true
             }
           >
-            <Trigger
-              isOpen={isOpen}
-              setIsOpen={toggleOpen}
-              image={settings().triggerImage}
-            />
+            <Trigger isOpen={isOpen} setIsOpen={toggleOpen} />
             <MainPanel isResizing={isResizing} isOpen={isOpen}>
               <ContentPanel
                 ref={(ref) => (panelRef = ref)}

package/src/tabs/settings-tab.tsx

@@ -79,13 +79,7 @@ export const SettingsTab = () => {
             }
             checked={settings().triggerHidden}
           />
-          <Input
-            label="Trigger Image"
-            description="Specify the URL of the image to use for the trigger"
-            value={settings().triggerImage}
-            placeholder="Default TanStack Logo"
-            onChange={(value) => setSettings({ triggerImage: value })}
-          />
+
           <Select
             label="Theme"
             description="Choose the theme for the devtools panel"

package/src/utils/constants.ts

@@ -0,0 +1,4 @@
+/**
+ * Maximum number of plugins that can be active simultaneously in the devtools
+ */
+export const MAX_ACTIVE_PLUGINS = 3

package/src/utils/get-default-active-plugins.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it } from 'vitest'
+import { getDefaultActivePlugins } from './get-default-active-plugins'
+import type { PluginWithId } from './get-default-active-plugins'
+
+describe('getDefaultActivePlugins', () => {
+  it('should return empty array when no plugins provided', () => {
+    const result = getDefaultActivePlugins([])
+    expect(result).toEqual([])
+  })
+
+  it('should automatically activate a single plugin', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'only-plugin',
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    expect(result).toEqual(['only-plugin'])
+  })
+
+  it('should automatically activate a single plugin even if defaultOpen is false', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'only-plugin',
+        defaultOpen: false,
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    expect(result).toEqual(['only-plugin'])
+  })
+
+  it('should return empty array when multiple plugins without defaultOpen', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'plugin1',
+      },
+      {
+        id: 'plugin2',
+      },
+      {
+        id: 'plugin3',
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    expect(result).toEqual([])
+  })
+
+  it('should activate plugins with defaultOpen: true', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'plugin1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        defaultOpen: false,
+      },
+      {
+        id: 'plugin3',
+        defaultOpen: true,
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    expect(result).toEqual(['plugin1', 'plugin3'])
+  })
+
+  it('should limit defaultOpen plugins to MAX_ACTIVE_PLUGINS (3)', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'plugin1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin3',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin4',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin5',
+        defaultOpen: true,
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    // Should only return first 3
+    expect(result).toEqual(['plugin1', 'plugin2', 'plugin3'])
+    expect(result.length).toBe(3)
+  })
+
+  it('should activate exactly MAX_ACTIVE_PLUGINS when that many have defaultOpen', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'plugin1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin3',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin4',
+        defaultOpen: false,
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    expect(result).toEqual(['plugin1', 'plugin2', 'plugin3'])
+    expect(result.length).toBe(3)
+  })
+
+  it('should handle mix of defaultOpen true/false/undefined', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'plugin1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        // undefined defaultOpen
+      },
+      {
+        id: 'plugin3',
+        defaultOpen: false,
+      },
+      {
+        id: 'plugin4',
+        defaultOpen: true,
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    // Only plugin1 and plugin4 have defaultOpen: true
+    expect(result).toEqual(['plugin1', 'plugin4'])
+  })
+
+  it('should return single plugin even if it has defaultOpen: true', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'only-plugin',
+        defaultOpen: true,
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    expect(result).toEqual(['only-plugin'])
+  })
+
+  it('should stop at MAX_ACTIVE_PLUGINS limit when 5 plugins have defaultOpen: true', () => {
+    const plugins: Array<PluginWithId> = [
+      {
+        id: 'plugin1',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin2',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin3',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin4',
+        defaultOpen: true,
+      },
+      {
+        id: 'plugin5',
+        defaultOpen: true,
+      },
+    ]
+
+    const result = getDefaultActivePlugins(plugins)
+    // Should only activate the first 3, plugin4 and plugin5 should be ignored
+    expect(result).toEqual(['plugin1', 'plugin2', 'plugin3'])
+    expect(result.length).toBe(3)
+    expect(result).not.toContain('plugin4')
+    expect(result).not.toContain('plugin5')
+  })
+})