JSON Configuration

Instead of specifying the URLs to get sreenshots for and their configuration through the command line options you can do all of that in JSON file. This is the recommended method if you are getting screenshots for multiple URLs at one time.

Below is an example JSON file:

{
    "name": "{url}-{width}-{height}.png",
    "urls": [
        "https://www.aptuitiv.com",
        "https://www.aptuitiv.com/pricing",
        "https://www.aptuitiv.com"
    ],
    "sizes": ["1200x800", "800x800", "420x700"]
}

The above specifies 3 URLs to get screenshots for and 3 different viewport sizes to save each screenshot as.

NOTE: The contents of the JSON file needs to be valid JSON. Use double quotes instead of single quotes.

Validate your JSON at jsonlint.com if you're having any troubles.

JSON options

Below is a description of each of the JSON keys that you can set values for.

Only the urls value is actually required. If the others aren't set then the default values will be used.

Name	Description
baseUrl	The base URL value. If set then each URL will be appended to this value. If it's not set then it's not used and each URL should be the full URL.
clip	The X, Y, width, and height of a clip to capture instead of the full screen or specified width and height. It would be an object. For example: "clip": {x 0, y: 100, w: 800, h: 400}
delay	The number of milliseconds to delay after loading before taking a picture of the page.
dir	The directory relative to where the script is run to output the screenshots to.
fit	Whether or not to fit the the screenshot to the provided height and width.
full|fullScreen|fullscreen	Whether or not to have the screenshot capture the full width and height of the page.
height	Integer height of the viewport to take the screenshot in. Use "fit": true if you want the screenshot to only capture the viewport width and height. Defaults to 900 if no sizes are set.
hideSelector	The CSS selector of the element(s) to hide during the screenshot process. The elements are hidden before any screenshot or scrolling is done.
hideStitchSelector	The CSS selector of the element(s) to hide during the screenshot process if screenshots are stitched together. The elements are hidden after the first scroll. Common usage is to hide a sticky header or floating element.
name	The name format to use to build the file name for each screenshot. Defaults to {url}-{width} if not set.
pixelRatio	The device pixel ratio to use for the screenshot. Default is 1.
quality	The quality of the jpg image, between 0-100. Not applicable to png image. Defaults to 100.
sizes	An array of viewport sizes to get the screenshots in. Defaults to 1300x900 if not set.
scrollDelay	The number of milliseconds to delay after each scroll to allow the content to load. This is used to allow time for lazy loading of images or animations that are triggered by the scroll to complete. Defaults to 400.
stitchThreshold	This determines the maximum pixel height of the screenshot that can be taken natively before falling back to stitching screenshots together. It's based on the maximum texture size supported by Chromium's software GL backend. Visit https://webglreport.com/ in Chrome and check the 'Max Texture Size' value to see the maximum texture size supported by the browser.
type	The file type to use for the screenshots. jpg, png, or webp. Defaults to jpg if not set.
urls	An array of URLs to get screenshots for. You can either set each one as a string, or they can be a JSON object overriding configuration options for each URL.
waitUntil	The wait until value to use for the page. Allowed values are: domcontentloaded, load, networkidle0, networkidle2. Defaults to load. It is recommended to start with load and only use networkidle0 or networkidle2 if you have a specific reason to do so. An example reason could be waiting for a specific API call to complete before taking the screenshot.
width	Integer width of the viewport to take the screenshot in. Defaults to 1300 if no sizes are set.

Minimum JSON file

The minimum data that you need in the JSON file is the urls. All the other values have defaults.

Below is the bare minimum necessary in the JSON file.

{
    "urls": [
        "https://www.aptuitiv.com"
    ]
}

Initialize the JSON file

A utility command can be used to generate a boilerplate JSON file.

page-shots init

By default the JSON file will be built in the same directory that you're accessing on the command line. And by default the file name will be shots.json.

You can specify your own name for the JSON file by passing a value after the init command.

page-shots init myfile.json

Note, you don't have to specify the .json file extension. If the extension is not set or it's not equal to "json" then .json is added as the file extension.

page-shots init myfile

The above is the same as:

page-shots init myfile.json

Use the JSON configuration file

There are two ways to use the JSON configuration file.

1. Simply run page-shots on the command line with no arguments. In this case the program will look for a file called shots.json in the current directory.
2. Specify the name of the JSON file to use.

Specify the name of the JSON file to use

Use the -c or --config argument to specify the JSON config file to use. If you use this argument any other arguments are ignored.

page-shots -c myfile.json

When specifying the name of the JSON config file you don't have to include the .json extension. If the extension of the file is not .json then it's automatically added.

page-shots -c myfile

Sample JSON

Below is an example of all of the available options.

You wouldn't use all of the options as some of them override other options. For example, you wouldn't set sizes, width and height because sizes override width and height. Also, fit and full do essentially the same thing.

{
    "baseUrl": "https://www.aptuitiv.com",
    "clip": {"x": 20, "y": 105, "w": 800, "h": 400},
    "delay": 400,
    "dir": "screenshots",
    "height": 900,
    "fit": true,
    "full": false,
    "name": "site-{url}-{width}-{height}-{fit}",
    "quality": 80,
    "sizes": [
        "1500x1200",
        "1000x800",
        {
            "width": 600,
            "height": 500
        },
        {
            "width": 400,
            "height": 400,
            "fit": true,
            "name": "small-{stub}-{quality}",
            "quality": 80,
            "type": "png"
        },
        {
            "width": 800,
            "height": 400,
            "full": false,
            "dir": "medium",
            "key": "medium-shot",
            "delay": 1500,
            "name": "med-{stub}.png"
        }
    ],
    "type": "jpg",
    "urls": [
        "/",
        "/contact",
        "https://www.google.com",
        {
            "url": "/pricing",
            "delay": 0,
            "dir": "pricing-screenshots",
            "height": 400,
            "fit": false,
            "full": true,
            "name": "pricing-{width}.jpg",
            "quality": 70,
            "sizes": [
                "1200x800",
                {
                    "width": 800,
                    "height": 400,
                    "fit": true
                }
            ],
            "type": "jpg",
            "width": 1400
        }
    ],
    "width": 1000
}

As you can see in the above example both sizes and urls can be used to override configuration values.

If you use a JSON object for a size then you can also specify if the screenshot should fit the height and width. This can be done by using the fit or full option.

If you use a JSON object for a URL then you can override all other options for that individual URL.

If you use the baseUrl option but your url value starts with https:// or http:// then the baseUrl value will not be used for that URL.

Overriding configurations with the sizes values

If you use a JSON object for an individual size then you can override some of the configuration values for that individual size.

Below are the values that you can override in the size object

• delay
• dir
• fit
• full
• name
• quality
• type

You can also set the key value to specify a name for the size that can be used to replace the {size} placeholder in the dynamic file name.

See the sample JSON above for an example of how this is done.

Overriding configurations with the urls values

If you use a JSON object for an individual URL then you can override some of the configuration values for that individual URL.

If you also override configuration values with an individual size then those values will override the URL values.

Below are the values that you can override in the URLs object.

• delay
• dir
• height
• fit
• full
• name
• quality
• sizes
• type
• width

See the sample JSON above for an example of how this is done.