How to Search, Scrape, and Crawl the Web from a Convex App with Firecrawl

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

공식 Firecrawl Convex 컴포넌트는 외부 API 호출을 Convex action에 두고, 서명된 웹훅과 반응형 query를 결합해 검색·스크레이핑·내구성 크롤링을 앱의 데이터 흐름으로 통합한다.

📌 핵심 요약

• @firecrawl/firecrawl-convex는 Convex 앱에 search, scrape, map, 내구성 startCrawl 기능과 자체 crawls·pages 테이블 및 HTTP 경로를 추가한다.
• Convex query와 mutation은 네트워크 접근이 없는 결정론적 샌드박스에서 실행되므로 모든 Firecrawl 외부 호출은 action 안에서 수행해야 한다.
• 검색 예시는 Firecrawl search를 limit: 5로 호출해 즉시 결과를 반환하며, 앱의 인증·권한 부여·속도 제한은 이 wrapper action에서 처리한다.
• startCrawl은 { crawlId, jobId }를 즉시 반환하고, Firecrawl 서버가 각 페이지를 처리한 뒤 서명된 웹훅으로 전달하면 mutation이 데이터베이스에 저장하고 반응형 query가 진행 상황을 갱신한다.
• 웹훅 모드에는 공개 URL이 있는 Convex 클라우드 배포가 필요하고 로컬 개발에서는 mode: "poll"을 사용하며, limit: 25와 markdown·screenshot 형식을 적용할 때는 Convex의 1MB 문서 한도를 고려해야 한다.

🧩 주요 포인트

1. 컴포넌트가 별도 namespace의 crawls·pages 테이블을 소유하고 Convex가 변경된 문서를 구독자에게 자동 전파하므로, 웹훅 모드의 실시간 진행 화면에는 클라이언트 polling loop가 필요 없다.
2. 공개 웹훅은 X-Firecrawl-Signature HMAC과 크롤별 토큰을 모두 검증하며, 하나라도 실패하면 행을 쓰기 전에 401로 거부해 외부 입력이 데이터베이스에 직접 유입되는 위험을 제한한다.
3. Firecrawl의 scrapeOptions가 API로 그대로 전달되어 markdown과 screenshot 같은 형식을 선택할 수 있지만, 결과 크기는 Convex의 1MB 문서 한도에 맞춰야 하므로 수집 형식과 범위를 함께 조정해야 한다.

🧠 상세 정리

1. 문서 검색 앱의 목표와 전체 흐름

이 글은 Convex에서 문서 검색 앱을 만들면서 Firecrawl이 웹을 대상으로 수행하는 검색, 크롤링, 스크레이핑의 연결 방식을 설명한다. 사용자가 일반 텍스트 질의를 입력하면 search가 후보 문서 사이트를 찾고, 사용자가 사이트 하나를 선택하면 crawl이 연결을 계속 열어 두지 않은 채 백그라운드에서 해당 사이트를 순회한다. 크롤에 전달한 scrapeOptions는 처리된 각 페이지를 정리된 markdown으로 만들며 screenshot 형식도 요청할 수 있다. 공식 Firecrawl Convex 컴포넌트는 앱과 같은 배포 환경에서 실행되고, 완성된 페이지를 도착하는 순서대로 데이터베이스에 기록한다. 최종 사용자 흐름은 질의 입력, 사이트 선택, 페이지가 채워지는 과정 확인으로 구성되며, 글에서 제시한 완성 앱의 백엔드와 데이터베이스 로직은 100줄 미만이다.

2. Convex의 실행 모델과 반응형 데이터 읽기

Convex는 데이터베이스와 서버 측 TypeScript 함수를 동일한 배포 단위에 두는 백엔드 플랫폼이며, 함수는 convex/ 디렉터리에 작성한다. 클라이언트는 직접 만든 REST 경로 대신 함수 이름을 통해 이 서버 함수를 호출하고, 데이터 접근 역시 해당 함수들로 제한된다. query는 데이터를 읽고 mutation은 트랜잭션 안에서 데이터를 쓰지만, 두 함수 유형 모두 안전한 재실행과 재시도를 위해 네트워크 접근이 차단된 결정론적 샌드박스에서 동작한다. 반면 action은 일반적인 Node 형태의 환경에서 실행되어 외부 API를 호출할 수 있고, 필요한 결과는 mutation을 호출해 데이터베이스에 넘길 수 있다. Convex는 query가 읽은 문서를 추적하고 변경이 발생하면 구독 중인 클라이언트에 새 결과를 전송하므로, 저장된 크롤 진행 상황을 클라이언트가 반복 조회할 필요가 없다.

