Puppeteer CreatePageOptions: Page Creation Settings Explained

CreatePageOptions is the small options object passed to BrowserContext.newPage(). It selects a tab or a window, can supply window bounds for the window branch, and can include the optional shared background flag. It does not configure viewport dimensions, user agent, or storage isolation.

The documented type reference is labeled Puppeteer 25.10.0. Some supporting method references surfaced as 25.12.0, so check the documentation matching your installed Puppeteer version before relying on version-specific details. [CreatePageOptions type](https://pptr.dev/api/puppeteer.createpageoptions)

1. The CreatePageOptions type

export type CreatePageOptions = (
  | {
      type?: 'tab';
    }
  | {
      type: 'window';
      windowBounds?: WindowBounds;
    }
) & {
  background?: boolean;
};

This is a TypeScript union intersected with a shared optional property. In practical terms, the valid branches are:

Branch	Fields	Meaning in the type
Tab	type omitted or type: 'tab'	Selects the tab branch. The type signature alone does not establish additional default behavior.
Window	type: 'window'; optional windowBounds	Selects the window branch. Bounds use Puppeteer’s WindowBounds type.
Shared	Optional background	May be set with either branch. The reference signature does not explain its operational behavior.

Because type: 'window' is required for that branch, an object with only windowBounds is not the documented window form. The signature also does not establish platform support or placement guarantees for window bounds; consult the matching version documentation for those details.

2. Pass options to BrowserContext.newPage()

BrowserContext.newPage(options?) creates a page in the context on which it is called and resolves to a Page. [BrowserContext.newPage()](https://pptr.dev/api/puppeteer.browsercontext.newpage)

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const context = browser.defaultBrowserContext();
  const page = await context.newPage({ type: 'tab' });
  await page.goto('https://example.com');
  console.log(await page.title());
  await page.close();
} finally {
  await browser.close();
}

If the tab form is suitable, you can omit the options object or pass { type: 'tab' }. Use the explicit form when it makes the intended creation mode clearer to readers of your code.

The new-page method belongs to a BrowserContext, not directly to the browser. A page created through a context is owned by that context. [BrowserContext](https://pptr.dev/api/puppeteer.browsercontext)

3. Create a separate storage context when needed

A new page and a new user context are different things. Browser contexts isolate storage such as cookies and localStorage. Pages opened through window.open remain in their parent page’s context. If a workflow needs a separate storage boundary, create a context and then create the page inside it.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
let context;
try {
  context = await browser.createBrowserContext();
  const page = await context.newPage({ type: 'tab' });
  await page.goto('https://example.com');
  console.log(await page.title());
} finally {
  if (context) {
    await context.close(); // Closes pages owned by this context.
  }
  await browser.close();
}

The documented isolated-context flow is to create a browser context, use its pages, and close the context when finished. Closing a context closes its pages; the default context cannot be closed. [Browser.createBrowserContext()](https://pptr.dev/api/puppeteer.browser.createbrowsercontext)

4. Configure viewport and user agent separately

CreatePageOptions has no viewport or user-agent fields. Configure these on the returned Page, or set a connection-wide default viewport when connecting to a browser.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.defaultBrowserContext().newPage({ type: 'tab' });

  // Set responsive emulation before navigation.
  await page.setViewport({ width: 1280, height: 800 });
  await page.setUserAgent('ExampleAutomation/1.0');
  await page.goto('https://example.com');
} finally {
  await browser.close();
}

Puppeteer’s Page API includes setViewport and setUserAgent; device emulation is a shortcut for applying viewport and user-agent settings. Set the viewport before navigation for responsive emulation: changing viewport properties, particularly mobile or touch properties, can resize a page and in some cases reload it. [Page API](https://pptr.dev/api/puppeteer.page)

When connecting to an existing browser, ConnectOptions.defaultViewport applies a viewport to each page and is documented with an 800 by 600 default. It is a connection option, not a field of CreatePageOptions. [ConnectOptions](https://pptr.dev/api/puppeteer.connectoptions)

5. Choose the right layer for each setting

Need	Use
Choose a tab or window when creating a page	context.newPage({ type: ... })
Provide window bounds for the window branch	context.newPage({ type: 'window', windowBounds: ... })
Set a viewport or user agent for a page	Page methods such as setViewport() and setUserAgent()
Set a default viewport for pages created through a connection	ConnectOptions.defaultViewport
Separate cookies and localStorage from another workflow	Create a separate BrowserContext, then call its newPage()

Keeping these layers distinct makes code easier to reason about: creation mode belongs in CreatePageOptions, page emulation belongs on the page or connection, and storage separation belongs to the browser context.

6. TypeScript examples and checks

Import the type from Puppeteer when you want to name the options object or validate a helper’s parameter. The type’s exact export path can vary with package versions; use the type export documented by the installed version.

import puppeteer from 'puppeteer';
import type { CreatePageOptions } from 'puppeteer';

const options: CreatePageOptions = {
  type: 'window',
  background: true,
};

const browser = await puppeteer.launch();
try {
  const page = await browser.defaultBrowserContext().newPage(options);
  await page.goto('https://example.com');
} finally {
  await browser.close();
}

With strict TypeScript checking, the union helps catch mismatched branches: the window branch requires type: 'window'; the tab branch allows only an omitted type or 'tab'. Whether a particular bounds object is valid depends on the installed release’s WindowBounds definition.

7. Common errors and fixes

Symptom	Likely cause	Fix
TypeScript rejects viewport or userAgent	Those are not members of CreatePageOptions.	Create the page, then use page.setViewport() or page.setUserAgent(); for connection defaults, inspect ConnectOptions.defaultViewport.
TypeScript rejects { windowBounds: ... }	The window branch requires type: 'window'.	Pass both type: 'window' and the bounds value.
Two pages unexpectedly share cookies or localStorage	They were created in the same browser context.	Create a separate browser context for the workflow that needs isolated storage.
A viewport change reloads or resizes the page	Viewport changes can resize a page and may reload it for mobile or touch-property changes.	Set responsive viewport properties before navigating when possible.
Code compiles against a different-looking API reference	The type and supporting references may be from different Puppeteer versions.	Check the documentation and type definitions for the installed package version.

8. Or skip the browser setup

If the goal is a screenshot rather than control over a live Puppeteer page, ScreenshotNeo provides a website screenshot API. Send one GET request with the target URL to get an image or PDF. Its options include full-page capture, CSS selector capture, viewport and device presets, custom CSS and JavaScript, and wait conditions. See the ScreenshotNeo API documentation.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

• Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed. Responses include X-Page-Verdict and X-Billed headers.
• An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf.
• 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000. Every feature is available on every plan.

Sign up for ScreenshotNeo and get 1,000 free screenshots a month, with no card required.

9. Performance, reliability, and cost considerations

For a Puppeteer workflow, browser and page lifecycle management affect resource use: close pages or their owning context when finished, and close the browser at the end of a standalone run. A separate context provides storage isolation but also creates another context lifecycle to manage. The API references cited here do not provide performance benchmarks, so choose the simplest context structure that meets the isolation requirement and measure it in your own environment.

For repeated page setup, keep reusable settings in a helper so viewport, user agent, and navigation order stay consistent. Set the viewport before navigation for responsive captures. Do not treat background as a documented performance switch: the type reference permits the property but does not describe its runtime effect.

ScreenshotNeo is usage-priced: Free includes 1,000 shots per month; Starter is $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000. Yearly billing gives two months free. The product bills only clean shots; the response headers indicate the page verdict and billing status. See current plan details at ScreenshotNeo.

10. Frequently asked questions

Does newPage() create a new browser window?

The method accepts CreatePageOptions, whose type allows a tab branch or a window branch. Select the window branch with type: 'window'; consult the reference for the Puppeteer version you use for runtime and platform specifics.

Can I set the viewport in CreatePageOptions?

No. Set it on the returned Page, or use a connection-level default viewport where appropriate.

Does creating another page isolate cookies?

No. Pages belong to contexts. Create a separate BrowserContext when you need separate cookies and localStorage.

What does background mean?

It is an optional property in the documented type, shared by both branches. The cited type signature does not describe its operational behavior, so check the matching version’s documentation rather than assuming an effect.

Which Puppeteer version does this guide describe?

The CreatePageOptions reference is labeled 25.10.0. Supporting references surfaced as 25.12.0. Match the API docs and type definitions to the package version installed in your project.