nestjs-puppeteer

Puppeteer module for Nest framework (node.js)

Headless Chrome provider for NestJS, enabling easy integration of Puppeteer into your application.

See Notes at the bottom of this README for caveats about headless modes, the dropped puppeteer-extra integration, and the rebrowser-puppeteer launcher.

Compatibility

| Peer dep | Supported range | Notes | | --------------------- | ------------------------- | ------------------------------------------------------------------------------------ | | Node.js | >= 20 | Matches engines.node | | @nestjs/common | ^10 \|\| ^11 | Required peer | | @nestjs/core | ^10 \|\| ^11 | Required peer | | puppeteer | ^22 \|\| ^23 \|\| ^24 | Optional peer — required at runtime unless a launcher is supplied | | rebrowser-puppeteer | ^24 | Optional peer, consumed via the launcher option |

At least one of puppeteer or a launcher-passed alternative (e.g. rebrowser-puppeteer) must be reachable at runtime. The library lazy-loads puppeteer via NestJS's loadPackage only when no launcher is configured, so consumers who always supply a launcher can omit puppeteer entirely.

CI exercises NestJS 10 + 11 against Puppeteer 23 + 24 (with rebrowser-puppeteer ^24 always present), on Node 20 / 22 / 24.

Installation

Pick the install line that matches how you intend to launch Chromium:

| Setup | Install | | ------------------------------------- | ---------------------------------------------------------------- | | Vanilla puppeteer | npm i nestjs-puppeteer puppeteer | | rebrowser-puppeteer (via launcher) | npm i nestjs-puppeteer rebrowser-puppeteer puppeteer-core | | Custom launcher | npm i nestjs-puppeteer <your-launcher> puppeteer-core |

puppeteer-core is recommended for setups that do not install puppeteer itself: it ships the Browser class identity used as the DI token (see the note at the bottom of this README) without bundling Chromium. If puppeteer is already installed you do not need puppeteer-core separately.

$ npm install --save nestjs-puppeteer puppeteer

Usage

Once the installation process is complete we can import the PuppeteerModule into the root AppModule

import { Module } from '@nestjs/common';
import { PuppeteerModule } from 'nestjs-puppeteer';

@Module({
  imports: [
    PuppeteerModule.forRoot({ headless: true }),
  ],
})
export class AppModule {}

The forRoot() method supports all the configuration properties exposed by the LaunchOptions object used by the puppeteer.launch() method. There are several extra configuration properties described below.

| Property | Description | | ------------- | ------------- | | name | Browser name | | isGlobal | Should the module be registered in the global context | | headless | true (default, runs in new headless mode), false for headed, or 'shell' to opt into the legacy chrome-headless-shell binary |

Once this is done, the Puppeteer Browser instance will be available for injection in any of the providers in the application.

import { Browser } from 'puppeteer';

@Module({
  imports: [
    PuppeteerModule.forRoot({ headless: true }),
  ],
})
export class AppModule {
  constructor(@InjectBrowser() private readonly browser: Browser) {}
}

If you used the name option when registering the module, you can inject the browser by name.

Browser context

Each root registration also creates an isolated Puppeteer BrowserContext from its registered browser. Pages registered through forFeature() are created from this context, so injected pages and the injected context share the same browser session.

import { BrowserContext, Page } from 'puppeteer';

@Module({
  imports: [
    PuppeteerModule.forRoot({ headless: true }),
    PuppeteerModule.forFeature(['page1']),
  ],
})
export class AppModule {
  constructor(
    @InjectContext() private readonly context: BrowserContext,
    @InjectPage('page1') private readonly page1: Page,
  ) {}
}

Named browser registrations use the same name when injecting the context.

@Module({
  imports: [
    PuppeteerModule.forRoot({ name: 'reports', headless: true }),
    PuppeteerModule.forFeature(['summary'], 'reports'),
  ],
})
export class ReportsModule {
  constructor(
    @InjectContext('reports') private readonly context: BrowserContext,
    @InjectPage('summary', 'reports') private readonly page: Page,
  ) {}
}

For manual lookups, use getContextToken() for the default context or getContextToken('reports') for a named browser registration.

