1668d47b2f
See commits for details. Closes #1837, #5880, #7822, #8101, #8821, #9367, #9382, #9378, #4731
138 lines
3.2 KiB
Plaintext
138 lines
3.2 KiB
Plaintext
# Configuration
|
|
|
|
```mdx-code-block
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
```
|
|
|
|
All defaults in Puppeteer can be customized in two ways:
|
|
|
|
1. [Configuration files](#configuration-files) (**recommended**)
|
|
2. [Environment variables](#environment-variables)
|
|
|
|
:::caution
|
|
|
|
Note that some options are only customizable through environment variables (such
|
|
as `HTTPS_PROXY`).
|
|
|
|
:::
|
|
|
|
:::caution
|
|
|
|
Puppeteer's configuration files and environment variables are ignored by `puppeteer-core`.
|
|
|
|
:::
|
|
|
|
## Configuration files
|
|
|
|
Configuration files are the **recommended** choice for configuring Puppeteer.
|
|
Puppeteer will look up the file tree for any of the following formats:
|
|
|
|
- `.puppeteerrc.cjs`,
|
|
- `.puppeteerrc.js`,
|
|
- `.puppeteerrc` (YAML/JSON),
|
|
- `.puppeteerrc.json`,
|
|
- `.puppeteerrc.yaml`,
|
|
- `puppeteer.config.js`, and
|
|
- `puppeteer.config.cjs`
|
|
|
|
Puppeteer will also read a `puppeteer` key from your application's
|
|
`package.json`.
|
|
|
|
See the [`Configuration`](../api/puppeteer.configuration) interface for possible
|
|
options.
|
|
|
|
:::caution
|
|
|
|
After adding a configuration file, you may need to remove and reinstall
|
|
`puppeteer` for it to take effect if the changes affect installation.
|
|
|
|
:::
|
|
|
|
### Examples
|
|
|
|
#### Changing the default cache directory
|
|
|
|
Starting in v19.0.0, Puppeteer stores browsers in `~/.cache/puppeteer` to
|
|
globally cache browsers between installation. This can cause problems if
|
|
`puppeteer` is packed during some build step and moved to a fresh location. The
|
|
following configuration can solve this issue (reinstall `puppeteer` to take
|
|
effect):
|
|
|
|
```js title="project-directory/.puppeteerrc.cjs"
|
|
const {join} = require('path');
|
|
|
|
/**
|
|
* @type {import("puppeteer").Configuration}
|
|
*/
|
|
module.exports = {
|
|
// Changes the cache location for Puppeteer.
|
|
cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
|
|
};
|
|
```
|
|
|
|
:::note
|
|
|
|
Notice this is only possible with CommonJS configuration files as information
|
|
about the ambient environment is needed (in this case, `__dirname`).
|
|
|
|
:::
|
|
|
|
#### Enabling experiments
|
|
|
|
By default, experiments are turned off, but they can be individually turned on
|
|
using the [`experiments`](../api/puppeteer.configuration.experiments) key.
|
|
|
|
For example, if you want to enable ARM-native macOS chromium, you can use
|
|
|
|
<Tabs>
|
|
<TabItem value="CommonJS">
|
|
|
|
```js title=".puppeteerrc.cjs"
|
|
/**
|
|
* @type {import("puppeteer").Configuration}
|
|
*/
|
|
module.exports = {
|
|
experiments: {
|
|
macArmChromiumEnabled: true,
|
|
},
|
|
};
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="JSON">
|
|
|
|
```json title=".puppeteerrc.json"
|
|
{
|
|
"experiments": {
|
|
"macArmChromiumEnabled": true
|
|
}
|
|
}
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="YAML">
|
|
|
|
```yaml title=".puppeteerrc.yaml"
|
|
experiments:
|
|
macArmChromiumEnabled: true
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Environment variables
|
|
|
|
Along with configuration files, Puppeteer looks for certain
|
|
[environment variables](https://en.wikipedia.org/wiki/Environment_variable) for
|
|
customizing behavior. Environment variables will always override configuration
|
|
file options when applicable.
|
|
|
|
The following options are _environment-only_ options
|
|
|
|
- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are
|
|
used to download and run the browser.
|
|
|
|
All other options can be found in the documentation for the
|
|
[`Configuration`](../api/puppeteer.configuration) interface.
|