DriversRecommendedOutdated drivers can make a good PC feel brokenScan driver issues before chasing fixes manually.Scan NowHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsSlow PC?RecommendedPC slow today? Run a repair scan before it gets worseResolve common Windows issues and optimize system performance.Scan Now×
FREEDOM251

Freedom251 › Blog › localhost

How to Take a Puppeteer Screenshot of a Localhost Page

By Freedom251 Team · · 4 min read

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Start your local development server, then navigate Puppeteer to its full URL—such as http://localhost:3000—and save the page with page.screenshot(). Set an explicit wait condition and viewport when the image needs to be complete and repeatable.

Take a screenshot of a page on localhost

In a Node.js project configured to use ES modules, install Puppeteer with npm install puppeteer, start your development server, and save this as screenshot.mjs:

As an Amazon Associate I earn from qualifying purchases.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.goto('http://localhost:3000', { waitUntil: 'networkidle2' });
  await page.screenshot({ path: 'page.png', fullPage: true });
} finally {
  await browser.close();
}

Run it with node screenshot.mjs. Replace the URL, port, and output filename as needed. The URL must include a scheme such as http:// or https://. Puppeteer’s documented screenshot workflow uses Page.screenshot(); its Screenshots guide is at pptr.dev/guides/screenshots, and the navigation requirements are described in the Page.goto() reference.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Choose what to capture

Visible viewport

Omit fullPage to capture only the currently visible viewport:

#1 Best Overall
Dell Optiplex 3060 Desktop Computer | Intel i5-8500 (3.2) | 32GB DDR4 RAM | 1TB SSD Solid State | Built in WiFi | Bluetooth | Windows 11 Professional | Home or Office PC (Renewed)
  • [INTEL POWERED CONTENT] - Built with a 8th Generation Hexa-Core Intel i5 and 32GB of DDR4 RAM; Modern, Windows 11 ready, with 4K support, Executive multitasking, media streaming and smooth, multi-tab web browsing; Perfect as an all-purpose multimedia computer; built for content creators; Plenty of RAM and Mass storage for photo and video editing powered by Intel HD 630
  • [LATEST WIRELESS TECH] - This Dell Desktop Computer easily connects to the internet through the Built In WiFi / Bluetooth
  • [SOLID STATE STORAGE] - This Dell Computer setup comes with an ultra-fast 1TB Solid State Drive (SSD); Setup as the primary boot device; Boot and load programs with lightning speed ; Additional expansion available
  • [BUY & OWN WITH CONFIDENCE] - From the world's largest Microsoft Authorized Refurbisher; Quality Guarantee and Free Tech Support; Award-winning Customer Service; | Support Sustainable Business
  • [MODERN HI-SPEED PORTS] - USB 3.0 (x4) | USB 2.0 (x4) | DisplayPort (x1) | HDMI Port (x1) | Audio Combo Jack (x1) | Audio Out (x1) | RJ-45 Ethernet (x1) | Internal SATA (x3)
await page.screenshot({ path: 'viewport.png' });

Full document

Set fullPage: true to capture the full page rather than just the viewport:

await page.screenshot({ path: 'full-page.png', fullPage: true });

One element

To capture a specific element, select it and use its screenshot method:

const card = await page.$('.product-card');
if (!card) throw new Error('Could not find .product-card');
await card.screenshot({ path: 'product-card.png' });

Puppeteer scrolls the element into view if necessary. The operation throws if the element has been detached from the DOM. See the ElementHandle.screenshot() reference.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Dell Optiplex 7050 SFF Desktop PC Intel i7-7700 4-Cores 3.60GHz 32GB DDR4 1TB SSD WiFi BT HDMI Duel Monitor Support Windows 11 Pro Excellent Condition(Renewed)
  • Model: Dell OptiPlex 7050 Small Form Factor (SFF)
  • Processor: Intel Core i7-7700 3.60 GHz
  • Memory: 32GB DDR4 Ram
  • Storage: 1TB Solid State Drive (SSD) Fast Boot + Storage
  • Operating System: Windows 11 Pro (64-bit)

Wait until the content is ready

waitUntil: 'networkidle2' is a useful navigation starting point, but network quiet does not guarantee that an application has finished rendering, running animations, or loading delayed assets. For a dynamic page, wait for the content that matters:

await page.goto('http://localhost:3000', { waitUntil: 'domcontentloaded' });
await page.waitForSelector('[data-testid="dashboard-ready"]');
await page.screenshot({ path: 'dashboard.png', fullPage: true });

