Next-Yak Devtools

A CLI tool that maps rendered UI components to source files in Next.js applications using next-yak.

Why This Exists

When debugging visual issues, you typically:

1. Inspect an element in DevTools
2. See a generated class like Button_PrimaryButton_a3f2c1
3. Search your codebase to find the right file
4. Open multiple files to locate the actual component

This tool eliminates steps 2-4. Point it at your running dev server, query any element, and get the exact source file location plus all computed styles.

Example

# Start a persistent browser session
npx next-yak-devtools launch http://localhost:3000

# Find any element by visible text
npx next-yak-devtools inspect --text "Login"

Output:

selector: button.PrimaryButton_PrimaryButton_FeIQSx
bounds: { x: 549, y: 349, width: 107, height: 46 }
styles:
  padding: [12, 32]
  marginBottom: 24
  backgroundColor: #667eea

resolvedSource:
  filePath: components/PrimaryButton.tsx
  line: 8

You now know exactly where to edit. No manual searching required.

Key Features

• Instant source resolution - Hash-based mapping from CSS classes to source files
• Four targeting methods - Find elements by text, selector, glob pattern, or coordinates
• Interactive state inspection - Hover, click, focus to see actual style changes
• Persistent browser sessions - First command ~2.4s, subsequent commands ~20ms
• Visual regression testing - Screenshot, diff, and locate changed regions
• Cookie management - Test authenticated flows without manual login
• AI-optimized output - Compact TOON format reduces token usage by 30-60%

Installation

# Install Playwright browsers (one-time setup)
npx playwright install chromium

# Start your Next.js dev server
npm run dev

# Use the tool (no installation needed)
npx next-yak-devtools launch http://localhost:3000

Requirements

• Node.js >= 20.0.0
• A Next.js project using next-yak
• A running development server

Usage

Element Targeting

# By visible text (most reliable)
npx next-yak-devtools inspect --text "Login"

# By CSS selector
npx next-yak-devtools inspect --selector ".button"

# By glob pattern (finds multiple elements)
npx next-yak-devtools inspect --glob-text "Feature *"

# By pixel coordinates
npx next-yak-devtools inspect --at 100,200

When multiple elements match, use --index to target a specific instance or --all to inspect all:

npx next-yak-devtools inspect --text "Login" --index 0
npx next-yak-devtools inspect --text "Login" --all

Interactive Commands

# See actual hover state changes
npx next-yak-devtools hover --selector ".card"

# Click and detect navigation or errors
npx next-yak-devtools click --text "Submit"

# Focus and inspect focus styles
npx next-yak-devtools focus --selector "input"

# Measure spacing between elements
npx next-yak-devtools measure --text "Login" --text2 "Sign Up"

Screenshots and Visual Diffs

# Capture current state
npx next-yak-devtools screenshot

# Make code changes, then reload
npx next-yak-devtools reload

# Capture new state
npx next-yak-devtools screenshot

# Compare and generate diff image
npx next-yak-devtools diff screenshot-123.png screenshot-456.png --diff-image

The diff command outputs:

• Percentage of pixels changed
• Severity classification (minor/moderate/major)
• Coordinates of changed regions grouped by proximity
• Visual overlay highlighting changes

Cookie Management

Test authenticated flows without manual login:

# Read cookie values
npx next-yak-devtools read-cookie session

# Set cookies
npx next-yak-devtools write-cookie auth_token xyz789

# Delete cookies (omit value)
npx next-yak-devtools write-cookie auth_token

# Navigate to protected routes
npx next-yak-devtools navigate /dashboard

Source Resolution

Find source files from CSS class names:

npx next-yak-devtools resolve-tsx Button_PrimaryButton_a3f2c1

Returns the exact file path and line number. This uses hash-based resolution for 100% accuracy.

Browser Management

# List active browser sessions
npx next-yak-devtools list

# Get current session info
npx next-yak-devtools info

# Stop a session (auto-cleanup after 30min)
npx next-yak-devtools stop

Run multiple browsers for testing different projects:

npx next-yak-devtools launch http://localhost:3000 --id 0
npx next-yak-devtools launch http://localhost:3001 --id 1
npx next-yak-devtools components --id 1

Common Use Cases

Fix visual bugs - Inspect elements, locate source files, verify changes after editing. The browser persists so reload is instant.

Debug hover states - Use interactive commands to trigger and inspect state changes. Useful when an interaction "feels weird" but you can't identify why from static styles.

Responsive testing - Capture screenshots at multiple viewports (375x667, 768x1024, 1920x1080) to check layouts across devices.

Design system consistency - Use glob patterns to find all instances of a component type and compare their styles.

AI-assisted development - The tool is designed for use with AI coding agents like Claude Code. See CLAUDE.md for integration patterns.

Configuration

Monorepo Support

The tool auto-detects your Next.js config location by searching up from the current directory. This works for most monorepos without configuration:

cd my-monorepo/packages/web
npx next-yak-devtools launch http://localhost:3000

For complex setups, specify paths explicitly:

npx next-yak-devtools launch http://localhost:3000 \
  --config-path packages/web \
  --source-root .

File paths in output are relative to --source-root (defaults to current directory).

Output Format

Default output uses TOON format (compact, AI-optimized). For human-readable JSON:

npx next-yak-devtools inspect --text "Login" --json

Troubleshooting

Show Browser Window

Run with --show-browser to see what the browser is doing:

npx next-yak-devtools launch http://localhost:3000 --show-browser

Useful when elements aren't found or interactions don't work as expected.

Common Issues

"Element not found"

• List available elements: npx next-yak-devtools components
• Try --text instead of --selector
• Ensure page is loaded: npx next-yak-devtools reload

"Wait timeout"

• Element might not exist or be visible
• Increase timeout: --timeout 10000
• Use --show-browser to debug

"Hash verification failed"

• Restart your development server
• Hashes are generated at build time and must match

"Session not responding"

• Check sessions: npx next-yak-devtools list
• Restart: npx next-yak-devtools stop && npx next-yak-devtools launch <url>

How It Works

Next-yak generates CSS class names with file path hashes during build. This tool:

1. Queries the DOM for elements with next-yak class names
2. Extracts the hash from the class name
3. Searches candidate files that import next-yak
4. Computes expected hashes using next-yak's algorithm
5. Returns the file where hashes match

The result is 100% accurate source resolution. Styles are extracted from computed CSS using Playwright, so you see actual rendered values including cascaded, inherited, and dynamic styles.

For architecture details, see ARCHITECTURE.md.

License

MIT