Configuração para contribuidores do Firecrawl

Execute o Firecrawl localmente ao modificar a API, os workers ou os testes. Este processo instala as dependências de desenvolvimento e inicia os serviços do código-fonte com o harness da API.

Warning

Este é um ambiente de desenvolvimento para contribuidores, não um guia de implantação. Se você quiser executar o Firecrawl em uma infraestrutura sob seu controle sem modificar o produto, use Hospedagem própria do Firecrawl.

Escolha entre desenvolvimento local e auto-hospedagem#

Desenvolva localmente quando precisar de ciclos rápidos de codificação, teste e depuração usando a revisão atual do código-fonte.
Auto-hospede uma versão específica quando quiser uma base estável do Docker Compose na sua própria infraestrutura.
Use o Firecrawl Cloud quando quiser o caminho gerenciado mais rápido, sem precisar operar nenhum dos dois ambientes.

Mantenha esses ambientes separados. O arquivo de desenvolvimento da API em apps/api/.env e o arquivo .env do Compose na raiz são usados por processos diferentes e não são intercambiáveis.

Inicie o ambiente de desenvolvimento do Firecrawl#

Instale os pré-requisitos#

Instale:

Git
Node.js 22
pnpm 11.4.0
Redis
Docker ou Podman para os contêineres do PostgreSQL e do RabbitMQ gerenciados pelo harness da API
Go 1.23 ou mais recente, recompilado pelo harness da API a cada inicialização
Rust, compilado durante o pnpm install para o pacote nativo @mendable/firecrawl-rs

Ative a versão do gerenciador de pacotes usada pela API:

corepack enablecorepack prepare pnpm@11.4.0 --activate

Clone o Firecrawl e instale as dependências#

git clone https://github.com/firecrawl/firecrawl.gitcd firecrawl/apps/apipnpm install

Crie apps/api/.env com a configuração mínima de desenvolvimento sem autenticação:

cat > .env <<'EOF'PORT=3002HOST=0.0.0.0REDIS_URL=redis://localhost:6379REDIS_RATE_LIMIT_URL=redis://localhost:6379USE_DB_AUTHENTICATION=falsePLAYWRIGHT_MICROSERVICE_URL=EOF

Deixe NUQ_DATABASE_URL e NUQ_RABBITMQ_URL não configuradas para que o harness crie contêineres locais do PostgreSQL e RabbitMQ. Configure-as apenas se você for gerenciar essas dependências.

Inicie o Redis e o Firecrawl#

Inicie o Redis em um terminal:

redis-server

Em seguida, inicie o Firecrawl em apps/api, em outro terminal:

pnpm start

O comando start compila a API, inicia os processos da API e do worker e gerencia os contêineres locais da fila. Mantenha esse terminal aberto durante o desenvolvimento.

Verifique um scraping local#

Confirme se o processo da API responde:

curl \  --fail \  --silent \  --show-error \  http://localhost:3002/v0/health/readiness

Resposta esperada:

{"status":"ok"}

Em seguida, teste o fluxo de scraping:

curl \  --fail-with-body \  --silent \  --show-error \  --max-time 75 \  -X POST \  http://localhost:3002/v2/scrape \  -H 'Content-Type: application/json' \  -d '{    "url": "https://example.com",    "formats": ["markdown"],    "timeout": 60000  }'

Uma resposta bem-sucedida inclui success: true, conteúdo em Markdown em data.markdown e um status HTTP em data.metadata.statusCode.

Modifique e teste o Firecrawl#

Mantenha cada alteração focada, inclua um fluxo de sucesso e cobertura relevante para falhas e execute o comando de teste mais específico, mantido no repositório, que comprove o comportamento.

Em apps/api, execute a suíte de snippets da API com suas dependências:

pnpm harness pnpm test:snips

O harness inicia a API, os workers, o PostgreSQL e o RabbitMQ para executar o comando de teste e, em seguida, encerra os processos que iniciou. Use um caminho mais específico do Vitest quando não for necessário executar toda a suíte de snippets.

Para o fluxo de trabalho de contribuição, consulte o CONTRIBUTING.md do repositório antes de abrir um pull request.

Solução de problemas no ambiente de desenvolvimento#

Redis não conecta#

Confirme se o Redis está escutando em localhost:6379 e se ambas as URLs do Redis em apps/api/.env usam esse endereço.

O harness não consegue iniciar o PostgreSQL ou o RabbitMQ#

Inicie o Docker ou o Podman e execute pnpm start novamente. Se você gerencia os serviços por conta própria, defina explicitamente as URLs de conexão em vez de depender de contêineres gerenciados pelo harness.

A porta 3002 já está em uso#

Interrompa o outro processo ou altere PORT em apps/api/.env e, em seguida, use a mesma porta nas solicitações de verificação.

A busca básica funciona, mas a renderização no navegador não#

Deixar PLAYWRIGHT_MICROSERVICE_URL vazio mantém o serviço Playwright separado desativado. Inicie e configure esse serviço apenas quando a alteração que você estiver testando exigir isso.

Próximos passos#

Vai implantar em vez de desenvolver? Consulte Hospedagem própria do Firecrawl.
Ainda está decidindo qual caminho seguir? Compare Código aberto ou Firecrawl Cloud.
Pronto para contribuir? Use o guia de contribuição mantido no repositório.