frontend-debugging
使用现代工具和最佳实践调试 Next.js、React 和 Playwright 应用程序的专业指导。
📖 中文导读:使用现代工具和最佳实践调试 Next.js、React 和 Playwright 应用程序的专业指导。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: frontend-debugging description: Expert guidance for debugging Next.js, React, and Playwright applications with modern tools and best practices.
Frontend Debugging
Use this skill when you need to troubleshoot UI issues, state management bugs, or test failures in a Next.js/React environment.
VSCode Simple Browser (Recommended)
The Simple Browser is a lightweight embedded browser in VSCode, ideal for quick visual debugging without leaving the editor.
How to Use
- Start Dev Server: Run
bun devto start your app (typically onhttp://localhost:5001). - Open Simple Browser: Use the
open_simple_browsertool with the URL to preview directly in VSCode. - Side-by-Side View: Drag the Simple Browser tab to view code and preview simultaneously.
Agent Workflow
When debugging UI issues:
1. Start the dev server: bun dev (background process)
2. Open Simple Browser: open_simple_browser with http://localhost:5001
3. Navigate to the problematic route: open_simple_browser with http://localhost:5001/route
4. Read the relevant component code
5. Make changes and observe the preview (auto-refreshes with Fast Refresh)
Benefits
- No Context Switching: Stay in VSCode while visually inspecting the app.
- Fast Iteration: Changes trigger Fast Refresh; see results instantly.
- Route Testing: Quickly navigate to any route by changing the URL.
- Screenshot Capability: Use Playwright MCP tools to capture screenshots if deeper inspection is needed.
Limitations
- No DevTools access (use external browser for DOM/Network inspection).
- Basic rendering only (no browser extensions like React DevTools).
- Use external browser for complex debugging scenarios.
Next.js Debugging
Server-Side Debugging
- Inspect Flag: Run
bun dev --inspectto enable the Node.js inspector. - VS Code: Use the "Next.js: debug server-side" configuration in
launch.json. - Chrome: Navigate to
chrome://inspectto attach to the server process.
Client-Side Debugging
- Browser DevTools: Use the Sources tab (Chrome) or Debugger tab (Firefox).
- React DevTools: Use the Components and Profiler tabs to inspect state and props.
- Breakpoints: Use
debugger;statements in code or set breakpoints in DevTools.
Playwright Debugging
Interactive Debugging
- Inspector: Run
npx playwright test --debugto open the Playwright Inspector. - Manual Pause: Insert
await page.pause()in your test to stop execution and inspect the page. - Headed Mode: Use
--headedto see the browser during execution.
Post-Mortem Analysis
- Trace Viewer: Record traces with
trace: 'on'in config and view them withnpx playwright show-trace {path-to-trace}. - Actionability Logs: Check the logs in the Inspector to see why an action (like a click) failed.
Playwright MCP for Visual Debugging
When Simple Browser isn't enough, use Playwright MCP tools for deeper inspection:
- Snapshot:
mcp_playwright_mc_browser_snapshotcaptures the accessibility tree. - Screenshot:
mcp_playwright_mc_browser_take_screenshotcaptures a visual screenshot. - Navigate:
mcp_playwright_mc_browser_navigateopens a URL in a full Playwright browser. - Click/Type: Interact with elements programmatically for automated debugging.
Best Practices
- Start with Simple Browser: For quick visual checks, use Simple Browser first.
- Escalate to External Browser: When you need DevTools, open in Chrome/Firefox.
- Use Playwright MCP for Automation: For repetitive debugging or screenshots.
- Source Maps: Ensure
productionBrowserSourceMaps: trueis set innext.config.tsif debugging production builds. - Console Logging: Use
console.logsparingly; prefer breakpoints for complex state inspection. - Network Tab: Monitor API calls and responses in external browser DevTools.
- Fast Refresh: Be aware that Fast Refresh might clear local state; use persistent storage or URL state for critical data.