vercel-labs / next-browser

★ 201

A skill package that teaches your agent 1 capability — every one documented and browsable below, no GitHub required · by vercel-labs.

Each skill below is one capability this package teaches your agent. Install the whole package, or open a skill to install just that one.

synthesize-transcript

Analyze an agent transcript for generalizable learnings about next-browser CLI usage, then propose SKILL.md updates, feature requests, and bug fixes.

→

@vercel/next-browser

React DevTools and the Next.js dev overlay as shell commands — component trees, props, hooks, PPR shells, errors, network, accessibility snapshots — structured text that agents can parse and act on.

An LLM can't click through a DevTools panel, but it can run next-browser snapshot, read the output, click e3, and keep going. Each command is a stateless one-shot against a long-lived browser daemon, so an agent loop can fire them off without managing browser lifecycle.

Getting started

pnpm add -g @vercel/next-browser   # or npm, yarn
playwright install chromium

Requires Node >= 20.

Commands

Browser lifecycle

Command	Description
`open <url> [--cookies <file>]`	Launch browser and navigate (with optional cookies)
`close`	Close browser and kill daemon

Command	Description
`goto <url>`	Full-page navigation (new document load)
`ssr lock`	Block external scripts on all navigations (SSR-only mode)
`ssr unlock`	Re-enable external scripts
`push [path]`	Client-side navigation (interactive picker if no path)
`back`	Go back in history
`reload`	Reload current page
`restart-server`	Restart the Next.js dev server (clears caches)

Inspection

Command	Description
`tree`	Full React component tree (hierarchy, IDs, keys)
`tree <id>`	Inspect one component (props, hooks, state, source location)
`snapshot`	Accessibility tree with `[ref=eN]` markers on interactive elements
`errors`	Build and runtime errors for the current page
`logs`	Recent dev server log output
`browser-logs`	Browser console output (log, warn, error, info)
`network [idx]`	List network requests, or inspect one (headers, body)
`screenshot [caption] [--full-page]`	Viewport PNG to a temp file (caption shown in Screenshot Log)

Interaction

Command	Description
`click <ref\|text\|selector>`	Click via real pointer events (works with Radix, Headless UI)
`fill <ref\|selector> <value>`	Fill a text input or textarea
`eval [ref] <script>`	Run JS in page context (supports `--file` and stdin)
`viewport [WxH]`	Show or set viewport size

Performance & PPR

Command	Description
`perf [url]`	Core Web Vitals + React hydration timing in one pass
`renders start`	Start recording React re-renders
`renders stop [--json]`	Stop and print per-component render profile
`ppr lock`	Freeze dynamic content to inspect the static shell
`ppr unlock`	Resume dynamic content and print shell analysis

Instrumentation

Command	Description
`instrumentation set <path>`	Inject script before page scripts on every navigation
`instrumentation clear`	Remove instrumentation script

Next.js MCP

Command	Description
`page`	Route segments for the current URL
`project`	Project root and dev server URL
`routes`	All app router routes
`action <id>`	Inspect a server action by ID

Examples

Inspect what's on the page and interact with it:

$ next-browser open http://localhost:3000
$ next-browser snapshot
- navigation "Main"
  - link "Home" [ref=e0]
  - link "Dashboard" [ref=e1]
- main
  - heading "Settings"
  - tablist
    - tab "General" [ref=e2] (selected)
    - tab "Security" [ref=e3]

$ next-browser click e3
clicked

$ next-browser snapshot
- tablist
  - tab "General" [ref=e0]
  - tab "Security" [ref=e1] (selected)

Profile page load performance:

$ next-browser perf http://localhost:3000/dashboard
# Page Load Profile — http://localhost:3000/dashboard

## Core Web Vitals
  TTFB                   42ms
  LCP               1205.3ms (img: /_next/image?url=...)
  CLS                    0.03

## React Hydration — 65.5ms (466.2ms → 531.7ms)
  Hydrated                         65.5ms  (466.2 → 531.7)
  Commit                            2.0ms  (531.7 → 533.7)
  ...

Debug the PPR shell:

$ next-browser ppr lock
locked
$ next-browser goto http://localhost:3000/dashboard
$ next-browser preview "PPR shell — locked"
preview → /var/folders/.../next-browser-screenshot.png
$ next-browser ppr unlock
# PPR Shell Analysis — 131 boundaries: 3 dynamic holes, 128 static

## Quick Reference
| Boundary              | Type      | Primary blocker           | Source              |
| ---                   | ---       | ---                       | ---                 |
| TrackedSuspense       | component | usePathname (client-hook) | tracked-suspense.js |

Inspect a React component:

$ next-browser tree
0 38167 - Root
1 38168 38167 HeadManagerContext.Provider
2 38169 38168 Root
...
224 46375 46374 DeploymentsProvider

$ next-browser tree 46375
path: Root > ... > DeploymentsProvider
DeploymentsProvider #46375
props:
  children: [<Lazy />, <Lazy />, <span />, <Lazy />, <Lazy />]
hooks:
  IsMobile: undefined (1 sub)
  Router: undefined (2 sub)
source: app/.../deployments/_parts/context.tsx:180:10

How it works

A daemon process launches Chromium with the React DevTools extension pre-loaded and listens on a Unix domain socket (named pipe on Windows). CLI commands send JSON-RPC messages to the daemon and print the response. The browser stays open across commands — no per-command startup cost.

License

MIT

Install the whole package (1 skills):

Copy & paste — that's it

npx skills add https://github.com/vercel-labs/next-browser

Or install a single skill: