Puppeteer Target Types: What Each Type Means

Puppeteer’s TargetType enum has seven values: background_page, browser, other, page, service_worker, shared_worker, and webview. A target is the CDP-level object Puppeteer classifies; a page is a higher-level Page object that you can obtain from certain target types. Use Target.page() for page, webview, and background_page targets, and Target.worker() for service and shared workers.

What Puppeteer target types mean

The enum lists the possible classifications, but does not define the browser-internal meaning of every value. The safe practical interpretation is based on Puppeteer’s method contracts: some types support page access, some support worker access, and some have no such access path documented. See the Puppeteer TargetType enum and confirm details against the documentation for your installed Puppeteer version.

Type	What the API supports	Practical note
PAGE ("page")	Target.page() may return a Page.	The ordinary page target type.
WEBVIEW ("webview")	Target.page() may return a Page.	Page-like for Puppeteer’s page accessor. The enum reference does not provide a deeper definition.
BACKGROUND_PAGE ("background_page")	Target.page() may return a Page.	Non-visible background pages are not included in BrowserContext.pages(); find them through targets and call Target.page().
SERVICE_WORKER ("service_worker")	Target.worker() may return a WebWorker.	Use the worker accessor rather than expecting a page.
SHARED_WORKER ("shared_worker")	Target.worker() may return a WebWorker.	Also supported by the worker accessor.
BROWSER ("browser")	No page or worker accessor is specified for this type.	The enum names the type but does not define further semantics.
OTHER ("other")	No page or worker accessor is specified for this type.	The enum names the type but does not define further semantics.

Page versus target in Puppeteer

A Target is the object that Target.type() classifies. Puppeteer describes targets at the Chrome DevTools Protocol level and gives frames, pages, and workers as examples. The method documentation summarizes Target.type() as: “Identifies what kind of target this is.” A Page is the page-facing API object used to work with page content and browser interactions. Not every target is a page, and Target.page() returns null for target types other than page, webview, or background_page. Target.type() reference · Target class reference.

Choose the right accessor

1. Get targets from the relevant browser context.
2. Read each target’s type if you need to branch on classification.
3. Call page() for page-like targets or worker() for supported worker targets.
4. Handle null: a target can be valid without producing a page or worker object through that accessor.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const context = browser.defaultBrowserContext();
  const targets = context.targets();

  for (const target of targets) {
    const type = target.type();
    console.log(type, target.url());

    if (type === 'page' || type === 'webview' || type === 'background_page') {
      const page = await target.page();
      if (page) {
        console.log('Page title:', await page.title());
      }
    } else if (type === 'service_worker' || type === 'shared_worker') {
      const worker = await target.worker();
      if (worker) {
        console.log('Worker URL:', worker.url());
      }
    }
  }
} finally {
  await browser.close();
}

Save as targets.mjs, install Puppeteer in the project with npm install puppeteer, then run node targets.mjs. The example uses the default browser context; use a different BrowserContext when your workflow needs a separate user context.

Enumerate visible pages separately

If your task is specifically to work with visible pages, BrowserContext.pages() is the direct API. Its result excludes non-visible pages such as background_page. Use context.targets() when you need the broader set of active targets, then inspect types and use the supported accessor. BrowserContext reference · BrowserContext.targets().

const pages = await context.pages();
for (const page of pages) {
  console.log(await page.title(), page.url());
}

Complete runnable target inspector

This standalone script visits a URL, reports its targets, and prints the page and worker access paths when available. It deliberately checks returned values rather than assuming a target always maps to one.

import puppeteer from 'puppeteer';

const url = process.argv[2] ?? 'https://example.com';
const browser = await puppeteer.launch({ headless: true });
try {
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'domcontentloaded' });

  const context = page.browserContext();
  for (const target of context.targets()) {
    const type = target.type();
    const targetUrl = target.url();
    let result = `${type}\t${targetUrl}`;

    if (['page', 'webview', 'background_page'].includes(type)) {
      const pageForTarget = await target.page();
      if (pageForTarget) result += `\tpage title=${await pageForTarget.title()}`;
    }
    if (['service_worker', 'shared_worker'].includes(type)) {
      const worker = await target.worker();
      if (worker) result += `\tworker=${worker.url()}`;
    }
    console.log(result);
  }
} finally {
  await browser.close();
}

What the access methods return

Method	Supported target types	Result when unsupported
Target.page()	page, webview, background_page	null
Target.worker()	service_worker, shared_worker	null

These contracts are more useful for application code than guessing at meanings the enum page does not state. The Target.worker() reference documents worker access, while the Target class reference documents page access and the background-page visibility caveat.

Version and context considerations

• The enum source lists seven values for Puppeteer v25.12.0. If your installed package differs, consult its matching API reference and TypeScript definitions before relying on the exact set.
• The Target class behavior referenced here is from Puppeteer’s Next documentation and can change. Treat the method contract for your installed version as authoritative.
• A BrowserContext represents an individual user context with isolated storage. Its targets() method lists active targets in that context; target classification and context membership answer different questions.
• Targets are a changing collection. Pages and workers can be created or closed while automation is running, so enumerate when needed and handle missing/closed objects in longer workflows.

Troubleshooting

Symptom	Likely cause	Fix
target.page() returns null	The target is not page, webview, or background_page.	Check target.type(); use worker() for service/shared workers or skip page-only operations.
A background page is missing from context.pages()	That method omits non-visible pages such as background pages.	Enumerate context.targets(), find the background-page target, and call target.page().
target.worker() returns null	The target type is not service_worker or shared_worker.	Inspect target.type(); do not treat the result as a page worker.
A target is absent from the list	It may not be active in the selected context, or it may have closed before enumeration.	Check the context you queried and enumerate again at the point the target is needed.
A type value is unexpected	Your installed Puppeteer/browser version may differ from the documentation version.	Check package and browser versions and use the matching Puppeteer reference.

Performance, reliability, and cost

Enumerating targets is useful when the workflow needs more than pages, but do not repeatedly resolve page or worker objects when one enumeration is enough. Keep the scope to the relevant browser context, and avoid assuming target order or lifetime. Puppeteer target inspection itself does not define a service price; infrastructure costs depend on where and how you run the browser, which is outside the target enum’s contract.

Or skip the browser setup

If the goal is to capture a website rather than inspect Puppeteer’s target model, ScreenshotNeo offers a screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. The options include full-page capture, CSS selector capture, device presets, custom waits, request blocking, and caching. The API documentation has the request details.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are never billed. Response headers report the page verdict and billing status.
• An MCP server lets AI agents using Claude, Cursor, or another MCP client take screenshots, inspect page information, and capture PDFs.
• 1,000 screenshots a month are free with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

How many Puppeteer target types are there?

The v25.12.0 enum reference lists seven.

Can every target be converted into a page?

No. Target.page() returns null outside the three page-like types.

Are all pages returned by BrowserContext.pages()?

No. Non-visible pages such as background pages are excluded.

Where should I check version-specific behavior?

Use the API documentation and type definitions that match the Puppeteer version installed in your project.