@bitwild/nest-puppeteer

Puppeteer provider for NestJS with a high-level API inspired by the Cloudflare Browser Rendering REST API.

Features

• Service layer -- PuppeteerService with 7 Cloudflare-aligned methods
• REST layer -- Auto-generated endpoints with configurable prefix, guards, and feature selection
• Feature modules -- Standalone modules for individual features (PdfBrowserModule, ScreenshotBrowserModule, etc.)
• DI decorators -- @InjectBrowser(), @InjectContext(), @InjectPage() for direct Puppeteer access
• Validation -- DTOs with class-validator, registered via APP_PIPE
• Swagger -- OpenAPI decorators on all endpoints and DTOs
• Error handling -- Cloudflare-format error responses via APP_FILTER
• Testing -- createMockPuppeteerProviders() for unit tests

Installation

npm install @bitwild/nest-puppeteer puppeteer

For REST endpoints (optional):

npm install class-validator class-transformer @nestjs/swagger

Quick Start

Service-only (no REST endpoints)

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

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

Then inject the service:

import { Injectable } from '@nestjs/common';
import { PuppeteerService } from '@bitwild/nest-puppeteer';

@Injectable()
export class ReportService {
  constructor(private readonly puppeteer: PuppeteerService) {}

  async generateInvoice(url: string): Promise<Buffer> {
    return this.puppeteer.pdf({
      url,
      format: 'a4',
      printBackground: true,
      margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' },
    });
  }

  async getPageContent(url: string): Promise<string> {
    return this.puppeteer.content({
      url,
      waitForSelector: { selector: '#main-content', visible: true },
    });
  }
}

REST API endpoints

Expose Cloudflare-compatible HTTP endpoints:

import { Module } from '@nestjs/common';
import { PuppeteerModule } from '@bitwild/nest-puppeteer';
import { AuthGuard } from './auth.guard';

@Module({
  imports: [
    PuppeteerModule.forRoot({
      headless: true,
      rest: {
        prefix: 'browser-rendering',
        features: ['content', 'screenshot', 'pdf', 'markdown', 'scrape', 'links'],
        guards: [AuthGuard],
      },
    }),
  ],
})
export class AppModule {}

This registers:

| Method | Path | Description | |--------|------|-------------| | POST | /browser-rendering/content | Fetch rendered HTML | | POST | /browser-rendering/screenshot | Capture screenshot (binary) | | POST | /browser-rendering/pdf | Generate PDF (binary) | | POST | /browser-rendering/markdown | Extract Markdown | | POST | /browser-rendering/snapshot | HTML + screenshot in one call | | POST | /browser-rendering/scrape | Scrape elements by CSS selectors | | POST | /browser-rendering/links | Extract all links |

Request example:

curl -X POST http://localhost:3000/browser-rendering/pdf \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com", "format": "a4", "printBackground": true}' \
  --output document.pdf

JSON response format (content, markdown, scrape, links):

{
  "success": true,
  "result": { "html": "..." }
}

Error response format:

{
  "success": false,
  "errors": [{ "code": 400, "message": "Either \"url\" or \"html\" must be provided" }]
}

Async configuration

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { PuppeteerModule } from '@bitwild/nest-puppeteer';

@Module({
  imports: [
    PuppeteerModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        launchOptions: {
          headless: config.get('PUPPETEER_HEADLESS', true),
          args: config.get('PUPPETEER_ARGS', '').split(',').filter(Boolean),
        },
      }),
      inject: [ConfigService],
      rest: {
        prefix: 'api/browser',
        features: ['pdf', 'screenshot'],
        guards: [AuthGuard],
      },
    }),
  ],
})
export class AppModule {}

Feature Modules

Pre-configured modules for individual features with their own defaults, REST endpoint, and guards.

Standalone (single-feature app)

import { Module } from '@nestjs/common';
import { PdfBrowserModule } from '@bitwild/nest-puppeteer';

