# Development

> Clone, install, build, and run the playground, plus the checks and the docs-site commands.

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](/start/installation/).

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:*`.

   ```sh
   git clone https://github.com/oddcelot/vite-plugin-lit.git
   cd vite-plugin-lit
   pnpm install
   ```

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

   ```sh
   pnpm build
   ```

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

   ```sh
   pnpm dev
   ```

## 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](https://stackblitz.com/github/oddcelot/vite-plugin-lit/tree/main/playground?startScript=stackblitz) or bolt.new straight from the repo URL. That is the quickest way to reproduce a bug report without a local checkout.

## Checks

```sh
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

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

```sh
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.

Pushes to `main` deploy the build to GitHub Pages, served at `vite-plugin-lit.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:

```sh
pnpm run chrome:clean --app http://localhost:5179/
```

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

## Related

[Testing](/contributing/testing/)Unit, e2e, the env vars they honour, and canary runs against lit main.

[Design docs](/contributing/design-docs/)The plans behind the features, in the repository.