astro-dev✓ Pass

SKILL.md Content

---
name: astro-dev
description: >-
  Start a Tabler Astro dev server and verify a change in the browser. Use
  whenever a change to `preview/`, `docs/`, `shared/` or `core/` has to be
  seen running — before handing a page or component back — and whenever the
  dev server behaves oddly: stale CSS/JS, assets that vanish, a page that will
  not reload. Covers which server to start on which port, background mode, the
  rule against building while a dev server runs, and the verification loop.
---

# Run and verify the dev servers

Never ask the user to check a page manually. Start the server, look at the page, and show what you found.

## 1. Which server

| Package | Command | Port | Serves |
| --- | --- | --- | --- |
| `@tabler/preview` | `pnpm --dir preview run dev` | 3000 | demo pages (`preview/pages/*.astro`) |
| `@tabler/docs` | `pnpm --dir docs run dev` | 3010 | documentation (`docs/content/**/*.mdx`) |
| `@tabler/screenshots` | `pnpm --dir screenshots run dev` | 3020 | screenshot capture pages |

`preview_start` returns a `tabId` — pass it to every later `navigate` / `read_page` / `computer` call so they act on that tab and not on whatever is fronted. The same entries exist in `.claude/launch.json` (`preview`, `docs`, `screenshots`) — start them with `preview_start` so the browser pane opens on the right port, and use `preview-attach` when a server is already running. `pnpm dev` at the repo root starts everything through turbo; only do that when the change spans packages, because the persistent tasks make the output hard to read.

A `shared/` change shows up in both preview and docs. Verify in the package the user asked about, and open the other one too when the component is used there.

## 2. Full dev vs. astro-only

Each package's `dev` script is `astro dev` plus its asset watchers (`concurrently`), and turbo runs `dev:prepare` first so `tmp-assets/` and `public/` exist:

- **SCSS or `core/` touched → use the full `dev` script.** `astro dev` alone will not rebuild the stylesheets.
- **Only `.astro` / `.mdx` / `shared/lib` touched → `astro dev --background` inside the package is enough** and faster, provided the assets have been built before. Manage it with `astro dev status`, `astro dev logs`, `astro dev stop`; the log file is `.astro/dev.log` in the package. Add `--force` to replace a server that is already running.

## 3. Do not build while a dev server is running

`pnpm build` (or a per-package build) run next to a live dev server fights the watchers: the build's asset copy overwrites what the watcher just wrote into `public/`, and the two file watchers together can exhaust file handles (`EMFILE`). Verify through the running server and HMR instead. If a build is genuinely needed, stop the dev server first.

## 4. The verification loop

1. `preview_start` with the package's config, then open the page (`/badges` in dev; the built file is `/badges.html`).
2. `read_console_messages` — errors first, then warnings.
3. `read_page` or `curl` for structure; assert instead of eyeballing when the page is generated from data:

   ```bash
   curl -s http://localhost:3000/badges | grep -o '<h[1-6]' | sort | uniq -c
   ```

4. `computer` clicks/typing for anything interactive, then read the state back.
5. `resize_window` for responsive or dark-mode work; `colorScheme` for `data-bs-theme`.
6. Screenshot the result for the user when the change is visual.

## 5. When the page looks stale or unstyled

In order:

- **CSS did not change** — the SCSS watcher is not running. Restart with the full `dev` script rather than `astro dev`.
- **Assets 404 after a restart** — `public/preview` (or `docs/public`) was wiped by a build or a `clean`. Run `pnpm --dir <pkg> run dev:prepare`, then start dev again.
- **A `public/` file changed but the browser did not reload** — Astro does not watch `public/`; the `copyAssets` integration reloads the listed dirs, everything else needs a manual refresh.
- **`shared/` change not picked up** — the file is aliased, not watched through `node_modules`; confirm the import uses `@shared`/`@ui`, not a path into `node_modules`.
- Still wrong: `pnpm --dir <pkg> run clean`, then `dev:prepare`, then `dev`.

## 6. Gates before handing work back

Run at the repo root and read the **full** output — a tail hides TypeScript errors:

```bash
pnpm run type-check && pnpm run format:prettier && pnpm run lint
```

`type-check` is `astro check` per package, so it covers `.astro` frontmatter and templates. For a markup refactor that should not change output at all, also run the `html-diff` skill.

## 7. Checklist

- [ ] Right package started, on its own port
- [ ] Full `dev` script when SCSS or `core/` is involved
- [ ] No build started while a dev server was running
- [ ] Page opened, console clean, interaction exercised
- [ ] Screenshot for visual changes
- [ ] Repo-level `type-check` / `format:prettier` / `lint` clean, full output read

License

Declared license: MIT

MIT License

Copyright (c) 2018 tabler

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.