{"id":51266176,"url":"https://github.com/alectrocute/firecrawl-run-inspector","last_synced_at":"2026-06-29T15:30:56.355Z","repository":{"id":367199141,"uuid":"1279708471","full_name":"alectrocute/firecrawl-run-inspector","owner":"alectrocute","description":"See exactly what happened inside every Firecrawl Scrape run","archived":false,"fork":false,"pushed_at":"2026-06-25T00:57:52.000Z","size":722,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T02:11:39.711Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://firecrawl-run-inspector.alectrocute.workers.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alectrocute.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-25T00:24:13.000Z","updated_at":"2026-06-25T00:57:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alectrocute/firecrawl-run-inspector","commit_stats":null,"previous_names":["alectrocute/firecrawl-run-inspector"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/alectrocute/firecrawl-run-inspector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alectrocute%2Ffirecrawl-run-inspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alectrocute%2Ffirecrawl-run-inspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alectrocute%2Ffirecrawl-run-inspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alectrocute%2Ffirecrawl-run-inspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alectrocute","download_url":"https://codeload.github.com/alectrocute/firecrawl-run-inspector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alectrocute%2Ffirecrawl-run-inspector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34933498,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-29T15:30:55.675Z","updated_at":"2026-06-29T15:30:56.350Z","avatar_url":"https://github.com/alectrocute.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🔥 Firecrawl Run Inspector\n\n### See exactly what happened inside every Firecrawl Scrape run.\n\nA step-by-step timeline with screenshots, timing, and plain-English failure attribution so when a multi-step scrape breaks, you know which step, why and what the page looked like at that moment.\n\n[![Built with Firecrawl](https://img.shields.io/badge/Built%20with-Firecrawl-FF7A00?style=for-the-badge)](https://www.firecrawl.dev)\n[![Nuxt 4](https://img.shields.io/badge/Nuxt-4-00DC82?style=for-the-badge\u0026logo=nuxtdotjs\u0026logoColor=white)](https://nuxt.com)\n[![Vue 3](https://img.shields.io/badge/Vue-3-42b883?style=for-the-badge\u0026logo=vuedotjs\u0026logoColor=white)](https://vuejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](#license)\n\n![Firecrawl Run Inspector — a failed run, attributed to step 3 with screenshots and a plain-English explanation](./assets/screenshot.png)\n\n\u003c/div\u003e\n\n---\n\n## Why?\n\nProduction scraping workflows are opaque. When a 14-step action sequence fails, you get a single\n`SCRAPE_FAILED` and no context. Which step broke? Was it a bad selector, or did the page change?\nWhat did the page even look like when it gave up?\n\nRun Inspector is the observability layer for [Firecrawl](https://www.firecrawl.dev) Actions.\nPaste a URL and an actions array, hit run, and it instruments the execution with per-step\nscreenshots and timing — then hands back a timeline with failure attribution and a clear\nexplanation of what went wrong.\n\nIt's open source so you can run it locally, drop it into your own internal tools or use it as a\nreference for building on the Firecrawl SDK.\n\n## Features\n\n- **Failure attribution** — \"Hit a snag at step 3 of 4,\" not a generic error. Every step is\n  mapped back to *your* original action, never the instrumented one.\n- **Per-step screenshots** — see the page state before and after each action, with a click-to-zoom\n  lightbox. Captured from a single browser session.\n- **Error classification** — selector-not-found, wait/navigation/API timeouts, rate limits,\n  CAPTCHA/blocks, empty results — each with tailored, human advice on how to fix it.\n- **Last-good screenshot** — on failure, the page is replayed up to (but not including) the\n  failing step so you can see exactly what it looked like before things broke.\n- **Rate-limit aware** — automatic exponential backoff on 429s, with the retry timeline surfaced\n  in the UI.\n- **Honest warnings** — screenshot-count mismatches, empty sequences, and degraded (network-drop)\n  results are flagged instead of silently swallowed.\n- **Bring your own key** — paste a Firecrawl API key (kept in your browser's local storage, sent\n  per-request) or configure one server-side. The key never gets baked into the client bundle.\n- **Built for speed** — JSON editor with `⌘/Ctrl + Enter` to run, inline validation, three ready\n  presets, and cancelable runs.\n\n## Quick start\n\n**Prerequisites:** Node.js 20+ and a Firecrawl API key ([grab one free](https://www.firecrawl.dev/app/api-keys)).\n\n```bash\n# 1. Install dependencies\nnpm install\n\n# 2. (Optional) configure a server-side API key\necho \"FIRECRAWL_API_KEY=fc-your-key-here\" \u003e .env\n\n# 3. Start the dev server\nnpm run dev\n```\n\nOpen **http://localhost:3000**, paste your key (or rely on the `.env` one), pick a preset, and hit\n**Run sequence**.\n\n\u003e **No `.env`? No problem.** You can paste your API key directly in the UI — it's stored locally in\n\u003e your browser and sent with each request, never persisted server-side.\n\n## Configuration\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `FIRECRAWL_API_KEY` | Optional | Server-side fallback key. A key entered in the UI (sent via the `x-firecrawl-api-key` header) always takes precedence. |\n| `FIRECRAWL_API_URL` | Optional | Firecrawl API base URL. Defaults to `https://api.firecrawl.dev`. |\n\n## How it works\n\nFirecrawl runs an entire actions array in one call and, on a mid-sequence failure, throws for the\n*whole* request. Run Inspector turns that into a per-step story with two small tricks:\n\n**1. Single-call instrumentation.** Before sending, it weaves a `screenshot` action between each of\nyour steps:\n\n```\n[ ss₀, action₀, ss₁, action₁, ss₂, …, actionₙ₋₁, ssₙ ]\n```\n\nOne scrape call, one browser session, one bill — and the ordered `screenshots[]` map cleanly back to\neach of your steps.\n\n**2. Failure attribution + last-good replay.** The catch: those step screenshots only come back when\nthe run *succeeds*. A mid-sequence failure throws for the **whole** call and returns nothing — no\npartial results — so the one moment you most want to see is the one Firecrawl won't give you. So when\nit reports `Error in action N`, we map `N` back to your original step, classify the error, then re-run\njust the *prefix* (`actions[0…N-1]`) in the **same browser profile** to recover a screenshot of the\npage right before it broke. Replaying in the same profile preserves the cookies, login, and\nnavigation state the failing step actually saw — a fresh session could land on a different page and\nshow you a misleading screenshot.\n\n### Supported actions\n\n`wait` · `click` · `write` · `press` · `scroll` · `screenshot` · `scrape` · `executeJavascript`\n\n## Project structure\n\n```\napp/\n├── app/                       # Nuxt app source (srcDir)\n│   ├── components/            # ActionEditor, ActionTimeline, FailureDetail, StepCard, …\n│   ├── composables/           # useRunInspector, useActionForm, useApiKey, usePresets\n│   ├── pages/index.vue        # the single-page workbench\n│   ├── types/                 # shared TypeScript contract (single source of truth)\n│   └── utils/                 # $t/$tm helpers, formatting, action labels\n├── server/\n│   ├── api/run.post.ts        # validate → instrument → scrape → build timeline\n│   ├── api/verify.get.ts      # error-format self-check status\n│   └── utils/                 # apiKey, errors, instrument, retry, verification\n├── shared/utils/i18n.ts       # framework-agnostic translator (used by app + server)\n├── locales/en.json            # all user-facing copy lives here\n└── tests/ui.spec.ts           # Playwright end-to-end suite\n```\n\n## Tech stack\n\n[Nuxt 4](https://nuxt.com) · [Vue 3](https://vuejs.org) · [Nitro](https://nitro.build) ·\n[Tailwind CSS](https://tailwindcss.com) · [Zod](https://zod.dev) ·\nFirecrawl HTTP API ·\n[Playwright](https://playwright.dev) · TypeScript\n\nFirecrawl calls run **server-side only**, so your API key never reaches the browser bundle. All\ncopy is centralized in `locales/en.json` and resolved through a tiny shared `$t()` helper.\n\n## Testing\n\nThe UI is covered by a Playwright end-to-end suite (page structure, presets, validation, success /\nfailure / empty / timeout / rate-limited runs, warnings, the screenshot lightbox, and API-key\nhandling).\n\n```bash\nnpx playwright install   # first run only — fetches the browser\nnpx playwright test\n```\n\n## Production\n\n```bash\nnpm run build     # build for production\nnpm run preview   # preview the production build locally\n```\n\nRun Inspector is a standard Nuxt app and deploys anywhere Nitro runs — Vercel, Netlify, Cloudflare,\na Node server, or a container. See the [Nuxt deployment docs](https://nuxt.com/docs/getting-started/deployment).\n\n## Contributing\n\nIssues and PRs are welcome. This repo is also meant to be read — clone it, poke around\n`server/api/run.post.ts`, and use it as a starting point for your own Firecrawl tooling.\n\n## License\n\nReleased under the **MIT License** — use it, fork it, ship it.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003csub\u003eRun Inspector is a community/demo utility for working with Firecrawl Actions.\u003c/sub\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falectrocute%2Ffirecrawl-run-inspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falectrocute%2Ffirecrawl-run-inspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falectrocute%2Ffirecrawl-run-inspector/lists"}