// Use when modifying or visually debugging Nango frontend UI, including packages/webapp, packages/connect-ui, browser interactions, screenshots, and visual regressions. Prefer browser-controlled or headless Playwright checks; use Peekaboo only for native macOS, visible-browser, or Accessibility tree inspection.
Use when adding or editing Nango database migrations - covers migration directory selection, timestamped .cjs naming, matching recent migration style, down migration decisions, and foreign key ON DELETE conventions.
Use when creating new agent skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, discovery optimization, and real examples
Use when adding documentation for a new Nango integration - creates main page, setup guide, and updates docs.json and providers.yaml following established patterns
Use when running the Nango application locally for development and browser testing - covers Docker services, dev commands, service URLs, and troubleshooting startup issues
Use when building the Nango monorepo or verifying TypeScript compilation - covers build commands, project references, common tsc errors, and package dependency order
Use when running tests in the Nango monorepo - knows unit vs integration configs, vitest commands, Docker setup, and common test patterns
| name | ui-visual-debugging |
| description | Use when modifying or visually debugging Nango frontend UI, including packages/webapp, packages/connect-ui, browser interactions, screenshots, and visual regressions. Prefer browser-controlled or headless Playwright checks; use Peekaboo only for native macOS, visible-browser, or Accessibility tree inspection. |
.context/; do not commit them.running-and-testing-locally as the source of truth.| Surface | URL | Common command |
|---|---|---|
| Dashboard webapp | http://localhost:3000 | npm run dev:watch:web |
| API server | http://localhost:3003 | npm run server:dev:watch |
| Connect UI | http://localhost:3009 | npm run dev:watch:web or npm run connect-ui:dev:watch |
For most frontend work, run:
npm run dev:docker
npm run dev:watch
npm run dev:watch:web
npm run dev:watch and npm run dev:watch:web are long-running commands. Keep them in separate sessions and wait for the initial TypeScript build before browser testing.
Start or reuse the relevant local services.
Capture a desktop baseline with a browser-controlled tool. If a Playwright MCP/browser tool is available, use it. Otherwise use headless Playwright without modifying repo dependencies:
npx playwright screenshot --browser=chromium --viewport-size=1512,862 http://localhost:3000 .context/nango-webapp-desktop.png
For Connect UI:
npx playwright screenshot --browser=chromium --viewport-size=1512,862 http://localhost:3009 .context/nango-connect-desktop.png
If Playwright reports that the Chromium executable is missing, install the browser cache without adding repo dependencies:
npx playwright install chromium
Inspect screenshots with view_image, then edit the smallest relevant files.
Verify after edits:
npm run ts-build
For webapp-only visual work, cd packages/webapp && npm run build is also useful. For Connect UI, run npm run connect-ui:build.
Capture fresh desktop screenshots and compare them before finishing.
For clicks, form filling, authentication flows, or multi-step checks, create a temporary Playwright script in .context/, run it, and save screenshots there.
Use stable selectors and visible text where possible. Avoid relying on the user's browser state.
Common flows:
http://localhost:3000.http://localhost:3009.When auth is needed, follow the local credentials and verification-log workflow in running-and-testing-locally.
If server startup fails with a Knex error like The migration directory is corrupt, the following files are missing, the local database has migrations from another branch. Do not reset the user's database without confirmation. For visual validation only, use a temporary database:
docker exec nango-db psql -U nango -d postgres -c "DROP DATABASE IF EXISTS nango_ui_skill_validation WITH (FORCE)"
docker exec nango-db psql -U nango -d postgres -c "CREATE DATABASE nango_ui_skill_validation"
NANGO_DB_NAME=nango_ui_skill_validation npm run dev:watch:web
After stopping the dev server, clean up the temporary database:
docker exec nango-db psql -U nango -d postgres -c "DROP DATABASE IF EXISTS nango_ui_skill_validation WITH (FORCE)"
Use Peekaboo only after checking permissions:
peekaboo permissions status
Required:
Screen Recording (Required): Granted
Accessibility (Required): Granted
Prefer targeted captures by window id. Capturing by app name can hang.
peekaboo list windows --app "Google Chrome" --json
peekaboo image --mode window --window-id <window_id> --retina --path .context/nango-window.png --json-output
peekaboo see --app "Google Chrome" --json-output
Avoid peekaboo open http://... --app "Google Chrome" for routine checks because it creates tabs in the user's existing browser.
.context/.npm run ts-build or the relevant package build was run after frontend changes.