Puppeteer Options
Scully uses Puppeteer to render Angular applications and generate static HTML. The puppeteerLaunchOptions property in ScullyConfig allows you to customize how Puppeteer launches and behaves.
Overview
Puppeteer is a Node.js library that provides a high-level API to control Chrome or Chromium. Scully uses it to render your Angular application in a headless browser and extract the static HTML.
Configuration
The puppeteerLaunchOptions property accepts a PuppeteerNodeLaunchOptions object.
import { ScullyConfig } from '@scullyio/scully';
import { PuppeteerNodeLaunchOptions } from 'puppeteer';
export const config: ScullyConfig = {
puppeteerLaunchOptions: {
// Your options here
}
};
Common Options
headless
- Type:
boolean | 'new'
- Default:
true
Whether to run Chromium in headless mode.
{
puppeteerLaunchOptions: {
headless: true
}
}
Setting headless: false is useful for debugging but should not be used in production.
args
- Type:
string[]
- Default:
[]
Additional arguments to pass to the Chromium process.
{
puppeteerLaunchOptions: {
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage'
]
}
}
executablePath
Path to a Chromium or Chrome executable to use instead of the bundled Chromium.
{
puppeteerLaunchOptions: {
executablePath: '/usr/bin/chromium-browser'
}
}
defaultViewport
- Type:
{ width: number; height: number; } | null
- Default:
{ width: 800, height: 600 }
Sets a consistent viewport for all pages. Set to null to disable.
{
puppeteerLaunchOptions: {
defaultViewport: {
width: 1920,
height: 1080
}
}
}
{
puppeteerLaunchOptions: {
defaultViewport: null // Disable fixed viewport
}
}
slowMo
Slows down Puppeteer operations by the specified number of milliseconds. Useful for debugging.
{
puppeteerLaunchOptions: {
slowMo: 250 // Slow down by 250ms
}
}
timeout
- Type:
number
- Default:
30000
Maximum time in milliseconds to wait for the browser to start.
{
puppeteerLaunchOptions: {
timeout: 60000 // 60 seconds
}
}
- Type:
boolean
- Default:
false
Whether to auto-open DevTools panel for each tab. If this is true, the headless option will be set to false.
{
puppeteerLaunchOptions: {
devtools: true
}
}
ignoreHTTPSErrors
- Type:
boolean
- Default:
false
Whether to ignore HTTPS errors during navigation.
{
puppeteerLaunchOptions: {
ignoreHTTPSErrors: true
}
}
Environment-Specific Configurations
Docker/Container Environments
When running in Docker or other containerized environments, you typically need to disable the sandbox:
{
puppeteerLaunchOptions: {
args: [
'--no-sandbox',
'--disable-setuid-sandbox'
]
}
}
CI/CD Environments
For continuous integration environments with limited resources:
{
puppeteerLaunchOptions: {
headless: true,
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
'--disable-gpu',
'--disable-software-rasterizer'
]
}
}
Linux Servers
For Linux servers without a display:
{
puppeteerLaunchOptions: {
headless: true,
args: [
'--disable-gpu',
'--no-sandbox',
'--disable-setuid-sandbox'
]
}
}
Complete Examples
Development Configuration
For local development with debugging:
import { ScullyConfig } from '@scullyio/scully';
export const config: ScullyConfig = {
projectName: 'my-app',
routes: {},
puppeteerLaunchOptions: {
headless: false,
devtools: true,
slowMo: 100,
defaultViewport: {
width: 1920,
height: 1080
}
}
};
Production Configuration
For production builds:
import { ScullyConfig } from '@scullyio/scully';
export const config: ScullyConfig = {
projectName: 'my-app',
routes: {},
puppeteerLaunchOptions: {
headless: true,
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage'
],
defaultViewport: null
}
};
Custom Chromium Path
Using a specific Chromium installation:
import { ScullyConfig } from '@scullyio/scully';
export const config: ScullyConfig = {
projectName: 'my-app',
routes: {},
puppeteerLaunchOptions: {
executablePath: process.env.CHROMIUM_PATH || '/usr/bin/chromium-browser',
headless: true,
args: ['--no-sandbox']
}
};
Useful Chromium Arguments
Here are some commonly used Chromium arguments:
| Argument | Description |
|---|
--no-sandbox | Disable Chrome’s sandboxing (required in Docker) |
--disable-setuid-sandbox | Disable the setuid sandbox |
--disable-dev-shm-usage | Prevents issues with limited shared memory in Docker |
--disable-gpu | Disable GPU hardware acceleration |
--disable-software-rasterizer | Disable software rasterizer |
--disable-web-security | Disable web security (use with caution) |
--disable-features=IsolateOrigins,site-per-process | Disable site isolation |
--single-process | Run Chrome in a single process (not recommended) |
--disable-extensions | Disable extensions |
--disable-background-networking | Disable background networking |
Troubleshooting
Issue: Puppeteer fails to launch in Docker
Solution: Add the following arguments:
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage'
]
Issue: Page rendering is slow
Solution: Disable unnecessary features:
args: [
'--disable-gpu',
'--disable-software-rasterizer',
'--disable-extensions'
]
Issue: Out of memory errors
Solution: Use smaller viewport and limit resources:
{
puppeteerLaunchOptions: {
args: [
'--disable-dev-shm-usage',
'--no-sandbox'
],
defaultViewport: {
width: 1024,
height: 768
}
},
maxRenderThreads: 2 // In main config
}
Issue: HTTPS certificate errors
Solution: Ignore HTTPS errors (use only in development):
{
puppeteerLaunchOptions: {
ignoreHTTPSErrors: true
}
}
Important Warnings
Some Puppeteer settings may interfere with Scully’s rendering process and create inaccurate results. Test thoroughly when using custom options.
Never use --disable-web-security or ignoreHTTPSErrors: true in production environments as they compromise security.
The --single-process argument can cause instability and should be avoided.
Additional Resources