Replace the example selector with an element or readiness signal your application exposes. If the page depends on a known delay, Puppeteer also supports an explicit wait:

await page.goto('http://localhost:3000');
await new Promise(resolve => setTimeout(resolve, 1000));
await page.screenshot({ path: 'delayed.png' });

A fixed delay is simple but can make capture slower or unreliable when load time varies. A meaningful selector or app-ready signal is generally a better fit when available.

Rank #3
Sale
HP All-in-OneDesktop Computer, 16GB DDR5 RAM, Intel Quad-Cores, 128GB SSD, WiFi6, Keyboard & Mouse, Windows 11
  • IMMERSIVE 24 INCH DISPLAY: Experience stunning clarity on a Full HD IPS screen with ultra-thin bezels, offering a 90% screen-to-body ratio that makes everything from spreadsheets to streaming come alive with vibrant colors and crisp details.
  • POWERFUL INTEL PROCESSING: Tackle demanding tasks with ease thanks to the Intel processor and 16GB of high-speed memory, delivering smooth performance whether you're multitasking between applications or running productivity software.
  • GENEROUS STORAGE: Store all your important files, photos, and programs with blazing-fast solid state drive technology that ensures quick boot times, rapid file access, and plenty of space for your digital life.
  • ENHANCED PRIVACY AND COLLABORATION: Work confidently with the pop-up privacy camera that tucks away when not in use, plus dual microphones with noise reduction for crystal-clear video calls that keep you connected professionally.
  • ECO-CONSCIOUS DESIGN: Feel good about your purchase with an EPEAT Gold registered and ENERGY STAR certified computer that combines premium performance with responsible environmental manufacturing practices.

Set a repeatable viewport

For consistent screenshot dimensions, set the viewport before navigation. Puppeteer’s screen configuration guide says the default headless screen is 800 × 600 when neither --screen-info nor --window-size is supplied. Define the dimensions explicitly if layout differences matter:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
const page = await browser.newPage();
await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
await page.goto('http://localhost:3000', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'desktop.png', fullPage: true });

See Puppeteer’s screen configuration guide. The viewport affects responsive layout; choose dimensions that match the screen size you want to test.

Or skip the browser setup

If you need a screenshot from a reachable URL without managing a local Puppeteer browser, ScreenshotNeo offers a screenshot API and MCP server. It captures URLs, returning PNG, JPEG, WebP, or PDF; it cannot reach a site that is only available inside your computer’s localhost environment. To use it with a development page, expose that page at a URL the API can access.

Rank #4
Dell Optiplex 3050 SFF Desktop Computer PC, Intel Quad Core i5-6500 up to 3.6GHz, 16GB DDR4, 256GB SSD, WiFi, 4K Support, DP, HDMI, Windows 11 Pro 64 Bit (Renewed)
  • This Certified Refurbished product is tested and certified to look and work like new. The refurbishing process includes functionality testing, basic cleaning, inspection, and repackaging. The product ships with all relevant accessories, a minimum 90-day warranty, and may arrive in a generic box. Only select sellers who maintain a high-performance bar may offer Certified Refurbished products on Amazon.com.
  • Dell Optiplex 3050 SFF Desktop computer PC, Intel Quad Core i5-6500 up to 3.6GHz, 16GB DDR4, 256GB SSD
  • Includes: USB Keyboard & Mouse, USB WiFi adapter, Microsoft office 30 days free trail.
  • Port: Front: USB 3.0(2), USB 2.0(2); Rear: DP, HDMI, USB 3.0(2), USB 2.0(2), RJ-45.
  • Support 4K (3840x2160) Dual display, makes it easy to connect two monitors at the same time, and you can expand working Windows, mirror content, or expand a single window across multiple monitors.

For example, this cURL request captures a publicly reachable page:

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

See the ScreenshotNeo documentation for API options and setup. Cookie banners are accepted before capture, and known consent platforms, newsletter popups, and chat widgets are removed; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with response headers indicating the page verdict and billing status. Its MCP server provides screenshot tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Troubleshooting

Navigation fails or Puppeteer cannot connect

  • Confirm the development server is running and listening on the expected port.
  • Use the complete URL, including scheme and port, for example http://localhost:3000.
  • Make sure the process running Puppeteer can reach that server. In containerized or remote setups, localhost refers to the environment running Puppeteer, not necessarily your host machine.

The screenshot is blank or shows an error page

