@uxomnia/n8n-nodes-puppeteer

Professional n8n community node for advanced browser automation using Puppeteer API with enterprise-grade features.

🚀 Features

🎯 22 Operations Available

• Web Scraping - Extract data with advanced selectors
• Screenshots - PNG/JPEG/WebP with quality control
• PDF Generation - Custom margins, headers, footers
• Navigation - Click, type, wait for elements
• Cookie Management - Import/export/clear cookies
• Local Storage - Get/set/clear localStorage
• Context Management - Multi-session isolation
• Network Interception - Monitor and block requests
• JavaScript Execution - Custom code evaluation

🔥 Advanced Capabilities

🎨 5 Selector Types

• CSS - .class, #id, div > span
• XPath - //div[@class="product"]
• Text - Click here (text-based selection)
• ARIA - Search button (accessibility selectors)
• Pierce - Traverse Shadow DOM

📱 Device Emulation (20+ devices)

• iPhone 13, iPhone 13 Pro, iPhone SE
• iPad Pro, iPad Mini
• Samsung Galaxy S21, Galaxy S20
• Pixel 5, Pixel 4
• Desktop Chrome, Firefox, Safari

📸 Enhanced Screenshots

• Formats: PNG, JPEG, WebP
• Quality: 0-100 (JPEG/WebP)
• Clip Area: Specific region capture
• Full Page: Entire scrollable page
• Transparent Background: PNG with alpha

📄 Advanced PDF Generation

• Landscape/Portrait orientation
• Custom margins (top, bottom, left, right)
• Header/Footer HTML templates
• Page ranges selection (1-3, 5, 7-10)
• Background graphics printing
• Custom paper formats

🌍 Professional Options

• Geolocation - Latitude, longitude, accuracy
• Permissions - Geolocation, notifications, microphone
• Slow Motion - 0-5000ms delay for debugging
• Custom Headers - User-Agent, Referer, etc.
• Locale & Timezone - fr-FR, Europe/Paris, etc.
• Block Assets - Images, CSS, fonts for speed

🔐 Security & Performance

• Stealth Mode - Anti-bot detection
• Queue Management - Backpressure protection (429)
• Context Isolation - Multi-session support
• Resource Monitoring - Memory & CPU tracking
• Retry Logic - Automatic navigation retries

📦 Installation

Prerequisites

You need a Puppeteer API server running. See puppeteer-server setup.

Option 1: Via n8n UI (Community Nodes)

Note: Only works for public npm packages. For private packages, use Option 2.

1. Go to Settings → Community Nodes
2. Click Install
3. Enter: @uxomnia/n8n-nodes-puppeteer
4. Click Install
5. Restart n8n

Option 2: Via CLI (Private Package)

# 1. Configure npm token in n8n container
export NPM_TOKEN='your-npm-token-here'

docker exec -e NPM_TOKEN="$NPM_TOKEN" -it <n8n-container-name> sh -lc '
  HOME=/home/node
  umask 077
  echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "$HOME/.npmrc"
  npm whoami
'

# 2. Install the package
docker exec -it <n8n-container-name> sh -lc '
  cd /home/node/.n8n
  npm install --omit=dev @uxomnia/n8n-nodes-puppeteer@latest
'

# 3. Restart n8n
docker restart <n8n-container-name>

🎮 Usage

1. Configure the Node

Add the PuppeteerAPI node to your workflow and configure:

• API URL: http://puppeteer:3000 (or your server URL)
• API Key: Your Puppeteer API key

2. Choose an Operation

Select from 22 available operations:

• Scrape Page
• Screenshot
• PDF
• Click
• Type Text
• Navigate
• Wait For Selector
• Evaluate
• Get/Set/Clear Cookies
• Get/Set/Clear Local Storage
• Intercept Request
• Block Resources
• Wait For Navigation
• Create/Delete/List/Clear Contexts
• Get HTML

3. Example: Simple Web Scraping

{
  "operation": "Scrape Page",
  "url": "https://example.com",
  "selector": "h1",
  "selectorType": "css",
  "waitForSelector": "h1",
  "blockAssets": true
}

Output:

{
  "success": true,
  "data": ["Example Domain"],
  "url": "https://example.com"
}

4. Example: Mobile Screenshot

{
  "operation": "Screenshot",
  "url": "https://example.com",
  "deviceEmulation": "iPhone 13",
  "imageType": "jpeg",
  "quality": 90,
  "fullPage": true
}

5. Example: XPath Scraping

