Firecrawl API SOP

Appearance

Contribution Guide ​

Updated Feb 2026

How to contribute to Firecrawl -- report bugs, submit PRs, and improve the project.

Ways to Contribute ​

TypeDescription
Bug ReportsFile issues for unexpected behavior
Feature RequestsPropose new capabilities or improvements
Pull RequestsSubmit code fixes, features, or documentation
DocumentationImprove guides, fix typos, add examples
Community SupportHelp others on Discord or GitHub Discussions

Development Setup ​

Prerequisites ​

ToolVersionNotes
Node.js18+LTS recommended
pnpm9+Package manager (npm install -g pnpm)
Redis7+Job queue backend
PostgreSQL15+Database (Docker image available)
DockerLatestFor running services locally

1. Fork and Clone ​

bash
# Fork the repo on GitHub first, then:
git clone https://github.com/YOUR-USERNAME/firecrawl.git
cd firecrawl

2. Install Dependencies ​

bash
pnpm install

3. Set Up the Database ​

The project includes a Docker image for the database:

bash
cd apps/nuq-postgres
docker compose up -d
cd ../..

4. Configure Environment ​

bash
cp apps/api/.env.example apps/api/.env

Edit apps/api/.env with your local configuration. At minimum:

bash
PORT=3002
HOST=0.0.0.0
USE_DB_AUTHENTICATION=false
BULL_AUTH_KEY=local-dev

For LLM-dependent features (JSON extraction, /extract endpoint), add an OpenAI key:

bash
OPENAI_API_KEY=sk-your-key

5. Start the Development Server ​

bash
pnpm run dev

The API runs on http://localhost:3002.

Running Tests ​

Full Test Suite ​

bash
npm run test:snips

Running Specific Tests ​

bash
# Run tests matching a pattern
npm run test:snips -- --grep "scrape"

# Run tests in a specific file
npm run test:snips -- apps/api/src/__tests__/scrape.test.ts

Testing Your Changes ​

Before submitting a PR, verify:

  1. Existing tests pass: npm run test:snips
  2. Your new code has tests: Add test cases for new features or bug fixes
  3. No type errors: pnpm run typecheck (if available)
  4. Linting passes: pnpm run lint

Submitting a Pull Request ​

1. Create a Branch ​

bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Use descriptive branch names:

  • feature/batch-scrape-webhooks -- new feature
  • fix/redis-connection-timeout -- bug fix
  • docs/self-host-ollama -- documentation
  • refactor/queue-manager -- code improvement

2. Make Your Changes ​

  • Follow existing code style and patterns
  • Add or update tests as needed
  • Update documentation if your change affects public APIs
  • Keep commits focused and atomic

3. Commit with Clear Messages ​

bash
git add .
git commit -m "feat: add webhook retry logic for batch scrape"

Follow Conventional Commits format:

PrefixUsage
feat:New feature
fix:Bug fix
docs:Documentation only
refactor:Code change that neither fixes nor adds
test:Adding or updating tests
chore:Build, CI, tooling changes

4. Push and Open PR ​

bash
git push origin feature/your-feature-name

Then open a Pull Request on GitHub with:

  • Clear title describing the change
  • Description explaining what and why
  • Link to related issue (if applicable)
  • Screenshots or output for visual or behavioral changes
  • Testing steps for reviewers

PR Checklist ​

Before requesting review, confirm:

  • [ ] Tests pass locally (npm run test:snips)
  • [ ] No new warnings or errors
  • [ ] Code follows project conventions
  • [ ] Documentation updated (if applicable)
  • [ ] Commit messages follow Conventional Commits
  • [ ] PR description is complete

Code Style ​

Firecrawl follows standard TypeScript conventions:

  • TypeScript for all API and service code
  • ESLint + Prettier for formatting (run pnpm run lint to check)
  • Functional style preferred where appropriate
  • Explicit types over any -- avoid any unless absolutely necessary
  • Error handling -- use try/catch with meaningful error messages
  • Comments -- explain why, not what (code should be self-documenting)

Project Structure ​

firecrawl/
├── apps/
│   ├── api/              # Main API server
│   │   ├── src/
│   │   │   ├── controllers/   # Route handlers
│   │   │   ├── services/      # Business logic
│   │   │   ├── lib/           # Shared utilities
│   │   │   └── __tests__/     # Test files
│   │   └── .env.example
│   ├── playwright-service/     # Browser rendering (Python)
│   └── playwright-service-ts/  # Browser rendering (TypeScript)
├── sdks/
│   ├── python/           # Python SDK
│   ├── node/             # Node.js SDK
│   ├── go/               # Go SDK
│   └── rust/             # Rust SDK
├── docker-compose.yml
└── examples/
    └── kubernetes/       # K8s deployment examples

Reporting Bugs ​

GitHub Issues ​

File bugs at github.com/mendableai/firecrawl/issues.

Include:

  1. Steps to reproduce -- minimal reproduction case
  2. Expected behavior -- what should happen
  3. Actual behavior -- what actually happens
  4. Environment -- OS, Node version, Docker version, self-hosted or cloud
  5. Logs -- relevant error messages or stack traces
  6. API request -- the exact request that triggers the issue (redact API keys)

Security Issues ​

Do not file security vulnerabilities as public issues. Email help@firecrawl.com directly.

Getting Help ​

ChannelBest For
DiscordQuick questions, community discussion
GitHub IssuesBug reports, feature requests
GitHub DiscussionsDesign proposals, general questions
help@firecrawl.comSecurity issues, private inquiries

Back to: Contributing Overview -->