@solid-devtools/debugger

@solid-devtools/debugger

A runtime package, used to get information and track changes of the Solid's reactivity graph. It's a cornerstone of the rest of the packages.

Installation

If you're not using the main solid-devtools package, and want to use the debugger directly, you can install it as a standalone package:

npm i @solid-devtools/debugger
# or
yarn add @solid-devtools/debugger
# or
pnpm add @solid-devtools/debugger

Warning This package changes extremely often, and is not meant to be used directly. Unless you know what you're doing, use the main package instead.

Module overview

The debugger is split into four submodules:

• . - The main debugger runtime. It exposes hooks like useDebugger, or useLocator which are used to directly interact with the debugger.

  The debugger module doesn't import from solid-js directly, DEV API it provided to it by the ./setup module.

• ./setup - As the name suggests, it's used to setup the debugger. It needs to be imported before the debugger is used, as it provides the DEV API to the debugger.

• ./bundled - A bundled version of the main debugger module. Use this instead of the main module to prevent the debugger from importing from the local solid-js package to keep the development and debugger runtimes separate.

• ./types - Exports all "pure" resources of the debugger, such as types, enums and constants. Use this if you don't want to import the debugger runtime or solid-js by accident.

Import the debugger

The debugger needs to be setup before it can be used. To do that, import the ./setup module before the debugger is used.

import '@solid-devtools/debugger/setup'

import {useDebugger} from '@solid-devtools/debugger/bundled' // or from '@solid-devtools/debugger'

const debug = useDebugger()

Using component locator

Debugger feature inspired by LocatorJS

Locator let's you locate components on the page, and go to their source code in your IDE. All you need to do is configure it by calling setLocatorOptions with some options.

import {useDebugger} from '@solid-devtools/debugger' // or 'solid-devtools/setup'

const debug = useDebugger()
debug.setLocatorOptions()

It will not allow you to highlight hovered components on the page and reveal them in the IDE or the Chrome Extension. (depending of if the extension panel is open or not)

Locator Options

Not passing any options will enable the locator with Alt as the trigger key and no targetIDE selected.

Currently Locator allows for specifying these props:

targetIDE

Choose in which IDE the component source code should be revealed.

Out-of-the-box options: vscode, atom, webstorm and vscode-insiders

setLocatorOptions({
  targetIDE: 'vscode',
})

To be able to go the source code, the code location needs to be inlined during build. This is done by the @solid-devtools/transform package. See how to set it up here.

Target URL Function:

To target custom URLs (e.g. Github files) the targetIDE option accepts an function returning a string or false.

setLocatorOptions({
  targetIDE: ({ filePath, line }) =>
    // will navigate to this link when clicking
    `https://github.com/thetarnav/solid-devtools/blob/main/playgrounds/sandbox/${filePath}#L${line}`,
})

Returning false will prevent calling window.open to navigate to URL, and let you handle the click yourself.

setLocatorOptions({
  targetIDE({ projectPath, filePath, line, column, element }) {
    console.log({ projectPath, filePath, line, column, element })
    return false
  },
})

key

Holding which key should enable the locator overlay? It's "Alt" by default — Alt on Windows, and Option or ⌥ on macOS.

Key options: "Alt", "Control", "Mete", "Shift" or string to be compared with e.key property.

setLocatorOptions({
  key: 'Control',
})

Using the Locator on the page

To activate the Locator module — you have to hold down the Alt/Option key and move your mouse around the page to highlight components and their different HTML Elements.

Clicking the component should take you to the component source code, given that you specified the targetIDE option.

https://user-images.githubusercontent.com/24491503/174093606-a0d80331-021f-4d43-b0bb-e9a4041e1a26.mp4

Supporting custom renderers

By default the debugger assumes you are using "solid-js/web" as jsx renderer and that the rendered elements are HTMLElements.

If you are using a custom renderer—such as Three.js, Pixi.js, or Lightning.js—you need to provide the debugger with an ElementInterface implementation.

import * as debug from '@solid-devtools/debugger/types'
import {setElementInterface} from '@solid-devtools/debugger/setup' // or 'solid-devtools/setup'

/** ElementInterface implementation for DOM Element */
let element_interface: debug.ElementInterface<Element> = {
    isElement:    obj => obj instanceof Element,
    getElementAt: e => e.target as Element | null,
    getName:      el => el.localName,
    getChildren:  el => el.children,
    getParent:    el => el.parentElement,
    getRect:      el => el.getBoundingClientRect(),
    getLocation:  el => {
        let attr = debug.getLocationAttr(el)
        return attr && debug.parseLocationString(attr) || null
    },
}

setElementInterface(element_interface)

Changelog

See CHANGELOG.md.