pageres
Version:
Capture website screenshots
289 lines (167 loc) • 6.64 kB
Markdown
# 
[](https://codecov.io/gh/sindresorhus/pageres)
[](https://github.com/xojs/xo)
Capture screenshots of websites in various resolutions. A good way to make sure your websites are responsive. It's speedy and generates 100 screenshots from 10 different websites in just over a minute. It can also be used to render SVG images.
*See [pageres-cli](https://github.com/sindresorhus/pageres-cli) for the command-line tool.*
## Install
```sh
npm install pageres
```
Note to Linux users: If you get a "No usable sandbox!" error, you need to enable [system sandboxing](https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md#setting-up-chrome-linux-sandbox).
## Usage
```js
import Pageres from 'pageres';
await new Pageres({delay: 2})
.source('https://github.com/sindresorhus/pageres', ['480x320', '1024x768'], {crop: true})
.source('https://sindresorhus.com', ['1280x1024', '1920x1080'])
.source('data:text/html,<h1>Awesome!</h1>', ['1024x768'])
.sourceHtml('<h1>Direct HTML!</h1>', ['1024x768'])
.destination('screenshots')
.run();
console.log('Finished generating screenshots!');
```
## API
### Pageres(options?)
#### options
Type: `object`
##### delay
Type: `number` *(Seconds)*\
Default: `0`
Delay capturing the screenshot.
Useful when the site does things after load that you want to capture.
##### timeout
Type: `number` *(Seconds)*\
Default: `60`
Number of seconds after which the request is aborted.
##### crop
Type: `boolean`\
Default: `false`
Crop to the set height.
##### css
Type: `string`
Apply custom CSS to the webpage. Specify some CSS or the path to a CSS file.
##### script
Type: `string`
Apply custom JavaScript to the webpage. Specify some JavaScript or the path to a file.
##### cookies
Type: `Array<string | object>`
A string with the same format as a [browser cookie](https://developer.mozilla.org/docs/Web/HTTP/Cookies) or [an object](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetcookiecookies).
Tip: Go to the website you want a cookie for and [copy-paste it from DevTools](https://stackoverflow.com/a/24961735/64949).
##### filename
Type: `string`\
Default: `'<%= url %>-<%= size %><%= crop %>'`
Define a customized filename using [Lo-Dash templates](https://lodash.com/docs#template).\
For example: `<%= date %> - <%= url %>-<%= size %><%= crop %>`.
Available variables:
- `url`: The URL in [slugified](https://github.com/sindresorhus/filenamify-url) form, eg. `http://yeoman.io/blog/` becomes `yeoman.io!blog`
- `size`: Specified size, eg. `1024x1000`
- `width`: Width of the specified size, eg. `1024`
- `height`: Height of the specified size, eg. `1000`
- `crop`: Outputs `-cropped` when the crop option is true
- `date`: The current date (YYYY-MM-DD), eg. 2015-05-18
- `time`: The current time (HH-mm-ss), eg. 21-15-11
##### incrementalName
Type: `boolean`\
Default: `false`
When a file exists, append an incremental number.
##### selector
Type: `string`
Capture a specific DOM element matching a CSS selector.
##### hide
Type: `string[]`
Hide an array of DOM elements matching CSS selectors.
##### clickElement
Type: `string`
Click the DOM element matching the given CSS selector.
##### username
Type: `string`
Username for authenticating with HTTP auth.
##### password
Type: `string`
Password for authenticating with HTTP auth.
##### scale
Type: `number`\
Default: `1`
Scale webpage `n` times.
##### format
Type: `string`\
Default: `png`\
Values: `'png' | 'jpg'`
Image format.
##### userAgent
Type: `string`
Custom user agent.
##### headers
Type: `object`
Custom HTTP request headers.
##### transparent
Type: `boolean`\
Default: `false`
Set background color to `transparent` instead of `white` if no background is set.
##### darkMode
Type: `boolean`\
Default: `false`
Emulate preference of dark color scheme.
##### launchOptions
Type: `object`\
Default: `{}`
Options passed to [`puppeteer.launch()`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
##### beforeScreenshot
Type: `Function`
The specified function is called right before the screenshot is captured, as well as before any bounding rectangle is calculated as part of `options.element`. It receives the Puppeteer [`Page` instance](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-page) as the first argument and the [`browser` instance](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-browser) 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()`.
```js
import Pageres from 'pageres';
await new Pageres({
delay: 2,
beforeScreenshot: async (page, browser) => {
await checkSomething();
await page.click('#activate-button');
await page.waitForSelector('.finished');
}
})
.source('https://github.com/sindresorhus/pageres', ['480x320', '1024x768'], {crop: true})
.destination('screenshots')
.run();
console.log('Finished generating screenshots!');
```
### pageres.source(url, sizes, options?)
Add a page to screenshot.
#### url
*Required*\
Type: `string`
URL or local path to the website you want to screenshot. You can also use a data URI.
#### sizes
*Required*\
Type: `string[]`
Use a `<width>x<height>` notation.
#### options
Type: `object`
Options set here will take precedence over the ones set in the constructor.
### pageres.sourceHtml(html, sizes, options?)
Capture a screenshot of rendered HTML.
#### html
*Required*\
Type: `string`
HTML string to render and screenshot.
#### sizes
*Required*\
Type: `string[]`
Use a `<width>x<height>` notation.
#### options
Type: `object`
Options set here will take precedence over the ones set in the constructor.
### pageres.destination(directory)
Set the destination directory.
#### directory
Type: `string`
### pageres.run()
Run pageres.
Returns `Promise<Uint8Array[]>`.
## Task runners
Check out [grunt-pageres](https://github.com/sindresorhus/grunt-pageres) if you're using Grunt.
For Gulp and Broccoli, just use the API directly. No need for a wrapper plugin.
## Built with Pageres
- [Break Shot](https://github.com/victorferraz/break-shot) - Desktop app for capturing screenshots of responsive websites.
## Related
- [capture-website](https://github.com/sindresorhus/capture-website) - A different take on screenshotting websites