3. Firecrawl API 키와 Convex 컴포넌트의 역할

Firecrawl API 키는 firecrawl.dev 가입 후 대시보드 홈의 API Key 영역에서 얻을 수 있으며, 무료 등급에는 기능을 시험할 수 있는 크레딧이 제공된다. 공식 클라이언트의 search와 scrape는 IP별 속도 제한을 받는 키 없는 방식으로도 시험할 수 있지만, Convex 컴포넌트는 환경 변수 FIRECRAWL_API_KEY를 필수로 선언하므로 키가 필요하다. Convex 컴포넌트는 테이블, 함수, HTTP 경로를 포함해 자체 백엔드를 함께 설치하는 패키지다. 컴포넌트의 테이블은 애플리케이션 스키마에 포함되지 않아 사용자가 정의하거나 마이그레이션하지 않으며, 애플리케이션은 컴포넌트가 공개한 API를 통해서만 접근한다. 이 컴포넌트는 제3자의 별도 Convex 배포가 아니라 사용자의 Convex 배포 안에서 실행되므로 Firecrawl 호출도 사용자 백엔드에서 발생한다.

4. 컴포넌트 설치와 배포 환경 설정

설치는 npm install @firecrawl/firecrawl-convex로 시작하고, convex/convex.config.ts에서 Firecrawl 설정을 가져와 app.use로 등록한다. 설정에는 필수 FIRECRAWL_API_KEY, 선택 항목으로 선언된 FIRECRAWL_WEBHOOK_SECRET, 그리고 웹훅 경로를 마운트할 httpPrefix가 포함된다. 예시의 httpPrefix는 /firecrawl/이며 실제 전달 주소는 배포 사이트 아래의 /firecrawl/webhook이 된다. app.use가 설치한 테이블과 함수는 애플리케이션 코드가 직접 수정할 수 없는 별도 공간에 배치된다. 환경 변수는 로컬 .env 파일이 아니라 Convex 배포에 직접 설정하며, 글에서는 셸에 값을 내보낸 뒤 npx convex env set으로 API 키와 웹훅 비밀값을 등록하는 방식을 제시한다.

5. 공개 웹훅의 보안 검증

FIRECRAWL_WEBHOOK_SECRET은 설정 스키마상 선택 항목이지만, 글은 공개 웹훅을 보호하기 위해 실제 배포에서는 설정할 것을 권고한다. 계정별 웹훅 비밀값은 Firecrawl 계정 설정의 Advanced 탭에서 확인할 수 있다. 공개 URL을 알게 된 외부 사용자가 임의 요청을 전송하면 데이터베이스에 행이 추가될 수 있으므로, 전달 요청을 저장 전에 검증하는 절차가 필요하다. 비밀값을 설정하면 컴포넌트는 각 요청의 X-Firecrawl-Signature HMAC과 웹훅 등록 시 Firecrawl에 전달한 크롤별 토큰을 각각 확인한다. 두 검사 중 하나라도 실패한 요청은 mutation이 행을 기록하기 전에 401 응답으로 거부된다.

6. Action을 이용한 웹 검색과 React 연동

첫 검색 함수는 convex/web.ts에 action으로 작성하며, FirecrawlClient를 components.firecrawl에 연결해 타입이 지정된 컴포넌트 API를 만든다. action은 문자열 query를 Convex validator로 검증하고, handler에서 firecrawl.search를 limit: 5로 호출해 결과를 바로 반환한다. Firecrawl 옵션은 v2 API로 변경 없이 전달되므로 각 옵션의 의미는 Firecrawl 문서를 기준으로 확인할 수 있다. 이 wrapper action은 컴포넌트가 볼 수 없는 ctx.auth를 활용하는 인증·권한 부여와 앱 수준의 속도 제한을 배치할 위치이기도 하다. React 클라이언트에서는 useAction(api.web.search)로 호출 함수를 만들고, 제출 시 검색 상태를 바꾼 뒤 반환된 결과를 상태에 저장한다. 오류는 ConvexError의 code, status, path, message 정보로 구분할 수 있으며, 글은 크레딧 부족 상태 402와 속도 제한 상태 429를 처리할 수 있도록 try/catch를 둘 필요가 있다고 지적한다.

