capture-creative v0.0.2
capture-creative
Capture screenshots of our creatives
It uses Puppeteer (Chrome) under the hood.
Install
$ npm install capture-creative
Note to Linux users: If you get a sandbox-related 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(input, outputFilePath, options?)
Capture a screenshot of the given input
and save it to the given outputFilePath
.
Returns a Promise<void>
that resolves when the screenshot is written.
captureWebsite.buffer(input, options?)
Capture a screenshot of the given input
.
Returns a Promise<Buffer>
with the screenshot as binary.
captureWebsite.base64(input, options?)
Capture a screenshot of the given input
.
Returns a Promise<string>
with the screenshot as Base64.
input
Type: string
The URL, file URL, data URL, local file path to the website, or HTML.
const captureWebsite = require("capture-website");
(async () => {
await captureWebsite.file("index.html", "local-file.png");
})();
options
Type: object
inputType
Type: string
\
Default: 'url'
\
Values: 'url'
'html'
Set it to html
to treat input
as HTML content.
const captureWebsite = require("capture-website");
(async () => {
await captureWebsite.file("<h1>Awesome!</h1>", "screenshot.png", {
inputType: "html",
});
})();
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.
scrollToElement
Type: string | object
Scroll to the DOM element matching the given CSS selector.
element
Type: string
A CSS selector.
offsetFrom
Type: string
\
Values: 'top' | 'right' | 'bottom' | 'left'
Offset origin.
offset
Type: number
Offset in pixels.
disableAnimations
Type: boolean
\
Default: false
Disable CSS animations and transitions.
isJavaScriptEnabled
Type: boolean
\
Default: true
Whether JavaScript on the website should be executed.
This does not affect the scripts
and modules
options.
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}
.
darkMode
Type: boolean
\
Default: false
Emulate preference of dark color scheme (prefers-color-scheme
).
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 = [
["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
I'm getting a sandbox-related error
If you get an error like No usable sandbox!
or Running as root without --no-sandbox is not supported
, you need to properly set up sandboxing on your Linux instance.
Alternatively, if you completely trust the content, you can disable sandboxing (strongly discouraged):
const captureWebsite = require("capture-website");
(async () => {
await captureWebsite.file("…", "…", {
launchOptions: {
args: ["--no-sandbox", "--disable-setuid-sandbox"],
},
});
})();
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