npm package: @jantimon/next-yak-devtools
Description: Map rendered UI next-yak components to source files. Query elements, inspect styles, and verify changes with persistent browser sessions
Author: jantimon
Latest version: 0.5.0

# 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

```bash
# 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

```bash
# 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](https://github.com/jantimon/next-yak)
- A running development server

## Usage

### Element Targeting

```bash
# 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:

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

### Interactive Commands

```bash
# 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

```bash
# 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:

```bash
# 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:

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

```bash
# 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:

```bash
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](./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:

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

For complex setups, specify paths explicitly:

```bash
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:

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

## Troubleshooting

### Show Browser Window

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

```bash
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](./ARCHITECTURE.md).

## License

MIT