…'
```
### .goto(page, options)
Performs a [page.goto](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.gotooptions.md) with a lot of extra capabilities:
```js
const page = await browserless.page()
const { response, device } = await browserless.goto(page, { url: 'http://example.com' })
```
#### options
Any option passed here will bypass to [page.goto](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options).
Additionally, you can setup:
##### abortTypes
type: `array`
default: `[]`
Sets the ability to abort requests based on the [ResourceType](https://github.com/puppeteer/puppeteer/blob/3db7d55d261b1e1fead7228a7ebf9825a0bcbe72/packages/puppeteer-core/src/common/HTTPRequest.ts#L68).
##### adblock
type: `boolean`
default: `true`
Enables the built-in [adblocker by](https://www.npmjs.com/package/@cliqz/adblocker) [Cliqz](https://www.npmjs.com/package/@cliqz/adblocker) that aborts unnecessary third-party requests associated with ads services.
##### animations
type: `boolean`
default: `false`
Disables CSS [animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animation) and [transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/transition), also it sets [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) consequently.
##### authenticate
type: `object`
It will be passed down to [page.authenticate](https://pptr.dev/api/puppeteer.page.authenticate), which answers every login a request asks for, from a site or from a proxy, with these credentials. For proxy credentials use [proxyServer](#proxyserver) instead, so a site never receives them.
##### click
type: `string` | `string[]`
Clicks the DOM element matching the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).
##### colorScheme
type: `string`
default: `'no-preference'`
Sets [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) CSS media feature, used to detect if the user has requested the system use a `'light'` or `'dark'` color theme.
##### device
type: `string`
default: `'macbook pro 13'`
It specifies the [device](#devices) descriptor used to retrieve `userAgent` and `viewport`.
##### headers
type: `object`
An object containing additional HTTP headers to send with every request.
```js
const browserless = require('browserless')
const page = await browserless.page()
await browserless.goto(page, {
url: 'http://example.com',
headers: {
'user-agent': 'googlebot',
cookie: 'foo=bar; hello=world'
}
})
```
This sets [`visibility: hidden`](https://stackoverflow.com/a/133064/64949) on the matched elements.
##### html
type: `string`
In case you provide HTML markup, a [page.setContent](https://github.com/puppeteer/puppeteer/blob/v5.2.1/docs/api.md#pagesetcontenthtml-options) avoiding fetch the content from the target URL.
##### javascript
type: `boolean`
default: `true`
When it's `false`, it disables JavaScript on the current page.
##### mediaType
type: `string`
default: `'screen'`
Changes the CSS media type of the page using [page.emulateMediaType](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageemulatemediamediatype).
##### modules
type: `string` | `string[]`
Injects [<script type="module">](https://v8.dev/features/modules) into the browser page.
It can accept:
- Absolute URLs (e.g., `'https://cdn.jsdelivr.net/npm/@microlink/mql@0.3.12/src/browser.js'`).
- Local file (e.g., `'local-file.js').
- Inline code (e.g., `"document.body.style.backgroundColor = 'red'"`).
```js
const buffer = await browserless.screenshot(url.toString(), {
modules: [
'https://cdn.jsdelivr.net/npm/@microlink/mql@0.3.12/src/browser.js',
'local-file.js',
"document.body.style.backgroundColor = 'red'"
]
})
```
##### onPageRequest
type:`function`
Associates a handler for every request in the page.
##### scripts
type: `string` | `string[]`
Injects [<script>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) into the browser page.
It can accept:
- Absolute URLs (e.g., `'https://cdn.jsdelivr.net/npm/@microlink/mql@0.3.12/src/browser.js'`).
- Local files (e.g., `'local-file.js').
- Inline code (e.g., `"document.body.style.backgroundColor = 'red'"`).
```js
const buffer = await browserless.screenshot(url.toString(), {
scripts: [
'https://cdn.jsdelivr.net/npm/jquery@3.4.1/dist/jquery.min.js',
'local-file.js',
"document.body.style.backgroundColor = 'red'"
]
})
```
Use [modules](#modules) whenever possible.
##### scroll
type: `string`
Scrolls to the DOM element matching the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).
##### styles
type: `string` | `string[]`
Injects [<style>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) into the browser page.
It can accept:
- Absolute URLs (e.g., `'https://cdn.jsdelivr.net/npm/hack@0.8.1/dist/dark.css'`).
- Local file (e.g., `'local-file.css').
- Inline code (e.g., `"body { background: red; }"`).
```js
const buffer = await browserless.screenshot(url.toString(), {
styles: [
'https://cdn.jsdelivr.net/npm/hack@0.8.1/dist/dark.css',
'local-file.css',
'body { background: red; }'
]
})
```
##### timezone
type: `string`
Changes the [timezone](https://source.chromium.org/chromium/chromium/deps/icu.git/+/faee8bc70570192d82d2978a71e2a615788597d1:source/data/misc/metaZones.txt?originalUrl=https:%2F%2Fcs.chromium.org%2Fchromium%2Fsrc%2Fthird_party%2Ficu%2Fsource%2Fdata%2Fmisc%2FmetaZones.txt) of the page.
##### url
type: `string`
The target URL.
##### viewport
Setups a custom viewport, using [page.setViewport](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetviewportviewport) method.
##### waitForSelector
type:`string`
Waits a quantity of time, selector or function using [page.waitForSelector](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagewaitforselectorselector-options).
##### waitForTimeout
type:`number`
Waits a quantity time in milliseconds.
##### waitUntil
type: `string` | `string[]`
default: `'auto'`
values: `'auto'` | `'load'` | `'domcontentloaded'` | `'networkidle0'` | `'networkidle2'`
Determines when the navigation is considered successful.
If an array of event strings is provided, navigation is considered successful once all events have fired.
Events can be either:
- `'auto'`: A combination of `'load'` and `'networkidle2'` in a smart way to wait the minimum time necessary.
- `'load'`: Consider navigation to be finished when the load event is fired.
- `'domcontentloaded'`: Consider navigation to be finished when the DOMContentLoaded event is fired.
- `'networkidle0'`: Consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
- `'networkidle2'`: Consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.
### .context()
Returns the [BrowserContext](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#class-browsercontext) associated with your instance.
```js
const browserContext = await browserless.context()
console.log(browserContext.id)
// => 'D2CD28FDECB1859772B9C5919E563C84'
```
### .withPage(fn, [options])
Returns a higher-order function as a convenient way to interact with a page:
```js
const getTitle = browserless.withPage((page, goto) => async opts => {
const result = await goto(page, opts)
return page.title()
})
```
The function will be invoked in the following way:
```js
const title = getTitle({ url: 'https://example.com' })
```
#### fn
type: `function`
The function to be executed. It receives `page, goto` as arguments.
#### options
##### timeout
type: `number`
default: `browserless.timeout`
This setting will change the default maximum navigation time.
### .page([name])
Returns a standalone [Page](https://github.com/puppeteer/puppeteer/blob/ddc59b247282774ccc53e3cc925efc30d4e25675/docs/api.md#class-page) associated with the current browser context.
```js
const page = await browserless.page()
await page.content()
// => ''
```
#### name
type: `string`
default: `undefined`
Optional name for the page, used in debug logs.
## Extended
### ai
The [`@browserless/ai`](https://npm.im/@browserless/ai) package runs [Chrome Built-in AI](https://developer.chrome.com/docs/ai/built-in-apis) APIs from Node.js:
```js
const createAi = require('@browserless/ai')
const createBrowser = require('browserless')
const browser = createBrowser(createAi.launch({ dir: process.env.BROWSERLESS_AI_DIR }))
const ai = createAi(async teardown => {
const browserless = await browser.createContext()
teardown(() => browserless.destroyContext())
return browserless
})
await ai.capabilities()
await ai.summarize('https://example.com', { type: 'tldr' })
await ai.prompt('https://example.com', { prompt: 'What is this page about?' })
await ai.extract('https://example.com', { schema: { type: 'object', properties: { title: { type: 'string' } } } })
await ai.translate('https://example.com', { sourceLanguage: 'en', targetLanguage: 'es' })
await ai.detectLanguage('https://example.com')
```
Each method is `(url, options)`. Input text is `options.text` when provided, otherwise `document.body.innerText` after navigation. Create options are allow-listed per method (`temperature` / `topK` for prompt, `type` / `length` for summarize, languages for translate and detect).
| Method | Chrome API |
|--------|------------|
| `capabilities` | feature detect |
| `prompt` | `LanguageModel` |
| `extract` | `LanguageModel` + schema |
| `summarize` | `Summarizer` |
| `translate` | `Translator` |
| `detectLanguage` | `LanguageDetector` |
`extract` requires `schema`. `translate` requires `sourceLanguage` and `targetLanguage`.
### function
The [`@browserless/function`](https://npm.im/@browserless/function) package provides a secure sandbox to run arbitrary JavaScript code with runtime access to a browser page:
```js
const createFunction = require('@browserless/function')()
const code = async ({ page }) => page.evaluate('jQuery.fn.jquery')
const version = createFunction(code)
const { isFulfilled, value } = await version('https://jquery.com')
// => {
// isFulfilled: true,
// value: '1.13.1'
// }
```
#### options
Besides the following properties, any other argument provided will be available during the code execution.
##### vmOpts
The hosted code runs inside a secure sandbox created via [isolated-function](https://npm.im/isolated-function).
##### gotoOpts
Any [goto#options](/#options-6) can be passed for tuning the internal URL resolution.
### lighthouse
The [`@browserless/lighthouse`](https://npm.im/@browserless/lighthouse) package provides you the setup for running [Lighthouse](https://developers.google.com/web/tools/lighthouse) reports backed by browserless.
```js
const createLighthouse = require('@browserless/lighthouse')
const createBrowser = require('browserless')
const { writeFile } = require('fs/promises')
const { onExit } = require('signal-exit')
const browser = createBrowser()
onExit(browser.close)
const lighthouse = createLighthouse(async teardown => {
const browserless = await browser.createContext()
teardown(() => browserless.destroyContext())
return browserless
})
const report = await lighthouse('https://microlink.io')
await writeFile('report.json', JSON.stringify(report, null, 2))
```
The report will be generated for the provided URL. This extends the `lighthouse:default` settings. These settings are similar to the Google Chrome Audits reports on Developer Tools.
#### options
The [Lighthouse configuration](https://github.com/GoogleChrome/lighthouse/blob/main/docs/configuration.md) that will extend `'lighthouse:default'` settings:
```js
const report = await lighthouse(url, {
onlyCategories: ['accessibility']
})
```
Also, you can extend from a different preset of settings:
```js
const report = await lighthouse(url, {
preset: 'desktop',
onlyCategories: ['accessibility']
})
```
Additionally, you can setup:
The lighthouse execution runs as a [worker thread](https://nodejs.org/api/worker_threads.html), any [worker#options](https://nodejs.org/api/worker_threads.html#new-workerfilename-options) are supported.
##### logLevel
type: `string`
default: `'error'`
values: `'silent'` | `'error'` | `'info'` | `'verbose'`
The level of logging to enable.
##### output
type: `string` | `string[]`
default: `'json'`
values: `'json'` | `'csv'` | `'html'`
The type(s) of report output to be produced.
##### timeout
type: `number`
default: `browserless.timeout`
Changes the default maximum navigation time.
### screencast
The [`@browserless/screencast`](https://npm.im/@browserless/screencast) package allows you to capture each frame of a browser navigation using puppeteer.
This API is similar to [screenshots](#screenshoturl-options), but you have a more granular control over the frame and the output:
```js
const createScreencast = require('@browserless/screencast')
const createBrowser = require('browserless')
const browser = createBrowser()
const browserless = await browser.createContext()
const page = await browserless.page()
const screencast = createScreencast(page, {
maxWidth: 1280,
maxHeight: 800
})
const frames = []
screencast.onFrame(data => frames.push(data))
screencast.start()
await browserless.goto(page, { url, waitForTimeout: 300 })
await screencast.stop()
console.log(frames)
```
See a [full example](/blob/master/packages/screencast/examples/server.js) that generates a GIF.
#### page
type: `object`
The [Page](https://pptr.dev/api/puppeteer.page) object.
#### options
See [Page.startScreencast](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-startScreencast) to know all the options and values supported.
## Packages
**browserless** is internally divided into multiple packages, this way you only use code you need.
| Package | Version |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [browserless](https://github.com/microlinkhq/browserless/tree/master/packages/browserless) | [](https://www.npmjs.com/package/browserless) |
| [@browserless/ai](https://github.com/microlinkhq/browserless/tree/master/packages/ai) | [](https://www.npmjs.com/package/@browserless/ai) |
| [@browserless/benchmark](https://github.com/microlinkhq/browserless/tree/master/packages/benchmark) | [](https://www.npmjs.com/package/@browserless/benchmark) |
| [@browserless/capture](https://github.com/microlinkhq/browserless/tree/master/packages/capture) | [](https://www.npmjs.com/package/@browserless/capture) |
| [@browserless/cli](https://github.com/microlinkhq/browserless/tree/master/packages/cli) | [](https://www.npmjs.com/package/@browserless/cli) |
| [@browserless/devices](https://github.com/microlinkhq/browserless/tree/master/packages/devices) | [](https://www.npmjs.com/package/@browserless/devices) |
| [@browserless/errors](https://github.com/microlinkhq/browserless/tree/master/packages/errors) | [](https://www.npmjs.com/package/@browserless/errors) |
| [@browserless/examples](https://github.com/microlinkhq/browserless/tree/master/packages/examples) | [](https://www.npmjs.com/package/@browserless/examples) |
| [@browserless/function](https://github.com/microlinkhq/browserless/tree/master/packages/function) | [](https://www.npmjs.com/package/@browserless/function) |
| [@browserless/goto](https://github.com/microlinkhq/browserless/tree/master/packages/goto) | [](https://www.npmjs.com/package/@browserless/goto) |
| [@browserless/lighthouse](https://github.com/microlinkhq/browserless/tree/master/packages/lighthouse) | [](https://www.npmjs.com/package/@browserless/lighthouse) |
| [@browserless/pdf](https://github.com/microlinkhq/browserless/tree/master/packages/pdf) | [](https://www.npmjs.com/package/@browserless/pdf) |
| [@browserless/screencast](https://github.com/microlinkhq/browserless/tree/master/packages/screencast) | [](https://www.npmjs.com/package/@browserless/screencast) |
| [@browserless/screenshot](https://github.com/microlinkhq/browserless/tree/master/packages/screenshot) | [](https://www.npmjs.com/package/@browserless/screenshot) |
## FAQ
**Q: Why use `browserless` over `puppeteer`?**
**browserless** does not replace Puppeteer; it complements it. It acts as a syntactic sugar layer over official Headless Chrome, optimized for production scenarios.
**Q: Is there a hosted cloud solution?**
Yes. If you don't want to manage the infrastructure of headless browsers, proxies, and antibot workarounds, use the [Microlink API](https://microlink.io) we've built.
It scales on demand, and pricing [starts for free](https://microlink.io/#pricing).
**Q: Why do you block ads scripts by default?**
Headless navigation is expensive compared to just fetching the content from a website.
To speed up the process, we block ad scripts by default because most of them are resource-intensive.
**Q: My output is different from what I expected**
**Browserless** might have been too smart and blocked a request that you need.
You can activate debug mode using `DEBUG=browserless` environment variable in order to see what is happening under the hood:
Consider opening an [issue](https://github.com/microlinkhq/browserless/issues/new) with the debug trace.
**Q: I want to use `browserless` on AWS Lambda**
Yes, check [chrome-aws-lambda](https://github.com/alixaxel/chrome-aws-lambda) to setup AWS Lambda with a binary compatible.
## License
**browserless** © [Microlink](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.
Authored and maintained by [Microlink](https://microlink.io) with help from [contributors](https://github.com/microlinkhq/browserless/contributors).
The [logo](https://thenounproject.com/term/browser/288309/) has been designed by [xinh studio](https://xinh.studio).
> [microlink.io](https://microlink.io) · GitHub [microlinkhq](https://github.com/microlinkhq) · X [@microlinkhq](https://x.com/microlinkhq)