frontend-preview

name	frontend-preview
description	Start a dev server, take screenshots of the rendered frontend, and check for console errors. Use when you need to visually verify frontend changes, test styling, or check for runtime errors after editing frontend code.
allowed-tools	bash read

Frontend Preview

Tools for visually testing frontend changes with your dev server.

Setup

Run once before first use:

cd {baseDir}
npm install

Start Dev Server

node {baseDir}/dev-start.js                          # auto-detect from package.json
node {baseDir}/dev-start.js "npm run dev"             # explicit command
node {baseDir}/dev-start.js "bun dev" http://localhost:3000  # explicit command + URL

Starts the dev server in the background and waits until it's ready (polls HTTP). Prints the URL when ready. Auto-detects the command from package.json scripts.dev if not specified. Auto-detects the URL from server stdout if not specified.

Screenshot

node {baseDir}/dev-screenshot.js                                  # localhost:5173 desktop
node {baseDir}/dev-screenshot.js http://localhost:5173/dashboard   # specific path
node {baseDir}/dev-screenshot.js --mobile                          # mobile viewport (375x812)
node {baseDir}/dev-screenshot.js --tablet                          # tablet viewport (768x1024)
node {baseDir}/dev-screenshot.js --wait=2000                       # extra 2s for animations
node {baseDir}/dev-screenshot.js http://localhost:3000 --mobile --wait=1000

Takes a screenshot using headless Chrome and saves it to a temp file. Prints the file path. You must call read <path> on the output to see the image.

Viewports:

• Desktop: 1280x800 (default)
• Mobile: 375x812 (--mobile)
• Tablet: 768x1024 (--tablet)

Check for Errors

node {baseDir}/dev-errors.js                         # check localhost:5173
node {baseDir}/dev-errors.js http://localhost:3000    # check specific URL

Opens the page in headless Chrome and captures console errors, page crashes, and failed network requests. Use this to check if the frontend has runtime errors.

Stop Dev Server

node {baseDir}/dev-stop.js

Kills the dev server started by dev-start.js.

Typical Workflow

After making frontend changes:

1. Start the dev server (if not already running):

   node {baseDir}/dev-start.js
   

2. Check for errors:

   node {baseDir}/dev-errors.js
   

3. If no errors, take a screenshot to verify visually:

   node {baseDir}/dev-screenshot.js
   

   Then read the screenshot:

   read <the-path-printed-above>
   

4. If testing responsive design, also screenshot mobile:

   node {baseDir}/dev-screenshot.js --mobile
   

   Then read that path too.

5. When done, stop the server:

   node {baseDir}/dev-stop.js
   

Important

• The screenshot tool uses its own headless Chrome — it does NOT require the browser-tools Chrome instance on port 9222.
• dev-start.js saves the server PID to /tmp/pi-dev-server.pid. Only one dev server at a time. Run dev-stop.js before starting a new one.
• If the dev server fails to start, stderr output is printed for debugging.
• Screenshots are saved to /tmp/ and are not cleaned up automatically.