@Module({
  imports: [
    PdfBrowserModule.forRoot({
      launchOptions: { headless: true },
      defaults: {
        format: 'a4',
        printBackground: true,
        margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' },
      },
      prefix: 'api/pdf',  // POST /api/pdf
      guards: [AuthGuard],
    }),
  ],
})
export class AppModule {}

Multi-feature (shared browser)

import { Module } from '@nestjs/common';
import {
  PuppeteerModule,
  PdfBrowserModule,
  ScreenshotBrowserModule,
  ScrapeBrowserModule,
} from '@bitwild/nest-puppeteer';

@Module({
  imports: [
    // Shared browser
    PuppeteerModule.forRoot({ headless: true }),

    // Feature modules with individual config
    PdfBrowserModule.register({
      defaults: { format: 'a4', printBackground: true },
      prefix: 'api/pdf',
      guards: [AuthGuard],
    }),
    ScreenshotBrowserModule.register({
      defaults: { fullPage: true, type: 'png' },
      prefix: 'api/screenshot',
      guards: [AuthGuard],
    }),
    ScrapeBrowserModule.register({
      prefix: 'api/scrape',
      guards: [AuthGuard],
    }),
  ],
})
export class AppModule {}

Feature services

Each feature module provides a dedicated service:

| Module | Service | Method | |--------|---------|--------| | PdfBrowserModule | PdfBrowserService | .generate(options) | | ScreenshotBrowserModule | ScreenshotBrowserService | .capture(options) | | ContentBrowserModule | ContentBrowserService | .fetch(options) | | MarkdownBrowserModule | MarkdownBrowserService | .extract(options) | | SnapshotBrowserModule | SnapshotBrowserService | .take(options) | | ScrapeBrowserModule | ScrapeBrowserService | .scrape(options) | | LinksBrowserModule | LinksBrowserService | .extract(options) |

Feature services merge module defaults with per-call options:

@Injectable()
export class InvoiceService {
  constructor(private readonly pdf: PdfBrowserService) {}

  async generate(url: string): Promise<Buffer> {
    // Module defaults (format: a4, margins, etc.) applied automatically
    return this.pdf.generate({ url });
  }

  async generateLandscape(url: string): Promise<Buffer> {
    // Override specific defaults per call
    return this.pdf.generate({ url, landscape: true });
  }
}

Low-level Access

Inject Puppeteer primitives directly:

import { Injectable } from '@nestjs/common';
import { InjectBrowser, InjectPage } from '@bitwild/nest-puppeteer';
import { Browser, Page } from 'puppeteer';

@Injectable()
export class CustomService {
  constructor(
    @InjectBrowser() private readonly browser: Browser,
    @InjectPage() private readonly page: Page,
  ) {}

  async doCustomWork() {
    const page = await this.browser.newPage();
    try {
      await page.goto('https://example.com');
      // ... custom puppeteer logic
    } finally {
      await page.close();
    }
  }
}

Named pages with forFeature

@Module({
  imports: [PuppeteerModule.forFeature(['crawler', 'renderer'])],
})
export class CrawlerModule {}

// Then inject:
@Injectable()
export class CrawlerService {
  constructor(
    @InjectPage('crawler') private readonly crawlerPage: Page,
    @InjectPage('renderer') private readonly rendererPage: Page,
  ) {}
}

Multiple browser instances

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

// Inject specific instances:
@Injectable()
export class MyService {
  constructor(
    @InjectBrowser('chrome') private readonly chrome: Browser,
    @InjectBrowser('stealth') private readonly stealth: Browser,
  ) {}
}

PuppeteerService API

All methods accept a common set of options plus method-specific fields. Options are flat (not nested) to match the Cloudflare API.

Common options

