docs: document Playwright browser plugin extensions by shixi-li · Pull Request #2089 · apify/crawlee-python · GitHub
Skip to content

docs: document Playwright browser plugin extensions - #2089

Merged
vdusek merged 1 commit into
apify:masterfrom
shixi-li:docs/browser-plugin-extensions
Jul 27, 2026
Merged

vdusek merged 1 commit into
apify:masterfrom
shixi-li:docs/browser-plugin-extensions

Conversation

@shixi-li

Copy link
Copy Markdown
Contributor

Description

The Playwright crawler guide linked a custom implementation without explaining the extension contract, making it unclear when configuration is sufficient and when a different launch API needs a plugin subclass.

  • distinguish built-in configuration from custom browser launch integrations
  • document the new_browser() controller contract and BrowserPool lifecycle responsibilities
  • call out context, incognito, page-limit, fingerprint, header, and user-data behavior that custom integrations must preserve or replace
  • link the existing Camoufox implementation as a complete example

Issues

Refs #1936

Testing

  • uv run --locked poe lint
  • cd website && corepack pnpm@11.15.1 format:check
  • cd website && corepack pnpm@11.15.1 lint:code
  • cd website && corepack pnpm@11.15.1 lint:md
  • cd website && uv run --locked corepack pnpm@11.15.1 build

Checklist

  • CI passed

@vdusek vdusek left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thank you

@vdusek
vdusek merged commit 1e23b46 into apify:master Jul 27, 2026
34 checks passed
vdusek added a commit that referenced this pull request Aug 20, 2026
Closes: #1936

### Description

Adds `docs/guides/extending_crawlee.mdx`, a page that maps
Crawlee's extension points.

The four extension points you listed in the issue each already document
their own contract in the guide that owns them: crawlers in the [HTTP
crawlers guide](https://crawlee.dev/python/docs/guides/http-crawlers),
HTTP clients and storage clients in theirs, and browser plugins in the
Playwright crawler guide (#2089). What is still missing is the map, so
someone who wants to extend Crawlee has to already know which guide to
open, and a third-party project has no single page to point its users at
for "here is the interface this integration implements".

This page is that map. For each extension point it states when to
subclass rather than configure, names the base class and what its
contract covers, and links to the guide that goes deep. It deliberately
does not restate those guides.

### Contents

- **Extension points** — a class diagram plus one section each for
crawlers (`AbstractHttpCrawler`), HTTP clients (`HttpClient`), storage
clients (`StorageClient`), and browser plugins
(`PlaywrightBrowserPlugin`), each linking to its detailed guide.
- **Choosing an extension point** — matches the layer to what actually
differs in an integration, and says to prefer configuration over a
subclass where the built-in class already exposes the knob.
- Framing for third-party integrations, per the issue's rationale: they
host their own guide and reference the contract here.

### Notes

- Placed as its own guide rather than a section inside an existing one,
since it spans all four extension points. The sidebar picks it up
automatically (`autogenerated` over `docs/guides`).
- No new code examples: each linked guide already carries a runnable one
for its own extension point, so duplicating them here would mean two
copies to keep in sync.
- Happy to adjust the placement, depth, or wording, especially if you
would rather this live under a different section or carry a worked
example of its own.

### Testing

- `uv run poe build-docs` — build succeeds, the page renders at
`/docs/next/guides/extending-crawlee`, and the build reports no broken
links or anchors for it (the broken anchors in the log are pre-existing
ones on API pages).
- Verified every link target resolves before building: the five doc ids
(`http-crawlers`, `http-clients`, `storage-clients`,
`playwright-crawler`, `architecture-overview`), the
`playwright-crawler-with-camoufox` example, and each ApiLink class
(`AbstractHttpCrawler`, `BasicCrawler`, `HttpClient`, `StorageClient`,
`PlaywrightBrowserPlugin`, `PlaywrightBrowserController`, `BrowserPool`)
against `src/crawlee/`.

### AI assistance

Written with AI assistance (Claude). The scoping decision was mine to
check first what each extension point already documents, which is why
this is a map rather than four new sections; the browser-plugin quarter
was covered by my earlier #2089.

---------

Co-authored-by: Vlada Dusek <v.dusek96@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants