Blocking Requests in Puppeteer: Native Interception vs the Block-Resources Plugin
Puppeteer automation often loads far more than the task needs: product photos, tracking scripts, video players, fonts. Each of those requests costs time and bandwidth. This guide explains two ways to stop them — Puppeteer's own request interception API and the puppeteer-extra block-resources plugin — and helps you choose between them.
Why block resources at all
A Puppeteer page load pulls in every asset the page references. If you only need the HTML or a specific element, most of that traffic is wasted work. A price scraper, for example, does not need the product gallery images or the analytics libraries the storefront loads. Cutting those requests shortens the script's runtime and reduces the chance of hitting rate limits or timeouts. The trade-off is that some resources are needed for the page to render correctly — blocking a stylesheet or a script that builds the DOM can leave you with an empty or broken page. The goal is selective blocking, not blocking everything.
Method 1: Puppeteer's native request interception API
Puppeteer exposes setRequestInterception(true) on the page. Once enabled, every request fires a 'request' event, and your listener decides whether to abort or continue it. This is the most direct route and needs no extra packages.
A minimal listener checks the request URL for image extensions and aborts those, continuing everything else. The request object gives you url() for the address and resourceType() for the category Puppeteer assigned to the request. The second native example extends the listener to also abort requests whose resourceType() is 'video', so media files are dropped alongside images.
The field map below summarises what each call does. The exact code for both native examples is supplied as protected modules and is reproduced verbatim alongside this page.
Method 2: the puppeteer-extra block-resources plugin
puppeteer-extra wraps Puppeteer and lets you attach plugins. The block-resources plugin turns resource blocking into a set of named types you add or remove at runtime, instead of writing URL or resourceType checks yourself.
Install puppeteer-extra and the plugin, then call puppeteer.use(blockResourcesPlugin). Add types with blockedTypes.add('media') or blockedTypes.add('script'); remove them with blockedTypes.remove('stylesheet'). The plugin's available types are listed in the reference table below. The exact install and usage code is supplied as protected modules and reproduced verbatim alongside this page.
Which method should you use?
Use the native API when you want no extra dependencies, when your blocking rule is a simple URL pattern or a single resourceType check, or when you need to abort based on something the plugin does not expose. Use the plugin when you want to toggle whole categories at runtime, when you are already using puppeteer-extra for other plugins, or when you want the named type list rather than hand-written conditions.
A quick checklist before you commit:
- Do you need to block by file extension or URL fragment? Native API.
- Do you need to block whole categories like media or script? Either works; the plugin is shorter.
- Do you need to change what is blocked mid-script? The plugin's add/remove calls are convenient.
- Are you already using puppeteer-extra? The plugin fits naturally.
- Do you want zero extra packages? Native API.
Request listener field map
Inside a 'request' listener you have a request object. The calls used in the examples are:
- request.url() — the request's address; useful for extension checks like .png or .jpg.
- request.resourceType() — the category Puppeteer assigned, such as 'video'.
- request.abort() — stop the request.
- request.continue() — let the request proceed.
With the plugin, the equivalent controls are blockedTypes.add(type) and blockedTypes.remove(type), where type is one of the names in the reference table.
Worked example: a price scraper that keeps only what it needs
Suppose you are crawling an e-commerce site for a product name and price. The page loads product photos, a video, analytics scripts and a stylesheet. Your scraper needs the HTML and the stylesheet (so the price element is visible), but not the images, video or analytics. With the native API you would abort requests whose URL ends in .png or .jpg and whose resourceType() is 'video', and continue the rest. With the plugin you would add 'image', 'media' and 'script' to blockedTypes and leave 'stylesheet' alone. Either way, verify the price element still appears before you trust the result — blocking too much is the most common failure.
Common failure: blocking too much
If your page renders blank or a selector never matches, you have probably aborted a resource the page needed. Stylesheets and scripts that build the DOM are the usual culprits. Start by blocking only images and media, confirm the page still works, then add categories one at a time. The plugin's remove() call lets you re-enable a type without rewriting your listener.
| Type |
|---|
| document |
| stylesheet |
| image |
| media |
| font |
| script |
| texttrack |
| xhr |
| fetch |
| eventsource |
| websocket |
| manifest |
| other |
These are the type names accepted by blockedTypes.add() and blockedTypes.remove() in the puppeteer-extra block-resources plugin, as listed in the captured reference. Plugin behaviour may change; check the package documentation for the current list.
Frequently asked questions
Do I need puppeteer-extra to block requests?
No. Puppeteer's own setRequestInterception(true) plus a 'request' listener is enough. The plugin is a convenience wrapper that lets you name resource types instead of writing URL or resourceType conditions.
Can I block CSS but keep images?
Yes. With the native API, check resourceType() for 'stylesheet' and abort only those. With the plugin, add 'stylesheet' to blockedTypes and leave 'image' out. Be aware that blocking CSS can change layout and hide elements you need.
What happens if I forget to call continue()?
Once interception is enabled, every request waits for your listener to call abort() or continue(). A request you neither abort nor continue will hang, and the page may never finish loading.
Which resource types can the plugin block?
The reference table on this page lists the available types, including document, stylesheet, image, media, font, script, xhr, fetch and others. Add or remove them with blockedTypes.add() and blockedTypes.remove().