@browserless/goto

@browserless/goto: Go to a page aborting unnecessary requests.

See the Go To section on our website for more details.

Install

Using npm:

npm install @browserless/goto --save

About

This package provides advanced page navigation with built-in ad blocking, smart waiting strategies, and extensive customization options. It's the core navigation engine that powers all browserless page loading operations.

What this package does

The @browserless/goto package allows you to:

• Navigate to pages with optimized loading and smart waiting strategies
• Block ads and trackers using a precompiled Ghostery ad-blocker engine
• Inject scripts, modules, and styles into pages
• Emulate devices with viewport, user agent, and media features
• Intercept and abort requests by resource type
• Handle cookies and HTTP authentication

Usage

const createGoto = require('@browserless/goto')
const puppeteer = require('puppeteer')

const goto = createGoto({ 
  timeout: 30000,
  defaultDevice: 'Macbook Pro 13'
})

const browser = await puppeteer.launch()
const page = await browser.newPage()

const { response, device, error } = await goto(page, {
  url: 'https://example.com',
  adblock: true,
  waitUntil: 'auto'
})

Options

Smart waiting with waitUntil: 'auto'

The default 'auto' mode intelligently waits for page readiness:

// Auto mode combines 'load' with 'networkidle2' smartly
await goto(page, { url: 'https://example.com', waitUntil: 'auto' })

// Standard Puppeteer wait conditions also supported
await goto(page, { url: 'https://example.com', waitUntil: 'networkidle0' })
await goto(page, { url: 'https://example.com', waitUntil: ['load', 'domcontentloaded'] })

Built-in Ad Blocker

The package includes a precompiled Ghostery ad-blocker engine that blocks ads and trackers automatically:

// Enabled by default
await goto(page, { url: 'https://example.com', adblock: true })

// Disable for specific pages
await goto(page, { url: 'https://example.com', adblock: false })

// The adblocker can be disabled mid-session
page.disableAdblock()

Cookie consent handling (opt-out) is included as part of adblock: true and powered by duckduckgo/autoconsent.

adblock: true also dismisses generic announcement dialogs that autoconsent does not cover: ARIA dialogs (role="dialog", role="alertdialog", aria-modal, <dialog open>) with no consent language and a single acknowledge-style button ("I understand", "Got it", "OK", or an aria-label="close" button). Dialogs containing form fields are left untouched unless they expose an explicit close button, and only <button> elements are clicked so a dismissal can never navigate. It also covers notification/push opt-in overlays that carry no dialog role, such as the one AliExpress renders over its header: those are clicked only when the copy is about notifications, the overlay sits in a positioned container smaller than the viewport, it holds no form fields and no consent language, and it exposes an explicitly dismissive control ("Not now", "No permitir", "Nicht jetzt", an aria-label="close" affordance). The affirmative control ("Allow", "Permitir") is never clicked, and a control inside a link is skipped so a dismissal cannot navigate.

Notifications

Notifications are denied by default, so sites skip the overlays they render to ask for them. Notification.permission and navigator.permissions.query({ name: 'notifications' }) both read denied, the pair of values Chrome reports for a user who blocked notifications, and window.Notification stays exposed as in stock Chrome.

The permission belongs to the page's browser context and is applied on every navigation, so pages sharing a context share the value, and a page driven without goto keeps Chrome's default.

// denied (default)
await goto(page, { url: 'https://example.com' })

// Chrome's out-of-the-box state, where `Notification.permission` reads `default`
await goto(page, { url: 'https://example.com', notifications: true })

Script and style injection

Inject external resources or inline code:

await goto(page, {
  url: 'https://example.com',
  // External URLs
  scripts: ['https://cdn.example.com/library.js'],
  // ES modules
  modules: ['https://cdn.example.com/module.mjs'],
  // CSS (URLs, paths, or inline)
  styles: [
    'https://cdn.example.com/styles.css',
    'body { background: red; }'
  ]
})

Request interception

Abort specific resource types to speed up navigation:

await goto(page, {
  url: 'https://example.com',
  abortTypes: ['image', 'stylesheet', 'font', 'media'],
  onPageRequest: (request, page) => {
    console.log('Request:', request.url())
  }
})

Device emulation

// Use preset device
await goto(page, { url: 'https://example.com', device: 'iPhone 13' })

// Custom viewport
await goto(page, {
  url: 'https://example.com',
  viewport: { width: 1920, height: 1080 }
})

// Custom headers
await goto(page, {
  url: 'https://example.com',
  headers: {
    'user-agent': 'custom-agent',
    'cookie': 'session=abc123'
  }
})

Return value

The goto function returns:

const { response, device, error } = await goto(page, { url })

// response: Puppeteer Response object (or undefined if navigation failed)
// device: { userAgent, viewport } used for the request
// error: Error object if navigation failed

How it fits in the monorepo

This is the core navigation engine used by the entire browserless ecosystem:

Dependencies

License

@browserless/goto © Microlink, released under the MIT License.
Authored and maintained by Microlink with help from contributors.

The logo has been designed by xinh studio.

microlink.io · GitHub microlinkhq · X @microlinkhq