interface CommonBrowserOptions {
  url?: string;                              // URL to navigate to
  html?: string;                             // HTML to render directly
  authenticate?: { username, password };     // HTTP Basic Auth
  cookies?: CookieParam[];                   // Cookies to set
  gotoOptions?: { waitUntil, timeout };      // Navigation behavior
  setExtraHTTPHeaders?: Record<string, string>;
  rejectResourceTypes?: ResourceType[];      // Block resource types
  rejectRequestPattern?: string[];           // Block URL patterns (regex)
  allowResourceTypes?: ResourceType[];       // Allow only these types
  allowRequestPattern?: string[];            // Allow only these patterns
  userAgent?: string;
  waitForSelector?: { selector, timeout?, visible? };
  waitForTimeout?: number;                   // Static delay (ms)
  viewport?: { width, height, deviceScaleFactor };
  addScriptTag?: { url?, content? }[];
  addStyleTag?: { url?, content? }[];
  setJavaScriptEnabled?: boolean;
  emulateMediaType?: string;                 // 'screen' | 'print'
}

content(options)

const html = await puppeteerService.content({
  url: 'https://example.com',
  waitForSelector: { selector: '#app', visible: true },
});

screenshot(options)

const buffer = await puppeteerService.screenshot({
  url: 'https://example.com',
  fullPage: true,
  type: 'png',
  quality: 90,            // jpeg/webp only
  omitBackground: true,
  selector: '#chart',     // screenshot a specific element
});

pdf(options)

const buffer = await puppeteerService.pdf({
  url: 'https://example.com',
  format: 'a4',
  landscape: true,
  printBackground: true,
  scale: 0.8,
  margin: { top: '2cm', bottom: '2cm', left: '1cm', right: '1cm' },
  displayHeaderFooter: true,
  headerTemplate: '<div style="font-size:10px">Header</div>',
  footerTemplate: '<div style="font-size:10px">Page <span class="pageNumber"></span></div>',
});

markdown(options)

const md = await puppeteerService.markdown({
  url: 'https://example.com/article',
  rejectResourceTypes: ['image', 'stylesheet'],
});

snapshot(options)

const { html, screenshot } = await puppeteerService.snapshot({
  url: 'https://example.com',
  fullPage: true,
  type: 'jpeg',
  quality: 80,
});

scrape(options)

const results = await puppeteerService.scrape({
  url: 'https://example.com',
  selectors: ['h1', 'p.intro', 'a[href]'],
});
// results: [{ selector: 'h1', elements: [{ text, html, attributes, width, height, top, left }] }, ...]

links(options)

const urls = await puppeteerService.links({
  url: 'https://example.com',
  visibleLinksOnly: true,
});
// urls: ['https://example.com/about', 'https://example.com/contact', ...]

Swagger

If @nestjs/swagger is installed, all endpoints and DTOs are auto-documented:

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

const app = await NestFactory.create(AppModule);

const config = new DocumentBuilder()
  .setTitle('Browser Rendering API')
  .setVersion('1.0')
  .build();

SwaggerModule.setup('docs', app, SwaggerModule.createDocument(app, config));
await app.listen(3000);

Testing

Use createMockPuppeteerProviders() to avoid launching a real browser:

import { Test } from '@nestjs/testing';
import { createMockPuppeteerProviders, PuppeteerService } from '@bitwild/nest-puppeteer';

describe('ReportService', () => {
  let service: ReportService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        ReportService,
        PuppeteerService,
        ...createMockPuppeteerProviders({
          browser: {
            newPage: jest.fn().mockResolvedValue({
              goto: jest.fn(),
              pdf: jest.fn().mockResolvedValue(Buffer.from('pdf')),
              content: jest.fn().mockResolvedValue('<html></html>'),
              close: jest.fn(),
              setViewport: jest.fn(),
            }),
          },
        }),
      ],
    }).compile();

    service = module.get(ReportService);
  });
});

Docker

Recommended launch options for containerized environments:

PuppeteerModule.forRoot({
  headless: true,
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
    '--disable-gpu',
  ],
})

License

MIT