Expo Router Step-by-Step Screenshots

Generate step-by-step visual guides for React Native Web apps using Expo Router. This skill automates browser-based screenshot capture, WebP conversion, and API upload to create comprehensive walkthrough documentation.

When to use

Use this skill when:

Creating visual walkthroughs for Expo Router apps (React Native (UI screenshot only works to react native web))
Documenting app features with step-by-step screenshots
Generating browser-based screenshots for Expo Router routes
Any task requiring automated screenshot capture from an Expo Web app

Do not use this skill for:

Native mobile screenshots (use device-specific tools)
Non-Expo Router projects (skill requires app/ directory structure)
Static image generation without browser automation

Instructions

Phase 0: Context Read (mandatory before planning)

Before generating any plan, examine the project structure for architecture and context files. These files contain conventions for commands, environment variables, routing patterns, and feature flags.

Required context files (priority order):

agents.md - Project agent rules and conventions
cloud.md - Cloud infrastructure and deployment conventions
architecture.md - Architecture patterns and routing structure

Conflict resolution: If multiple files exist with conflicting guidance, use priority: agents.md > cloud.md > architecture.md.

Output in plan:

List which architecture files were found and used
Summarize only conventions affecting execution (keep it short)

Phase 1: Planning (must happen first, no execution allowed)

Absolute constraints:

Never start the server, open a browser, navigate, take screenshots, or upload anything during planning
Always verify Expo Router project exists (app/ directory must be present)
If app/ directory is missing, refuse execution and provide instructions

Route inference:

Infer routes from the app/ file structure (e.g., app/index.tsx → /, app/settings.tsx → /settings)
Do not hardcode routes in the skill
Do not ask user for routes by default
If request is ambiguous, choose most likely route/flow based on Expo Router structure and state clearly that it was inferred

Plan structure for each step:

Step number - Sequential numbering
Title - Concise step name
Objective - What this step accomplishes
Actions - Specific navigation/interactions to perform
Success criteria - How to verify step completion
Screenshot note - "A screenshot will be captured and uploaded at the end of this step during execution"

Required approval gate: After presenting the plan, require explicit user approval with: "Reply with 'approved' to execute."

Output format: Markdown with plan structure above

Phase 2: Execution (only after explicit approval)

Gating rule: Execute ONLY if user explicitly approves (e.g., "approved"). Otherwise stay in planning mode.

Execution pipeline:

Start the React Native Web app locally
- Use project's scripts/conventions from context files or package.json scripts
- Common commands: npm run web, expo start --web, yarn web
- Use port detection to avoid conflicts
Wait until server is ready
- Check for port to be open
- Wait for "ready" or "listening" log message
- Timeout after 60 seconds if not ready
Launch Puppeteer
- Tool: puppeteer
- Browser: chromium
- Default viewport: 1280x720
- Ensure consistent viewport across all screenshots
Run steps sequentially
- For each step:
  - Navigate to the route
  - Perform interactions (clicks, form fills, etc.)
  - Wait for UI to settle (prefer waitForSelector or networkidle)
  - Capture screenshot
  - Convert to WebP with quality stepdown (80, 70, 60, 50, 40) until < 5MB
  - Upload to API with retry logic
  - Collect {url, filename, expiresAt}
Cleanup
- Close browser
- Stop server process
- Return complete step-by-step Markdown guide with URLs

Wait strategy (to avoid flaky screenshots):

Preferred: waitForSelector with stable selectors
Alternative: networkidle for page-level stability
Use route-level waits when possible
Add small delays (500-1000ms) for animations

Screenshot rules (absolute):

At least one screenshot MUST be captured and uploaded at the end of every step
Screenshots must represent the final state after step completes
More than one screenshot per step is optional, but never zero

Error handling:

Upload failures:
- Retry up to 2 times with quality stepdown
- If still failing, mark step as ERROR with short reason
- Continue to next step if it still makes sense
Server start failures:
- Stop execution immediately
- Return concise error summary and relevant logs
- Do not proceed with browser automation

Hard Requirements

Expo Router requirement:

Must use Expo Router (app/ directory structure)
If app/ directory missing: refuse execution with explanation

Approval requirement:

Must not execute before explicit user approval

Screenshot requirement:

Every step must have at least one screenshot

Upload API specification:

Base URL: https://api.freesupabase.shop
Endpoint: /api/upload
Method: POST
Content-Type: multipart/form-data
File field: file
Format: image/webp
Max size: 5MB (5242880 bytes)
URL expiry: 30 minutes
Expected response: { url: string, filename: string, expiresAt: string (ISO-8601) }

WebP encoding:

Default quality: 80
Max size: 5MB
Quality stepdown: [80, 70, 60, 50, 40]
If file > 5MB after quality 40, fail and report error

Browser automation:

Tool: puppeteer
Browser: chromium
Default viewport: { width: 1280, height: 720 }

Bundled Resources

scripts/take-screenshot.sh

Bash script for screenshot capture and upload. Handles:

Launching Puppeteer/Chromium
Capturing screenshot with specified viewport
Converting to WebP with quality stepdown
Uploading to API with retry logic
Returning URL, filename, and expiresAt

Usage:

scripts/take-screenshot.sh <url> <output-path> [selector-to-wait-for]

Response Templates

Planning Response Template

# Plan: <Feature Name>

## Context used
- Architecture files found: <list or 'none'>
- Key conventions applied: <short bullet list>

## Steps
1. **<Step title>**
   - Objective: ...
   - Actions: ...
   - Success criteria: ...
   - Screenshot: Will be captured & uploaded after this step (execution phase).

Reply with **'approved'** to execute.

Execution Response Template

# Feature: <Feature Name>

## Step 1: <Step title>
- Objective: ...
- Actions executed: ...
- Result: OK/ERROR (short description)
- Screenshot: ![Step 1](<url>)
- Expires at: <expiresAt>

## Step 2: ...
...

## Summary
- What was validated: ...
- Notes: inferred routes, known flakiness, limitations, etc.

expo-router-screenshots