hhy5277 / capture-website

Capture screenshots of websites

capture-website

Capture screenshots of websites

It uses Puppeteer (Chrome) under the hood.

See capture-website-cli for the command-line tool.

Install

$ npm install capture-website

Note to Linux users: If you get a "No usable sandbox!" error, you need to enable system sandboxing.

Usage

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png');
})();

API

captureWebsite.file(url, filePath, [options])

Returns a Promise<void> that resolves when the screenshot is written to the given file path.

captureWebsite.buffer(url, [options])

Returns a Promise<Buffer> with the screenshot as binary.

captureWebsite.base64(url, [options])

Returns a Promise<string> with the screenshot as Base64.

url

Type: string

The URL, file URL, data URL, or local file path to the website.

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('index.html', 'local-file.png');
})();

options

Type: Object

width

Type: number
Default: 1280

Page width.

height

Type: number
Default: 800

Page height.

type

Type: string
Values: png jpeg
Default: png

Image type.

quality

Type: number
Values: 0...1
Default: 1

Image quality. Only for {type: 'jpeg'}.

scaleFactor

Type: number
Default: 2

Scale the webpage n times.

The default is what you would get if you captured a normal screenshot on a computer with a retina (High DPI) screen.

emulateDevice

Type: string
Values: Devices (Use the name property)

Make it look like the screenshot was taken on the specified device.

This overrides the width, height, scaleFactor, and userAgent options.

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
		emulateDevice: 'iPhone X'
	});
})();

fullPage

Type: boolean
Default: false

Capture the full scrollable page, not just the viewport.

defaultBackground

Type: boolean
Default: true

Include the default white background.

Disabling this lets you capture screenshots with transparency.

timeout

Type: number (seconds)
Default: 60

The number of seconds before giving up trying to load the page.

Specify 0 to disable the timeout.

delay

Type: number (seconds)
Default: 0

The number of seconds to wait after the page finished loading before capturing the screenshot.

This can be useful if you know the page has animations that you like it to finish before capturing the screenshot.

waitForElement

Type: string

Wait for a DOM element matching the given CSS selector to appear in the page and to be visible before capturing the screenshot. It times out after options.timeout seconds.

element

Type: string

Capture the DOM element matching the given CSS selector. It will wait for the element to appear in the page and to be visible. It times out after options.timeout seconds.

hideElements

Type: string[]

Hide DOM elements matching the given CSS selectors.

Can be useful for cleaning up the page.

This sets visibility: hidden on the matched elements.

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
		hideElements: [
			'#sidebar',
			'img.ad'
		]
	});
})();

removeElements

Type: string[]

Remove DOM elements matching the given CSS selectors.

This sets display: none on the matched elements, so it could potentially break the website layout.

clickElement

Type: string

Click the DOM element matching the given CSS selector.

modules

Type: string[]

Inject JavaScript modules into the page.

Accepts an array of inline code, absolute URLs, and local file paths (must have a .js extension).

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
		modules: [
			'https://sindresorhus.com/remote-file.js',
			'local-file.js',
			`
			document.body.style.backgroundColor = 'red';
			`
		]
	});
})();

scripts

Type: string[]

Same as the modules option, but instead injects the code as <script> instead of <script type="module">. Prefer the modules option whenever possible.

styles

Type: string[]

Inject CSS styles into the page.

Accepts an array of inline code, absolute URLs, and local file paths (must have a .css extension).

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
		styles: [
			'https://sindresorhus.com/remote-file.css',
			'local-file.css',
			`
			body {
				background-color: red;
			}
			`
		]
	});
})();

headers

Type: Object
Default: {}

Set custom HTTP headers.

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
		headers: {
			'x-powered-by': 'https://github.com/sindresorhus/capture-website'
		}
	});
})();

userAgent

Type: string

Set a custom user agent.

cookies

Type: Array<string | Object>

Set cookies in browser string format or object format.

Tip: Go to the website you want a cookie for and copy-paste it from DevTools.

const captureWebsite = require('capture-website');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
		cookies: [
			// This format is useful for when you copy it from the browser
			'id=unicorn; Expires=Wed, 21 Oct 2018 07:28:00 GMT;',

			// This format is useful for when you have to manually create a cookie
			{
				name: 'id',
				value: 'unicorn',
				expires: Math.round(new Date('2018-10-21').getTime() / 1000)
			}
		]
	});
})();

authentication

Type: Object

Credentials for HTTP authentication.

username

Type: string

password

Type: string

beforeScreenshot

Type: Function

The specified function is called right before the screenshot is captured. It receives the Puppeteer Page instance as the first argument and the browser instance as the second argument. This gives you a lot of power to do custom stuff. The function can be async.

Note: Make sure to not call page.close() or browser.close().

const captureWebsite = require('capture-website');
const checkSomething = require('./check-something');

(async () => {
	await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
		beforeScreenshot: async (page, browser) => {
			await checkSomething();
			await page.click('#activate-button');
			await page.waitForSelector('.finished');
		}
	});
})();

debug

Type: boolean
Default: false

Show the browser window so you can see what it's doing, redirect page console output to the terminal, and slow down each Puppeteer operation.

Note: This overrides launchOptions with {headless: false, slowMo: 100}.

launchOptions

Type: Object
Default: {}

Options passed to puppeteer.launch().

Note: Some of the launch options are overridden by the debug option.

overwrite

Type: boolean
Default: false

Overwrite the destination file if it exists instead of throwing an error.

This option applies only to captureWebsite.file().

captureWebsite.devices

Type: string[]

Devices supported by the emulateDevice option.

Tips

Capturing multiple screenshots

const captureWebsite = require('capture-website');

const options = {
	width: 1920,
	height: 1000
};

const items = new Map([
	['https://sindresorhus.com', 'sindresorhus'],
	['https://github.com', 'github'],
	// …
]);

(async () => {
	await Promise.all(items.map(({url, filename}) => {
		return captureWebsite.file(url, `${filename}.png`, options);
	}));
})();

Check out filenamify-url if you need to create a filename from the URL.

FAQ

How is this different from your Pageres project?

The biggest difference is that Pageres supports capturing multiple screenshots in a single call and it automatically generates the filenames and writes the files. Also, when projects are popular and mature, like Pageres, it becomes harder to make drastic changes. There are many things I would change in Pageres today, but I don't want to risk making lots of breaking changes for such a large userbase before I know whether it will work out or not. So this package is a rethink of how I would have made Pageres had I started it today. I plan to bring some things back to Pageres over time.

Related

• capture-website-cli - CLI for this module
• pageres - A different take on screenshotting websites

License

MIT © Sindre Sorhus