ForFeature

After module registration, we can register specific pages for injection.

import { Module } from '@nestjs/common';
import { PuppeteerModule } from 'nestjs-puppeteer';

@Module({
  imports: [
    PuppeteerModule.forRoot({ headless: true }),
    PuppeteerModule.forFeature(['page1', 'page2']),
  ],
})
export class AppModule {}

Once this is done the Page instance will be available for injection in any of the providers in the module.

import { Page } from 'puppeteer';

@Module({
  imports: [
    PuppeteerModule.forRoot({ headless: true }),
    PuppeteerModule.forFeature(['page1', 'page2']),
  ],
})
export class AppModule {
  constructor(@InjectPage('page1') private readonly page1: Page) {}
}

Async configuration

You may want to pass your repository module options asynchronously instead of statically. In this case, use the forRootAsync() method, which provides several ways to deal with async configuration.

One approach is to use a factory function:

PuppeteerModule.forRootAsync({
  useFactory: () => ({
    headless: false,
  }),
})

Our factory behaves like any other asynchronous provider (e.g., it can be async and it's able to inject dependencies through inject).

PuppeteerModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: async (configService: ConfigService) => ({
    headless: configService.isHeadless,
  }),
  inject: [ConfigService],
})

Alternatively you can use the useClass syntax:

PuppeteerModule.forRootAsync({
  useClass: PuppeteerConfigService,
})

The construction above will instantiate PuppeteerConfigService inside PuppeteerModule and use it to provide an options object by calling createPuppeteerOptions().
Note that this means that the PuppeteerConfigService has to implement the PuppeteerOptionsFactory interface, as shown below:

@Injectable()
class PuppeteerConfigService implements PuppeteerOptionsFactory {
  createPuppeteerOptions(): PuppeteerModuleOptions {
    return {
      headless: true,
    };
  }
}

Using rebrowser-puppeteer

PuppeteerModule accepts a launcher option for swapping the bundled puppeteer for a drop-in alternative. The primary supported alternative is rebrowser-puppeteer, which applies anti-detection patches on top of upstream puppeteer.

$ npm install --save rebrowser-puppeteer

import puppeteer from 'rebrowser-puppeteer';
import { PuppeteerModule } from 'nestjs-puppeteer';

@Module({
  imports: [
    PuppeteerModule.forRoot({ launcher: puppeteer, headless: true }),
  ],
})
export class AppModule {}

The launcher option accepts any object exposing a launch(options) method, so other puppeteer-compatible builds work the same way. See Notes below for two important caveats — the Browser import gotcha and a workaround for rebrowser-puppeteer's broken postinstall.

Notes

[!IMPORTANT] Headless mode changed in Puppeteer v22. headless: true now selects Chrome's "new headless" mode; the legacy headless: 'new' literal has been removed. Pass headless: 'shell' to opt into the separate chrome-headless-shell binary if you need the legacy behaviour.

[!NOTE] puppeteer-extra integration was removed in v3.0.0. The upstream project has been inactive since 2023 and its stealth plugins target the legacy headless mode that Puppeteer v22 dropped as the default. Pin to the 2.x branch if you still need the plugin path, or migrate to rebrowser-puppeteer (see Using rebrowser-puppeteer above) for active stealth support.

[!IMPORTANT] Always import Browser from puppeteer (or puppeteer-core) — not from rebrowser-puppeteer — when using @InjectBrowser(). The decorator's DI token is the upstream Browser class identity; a class re-exported from a different package is a different token even though the two are structurally compatible at runtime. If you do not install puppeteer itself (e.g. you use rebrowser-puppeteer via the launcher option), add puppeteer-core so the upstream Browser value/type is still resolvable.

[!WARNING] rebrowser-puppeteer's postinstall is broken. It calls upstream Puppeteer's downloadBrowsers(), which downloads upstream's pinned Chromium revision rather than rebrowser's own — so the first .launch() call fails with Could not find Chrome (ver. <revision>). Trigger rebrowser's own download once after install:

$ node -e "import('rebrowser-puppeteer/internal/node/install.js').then(m => m.downloadBrowsers())"