Skip to content
Lit DevTools

Development

Set up a local checkout of the plugin, build it, and run the playground against it. This page is for changing the plugin itself; to use it in your own project, start at Install the plugin.

The repository needs Node 26 and pnpm 12. corepack enable picks up the pinned version. The published package itself runs on Node 20 or newer.

  1. Clone and install. The repo is one pnpm workspace: the plugin package at the root, plus playground/ and docs/ linked against it with workspace:*.

    Terminal window
    git clone https://github.com/oddcelot/lit-devtools.git
    cd lit-devtools
    pnpm install

  2. Build the plugin. This runs tsc and the panel build, into ./lib, ./panel, and ./index.js:

    Terminal window
    pnpm build

  3. Run the playground. It builds the plugin first, then serves http://localhost:5179:

    Terminal window
    pnpm dev

The playground

Section titled “The playground”

A manually inspectable fixture app, and the source for the e2e fixtures. Edit the templates, styles, and labels in playground/src/*.ts and watch counts, focus, and DOM identity survive. The page HUD counts HMR updates, and every component shows a renders: n badge. It runs on Vite 8 and always uses the local plugin build through the workspace link.

It is self-contained enough to open on StackBlitz or bolt.new straight from the repo URL. That is the quickest way to reproduce a bug report without a local checkout.

Checks

Section titled “Checks”
Terminal window
pnpm exec vp check   # format + lint + type check (oxfmt, oxlint, tsgolint)
pnpm format:check    # formatting only
pnpm run test:unit   # node-only unit tests

vp check is what CI runs. prepublishOnly runs it too, alongside the unit tests and a build.

The documentation site

Section titled “The documentation site”

This site lives in docs/ as its own workspace package, built with Astro and Starlight:

Terminal window
pnpm run docs:dev     # serve at http://localhost:4321/
pnpm run docs:build   # sync the changelog, build, check redirects, write .md copies
pnpm run docs:shots   # regenerate the screenshots

pnpm run docs:build is the gate. It syncs CHANGELOG.md into the reference section, fails on a dead internal link or anchor, and asserts every redirect target exists. Run it before you open a docs PR.

A section about a feature from a release after 0.3.0 carries a badge naming that release, on the line under its heading:

import Since from '../../../components/Since.astro';


## Pause on an update or a change


<Since v="0.19.0" />

It reads “New in” for the latest release and “Added in” before that, and links to the release’s changelog page. The version must have a section in CHANGELOG.md, or the build fails. Keep it out of the heading itself, where it would become part of the anchor.

Pushes to main deploy the build to GitHub Pages, served at lit-devtools.oddsquad.dev through Cloudflare. A Worker on that route, in docs/worker/, adds the Link headers Pages can’t set and answers Accept: text/markdown with the page’s index.md. It doesn’t deploy with the site; after changing it, run pnpm run worker:deploy in docs/ with Wrangler logged in.

Screenshots or recordings that need the real browser window, such as Chrome’s own DevTools or a screen capture for a demo, start Chrome through pnpm run chrome:clean. It opens installed Google Chrome on a throwaway profile with an English UI and none of the usual on-screen noise: no translate offer, automation banner, sign-in or password prompt, first-run or restore page. Add --app for a window with no tabs or address bar, or --kiosk for full screen:

Terminal window
pnpm run chrome:clean --app http://localhost:5179/

Scripts import launchCleanChrome() from scripts/chrome-profile.mjs, which returns the Playwright page to drive.

Section titled “Related”
TestingUnit, e2e, the env vars they honour, and canary runs against lit main.
Design docsThe plans behind the features, in the repository.