page.goto() does not throw solely because a response has a valid HTTP error status, such as 404 or 500, in headless shell mode. Inspect the returned response when diagnosing an error page:

Best Value
Dell Windows 11 Desktop Computer OptiPlex 5060 | Intel Core i5-8500 Six Core (4.3GHz Turbo) | 16GB DDR4 RAM | 500GB SSD Solid State + 1TB HDD | WiFi + Bluetooth | Home or Office PC (Renewed)
  • Connectivity: Includes WiFi, Bluetooth, and LAN for wireless and wired connections
  • Memory: Features 16GB DDR4 RAM for smooth multitasking and performance
  • Storage: Combines 500GB SSD and 1TB HDD for ample storage space
  • Graphics: Integrated Intel UHD Graphics 630 for crisp visuals and video playback
  • Design: Sleek desktop tower with black color and slim profile for modern look
const response = await page.goto('http://localhost:3000', { waitUntil: 'networkidle2' });
console.log('HTTP status:', response?.status());

Content or images are missing

Wait for a selector or readiness signal tied to the missing content rather than assuming that navigation completion means every asset or client-side render is finished. Check the browser console and application logs if the content never appears.

The element screenshot throws

Check that the selector matched an element and that the element remains attached to the page until the screenshot completes. A page update that replaces the selected element can detach the handle.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The browser remains open after an error

Keep navigation and capture inside a try block and close the browser in finally, as in the runnable example. This ensures the browser-close attempt runs if navigation or screenshot capture fails.

Browser mode and compatibility

Puppeteer documents headless: true as its new headless mode and headless: 'shell' as the old headless mode. Prefer Puppeteer’s bundled browser unless you have a reason to override it: the documentation cautions that using a custom executablePath is outside its browser compatibility guarantee. See the LaunchOptions reference.

Frequently Asked Questions

Where does Puppeteer save the screenshot?

The path passed in the path option is relative to the Node.js process’s current working directory unless you provide an absolute path.

What does page.screenshot() return if I do not set a path?

It returns screenshot image data as a Uint8Array by default. Puppeteer can also return base64-encoded data when requested.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Quick Recap

Bestseller No. 2
Dell Optiplex 7050 SFF Desktop PC Intel i7-7700 4-Cores 3.60GHz 32GB DDR4 1TB SSD WiFi BT HDMI Duel Monitor Support Windows 11 Pro Excellent Condition(Renewed)
Dell Optiplex 7050 SFF Desktop PC Intel i7-7700 4-Cores 3.60GHz 32GB DDR4 1TB SSD WiFi BT HDMI Duel Monitor Support Windows 11 Pro Excellent Condition(Renewed)
Model: Dell OptiPlex 7050 Small Form Factor (SFF); Processor: Intel Core i7-7700 3.60 GHz; Memory: 32GB DDR4 Ram
$384.00
Bestseller No. 4
Dell Optiplex 3050 SFF Desktop Computer PC, Intel Quad Core i5-6500 up to 3.6GHz, 16GB DDR4, 256GB SSD, WiFi, 4K Support, DP, HDMI, Windows 11 Pro 64 Bit (Renewed)
Dell Optiplex 3050 SFF Desktop Computer PC, Intel Quad Core i5-6500 up to 3.6GHz, 16GB DDR4, 256GB SSD, WiFi, 4K Support, DP, HDMI, Windows 11 Pro 64 Bit (Renewed)
Includes: USB Keyboard & Mouse, USB WiFi adapter, Microsoft office 30 days free trail.; Port: Front: USB 3.0(2), USB 2.0(2); Rear: DP, HDMI, USB 3.0(2), USB 2.0(2), RJ-45.
$189.99
Bestseller No. 5
Dell Windows 11 Desktop Computer OptiPlex 5060 | Intel Core i5-8500 Six Core (4.3GHz Turbo) | 16GB DDR4 RAM | 500GB SSD Solid State + 1TB HDD | WiFi + Bluetooth | Home or Office PC (Renewed)
Dell Windows 11 Desktop Computer OptiPlex 5060 | Intel Core i5-8500 Six Core (4.3GHz Turbo) | 16GB DDR4 RAM | 500GB SSD Solid State + 1TB HDD | WiFi + Bluetooth | Home or Office PC (Renewed)
Connectivity: Includes WiFi, Bluetooth, and LAN for wireless and wired connections; Memory: Features 16GB DDR4 RAM for smooth multitasking and performance
$269.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

localhostNode.jsPuppeteerscreenshotsWeb development

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.