7. 웹훅 기반 크롤과 로컬 polling 대안

Convex action은 500페이지 크롤처럼 오래 걸리는 작업 동안 연결을 유지하도록 설계된 환경이 아니므로, 컴포넌트는 action 안에서 전체 크롤이 끝나기를 기다리지 않는다. action은 Firecrawl 서버에서 작업을 시작한 뒤 즉시 종료하고, Firecrawl은 각 페이지 처리가 끝날 때마다 Convex 배포의 HTTP endpoint로 결과를 보낸다. endpoint는 서명을 검증한 다음 mutation을 호출해 페이지 행을 기록하며, 이 데이터 변경이 반응형 query를 통해 사용자 화면에 전달된다. 기본 웹훅 모드는 Firecrawl 서버가 접근할 수 있는 공개 URL을 요구하므로 HTTP Actions URL이 제공되는 Convex 클라우드 배포가 필요하다. 공개 URL이 없는 로컬 배포에서는 startCrawl에 mode: "poll"을 넘길 수 있고, 이 경우 컴포넌트가 Firecrawl 상태 endpoint를 조회하면서 간격을 최대 30초까지 늘린다.

8. 내구성 크롤의 시작과 수집 범위 설정

내구성 크롤은 시작한 프로세스가 아니라 데이터베이스에 상태를 보관하는 방식으로, action은 크롤 정보를 기록하고 crawlId를 받은 뒤 1~2초 안에 종료된다. startCrawl은 호출자에게 { crawlId, jobId }를 즉시 반환하며, 브라우저 탭을 닫거나 앱을 다시 배포해도 Firecrawl 쪽의 작업과 페이지별 전달은 계속된다. 예시 action은 입력 URL의 첫 번째 경로 구간을 추출해 includePaths를 만들고, 선택한 문서 경로에서 벗어나 마케팅 사이트나 외부 소셜 링크 쪽으로 크롤이 확장되지 않도록 범위를 제한한다. 크롤 옵션의 limit: 25는 최대 처리 페이지 수를 제한하고, formats: ["markdown"]과 onlyMainContent: true는 각 페이지에서 markdown 형식의 주요 콘텐츠를 요청한다. scrapeOptions는 Firecrawl API로 그대로 전달되므로 markdown과 screenshot을 함께 요청할 수도 있지만, 저장되는 각 결과는 Convex의 1MB 문서 한도를 넘지 않도록 구성해야 한다.

🧾 핵심 주장 / 시사점

• 내구성 크롤은 장시간 작업을 Convex action의 수명에서 분리하고 상태를 데이터베이스와 Firecrawl 서버에 남겨, 탭 종료·연결 단절·재배포가 진행 상태 손실로 이어지지 않게 한다.
• 페이지별 웹훅 저장과 Convex의 반응형 query를 결합하면 크롤 진행 표시가 별도의 클라이언트 polling loop가 아니라 일반 데이터 구독 문제로 바뀐다.
• Firecrawl 컴포넌트가 외부 API와 저장 구조를 캡슐화하더라도, 앱별 인증·권한 부여·속도 제한과 공개 웹훅 검증은 각각 wrapper action과 비밀값 설정에서 명시적으로 처리해야 한다.

✅ 액션 아이템

• Convex의 모든 Firecrawl 외부 호출은 action에 배치하고, query와 mutation은 데이터 읽기·쓰기에 한정.
• 웹훅 모드에는 공개 URL이 있는 Convex 클라우드 배포와 X-Firecrawl-Signature HMAC·크롤별 토큰 검증을 적용하고, 로컬 개발에는 mode: "poll" 사용.
• Firecrawl의 limit: 25 및 markdown·screenshot 설정을 Convex의 1MB 문서 한도 안에서 조정.

❓ 열린 질문

• Convex 앱은 공개 URL이 있는 클라우드 웹훅 모드와 mode: "poll"을 쓰는 로컬 모드 중 어느 환경에서 실행되는가?
• Firecrawl search의 limit: 5와 startCrawl의 limit: 25가 필요한 검색·크롤링 범위에 맞는가?
• markdown과 screenshot 결과가 Convex의 1MB 문서 한도 안에 들어오는가?