{
  "operation": "Scrape Page",
  "url": "https://example.com/products",
  "selector": "//div[@class='price']",
  "selectorType": "xpath",
  "extractData": true
}

6. Example: Multi-Session with Contexts

// Node 1: Create Context
{ "operation": "Create Context", "contextId": "session-1" }

// Node 2: Scrape with context
{ "operation": "Scrape Page", "url": "...", "contextId": "session-1" }

// Node 3: Screenshot with same context
{ "operation": "Screenshot", "url": "...", "contextId": "session-1" }

// Node 4: Delete Context
{ "operation": "Delete Context", "contextId": "session-1" }

🔧 Configuration

Required Parameters

| Parameter | Type | Description | |-----------|------|-------------| | API URL | string | Puppeteer server URL | | API Key | string | API authentication key |

Common Options

| Option | Type | Description | |--------|------|-------------| | Selector Type | dropdown | CSS, XPath, Text, ARIA, Pierce | | Device Emulation | dropdown | 20+ predefined devices | | Wait For Selector | string | CSS selector to wait for | | Wait For Timeout | number | Custom timeout in ms | | Block Assets | boolean | Block images/CSS/fonts | | Custom Headers | object | Custom HTTP headers | | Cookies | array | Cookies to set | | Geolocation | object | Lat/Long coordinates | | Permissions | array | Browser permissions | | Slow Motion | number | Delay between actions (ms) |

📊 All Operations

Web Scraping

• Scrape Page - Extract text/HTML from elements
• Get HTML - Get full page HTML

Screenshots & PDFs

• Screenshot - Capture page as image
• PDF - Generate PDF document

Navigation

• Navigate - Go to URL
• Click - Click on element
• Type Text - Type into input field
• Wait For Selector - Wait for element
• Wait For Navigation - Wait for page load

Cookies

• Get Cookies - Retrieve all cookies
• Set Cookies - Set cookies
• Clear Cookies - Remove all cookies

Local Storage

• Get Local Storage - Get storage items
• Set Local Storage - Set storage item
• Clear Local Storage - Remove all items

Network

• Intercept Request - Monitor requests
• Block Resources - Block resource types

Contexts (Multi-Session)

• Create Context - New isolated session
• Delete Context - Remove session
• List Contexts - Show all sessions
• Clear Contexts - Remove all sessions

Advanced

• Evaluate - Execute custom JavaScript

🏗️ Architecture

┌─────────────┐       ┌──────────────────┐       ┌─────────────────┐
│   n8n       │       │  Puppeteer API   │       │   Chromium      │
│  Workflow   │──────▶│     Server       │──────▶│   Headless      │
│             │ HTTP  │  (Express.js)    │ Pptr  │   Browser       │
└─────────────┘       └──────────────────┘       └─────────────────┘
     │                         │
     │                         │
     ▼                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  Features: Stealth Mode, Device Emulation, Multi-Context,      │
│           Queue Management, Resource Monitoring                  │
└─────────────────────────────────────────────────────────────────┘

🔐 Security

• API Key Authentication - Secure access control
• Queue Limits - Prevent resource exhaustion
• Stealth Mode - Anti-bot detection
• Context Isolation - Separate sessions
• HTTPS Support - Encrypted communication

🐛 Troubleshooting

Plugin not appearing in n8n

1. Check installation:

docker exec <n8n-container> ls /home/node/.n8n/node_modules/@uxomnia/

2. Check n8n logs:

docker logs -f <n8n-container>

3. Restart n8n:

docker restart <n8n-container>

4. Clear browser cache (Ctrl+Shift+R)

Connection Errors

• Use http://puppeteer:3000 (Docker network) not localhost:3000
• Verify Puppeteer server is running
• Check API key is correct
• Verify both containers are on same Docker network

429 Too Many Requests

The server is overloaded. Options:

• Increase PPTR_MAX_CONCURRENCY in server
• Increase PPTR_MAX_QUEUE in server
• Add delays between workflow executions
• Use contexts to isolate sessions

📚 Documentation

• Full Documentation
• Puppeteer Server Setup
• Example Workflows
• Puppeteer API Docs

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📄 License

MIT © Alexandre Auger

🔗 Links

• GitHub Repository
• npm Package
• Report Issues
• Uxomnia

🏆 Credits

Built with:

• n8n - Workflow automation
• Puppeteer - Browser automation
• puppeteer-extra - Stealth mode

Made with ❤️ by Uxomnia | Follow us for more automation tools!