Puppeteer Page Creation Options Explained

Puppeteer creates a page with browser.newPage() in the browser’s default context. To give a page its own session boundary, create a BrowserContext and call context.newPage(). Use CreatePageOptions to request a tab or window, optionally with window bounds or background creation. These are page creation choices; launching or connecting to the browser is a separate decision.

1. Choose the page and session you need

Need	Use	What it means
A page that shares the default browser session	`browser.newPage()`	Creates a page in the default browser context.
A separate session for an automation task	`browser.createBrowserContext()`, then `context.newPage()`	Separate contexts do not share cookies or cache. Context closure closes its pages.
A tab or window presentation choice	`newPage({ type: 'tab' })` or `newPage({ type: 'window' })`	The documented page options allow a tab or window; window bounds apply to the window form.
Several related pages with one cleanup boundary	One context, several `context.newPage()` calls	Pages use the selected context and can be closed together by closing it.

On Chrome, non-default browser contexts are incognito. Keep that Chrome-specific detail scoped to Chrome rather than assuming identical behavior across every browser backend.

2. Create a page in the default context

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log(await page.title());
} finally {
  await browser.close();
}

browser.newPage() is the straightforward option when the page can share the default browser context. If you only need a new page and do not need an isolated session, there is no need to create a context first.

3. Create an isolated session with BrowserContext

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const context = await browser.createBrowserContext();
  try {
    const page = await context.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
    console.log(await page.url());
  } finally {
    await context.close();
  }
} finally {
  await browser.close();
}

Use a context when tasks need independent cookies and local storage, or when a group of pages should share one session and cleanup boundary. Separate contexts do not share cookies or cache. Closing a context closes its associated pages. The API documentation describes the separation this way: “This won’t share cookies/cache with other browser contexts.” See the official Browser.createBrowserContext() reference and BrowserContext reference.

For two independent sessions, create two contexts and make each page from its own context:

const firstContext = await browser.createBrowserContext();
const secondContext = await browser.createBrowserContext();

const firstPage = await firstContext.newPage();
const secondPage = await secondContext.newPage();

// Close each context when its session is finished.
await Promise.all([firstContext.close(), secondContext.close()]);

4. Choose tab or window options

The documented CreatePageOptions type is a union. Omit type or set it to 'tab' to request a tab. Set type: 'window' to request a window; that form can include windowBounds. Either form can include background.

// Request a tab explicitly.
const tab = await browser.newPage({ type: 'tab' });

// Request a window and specify its bounds.
const windowPage = await browser.newPage({
  type: 'window',
  windowBounds: { width: 1200, height: 800 },
});

// Background creation can be requested with either form.
const backgroundTab = await browser.newPage({ type: 'tab', background: true });

Use the tab form for the ordinary page creation path. Choose a window when a distinct window is required by your workflow, and supply bounds only when you need to specify them. The exact option type is versioned: the research references show CreatePageOptions at 25.10.0 while related current references show 25.12.0. Check the documentation matching the Puppeteer version in your project before relying on an option. See CreatePageOptions and Browser.newPage().

5. Launch a browser or connect to one

Page creation is independent of browser process management. Puppeteer can launch a browser, or connect to an existing browser and then create pages through the connected Browser object. The official browser management guide covers launching and connecting; see also Puppeteer.connect().

import puppeteer from 'puppeteer';

// Either launch a browser:
const browser = await puppeteer.launch();
const page = await browser.newPage();

// Or connect to an existing browser using its endpoint:
// const browser = await puppeteer.connect({ browserWSEndpoint: endpoint });
// const page = await browser.newPage();

Manage the browser lifetime separately from page and context lifetimes. browser.close() closes the browser and its associated pages. When Puppeteer connected to an externally managed browser, disconnecting detaches Puppeteer without shutting down that browser. Choose the cleanup operation that matches who owns the browser process.

6. Run a complete page creation example

This example creates one default-context page and one isolated-context page, navigates both, then closes the isolated context and browser. It uses the standard tab path; remove the second page if your task needs only one session.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
let context;
try {
  const sharedSessionPage = await browser.newPage();
  await sharedSessionPage.goto('https://example.com', {
    waitUntil: 'domcontentloaded',
    timeout: 30_000,
  });

  context = await browser.createBrowserContext();
  const isolatedSessionPage = await context.newPage();
  await isolatedSessionPage.goto('https://example.org', {
    waitUntil: 'domcontentloaded',
    timeout: 30_000,
  });

  console.log({
    firstTitle: await sharedSessionPage.title(),
    secondTitle: await isolatedSessionPage.title(),
  });
} finally {
  if (context) await context.close();
  await browser.close();
}

7. Troubleshooting page creation

Symptom	Likely cause	Fix
Cookies or storage appear in another task	The pages were created in the default context or the same context.	Create a separate browser context for each independent session, then create each page with that context’s `newPage()`.
Pages close unexpectedly after cleanup	Their owning context or browser was closed.	Keep the context open for the lifetime of its pages. Close the browser only after all browser work is finished.
Closing Puppeteer also stops a remote browser	Browser lifetime handling does not match whether Puppeteer launched or connected to that process.	For a connected, externally managed browser, disconnect Puppeteer to detach; use browser close when Puppeteer owns the launched browser.
A tab/window option is rejected or has no effect	The installed Puppeteer version may not match the option reference, or the selected browser backend may differ.	Check the matching version’s `CreatePageOptions` documentation and use the tab default unless a window is required.
Navigation fails after the page was created	Page creation succeeded, but the destination load did not. This is a navigation or site availability issue rather than a context choice.	Handle navigation separately: set an appropriate wait condition and timeout, and inspect the target URL and browser errors.

8. Performance, reliability, and cost

The cited API documentation defines behavior and lifecycle; it does not provide a performance ranking between default pages, contexts, tabs, or windows. Choose based on session isolation and cleanup needs. Reusing a context for pages that belong to one session avoids creating a new session boundary for each related page, while separate contexts provide the documented separation of cookies and cache. Treat this as a design choice, not a benchmark claim.

For reliability, make ownership explicit: close a context when its group of pages is done, and close a launched browser when the process is no longer needed. When connected to a browser managed elsewhere, detach rather than closing a process your application does not own. For cost, the supplied Puppeteer references state no usage pricing; browser hosting or infrastructure costs depend on how and where you run the browser.

9. Or skip the browser setup

If your goal is a screenshot rather than interactive browser automation, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

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

import requests

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

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free and capture 1,000 screenshots a month with no card.

10. Frequently asked questions

Does `browser.newPage()` create an isolated session?

No. It creates the page in the browser’s default context. Use a separately created BrowserContext when the session needs isolation.

Yes. Create each with context.newPage(); they belong to that context and share its session boundary.

Do I need to launch Chromium to create a page?

No. Puppeteer can connect to an existing browser, then create pages through the connected browser object.

Should I request a window or a tab?

Use a tab for the ordinary page workflow. Request a window when your workflow needs a distinct window, with bounds if needed.