🐷 Piggy

Headless browser automation for TypeScript/Bun/Node.js.

Built on Nothing Browser — real BoringSSL TLS, fingerprint spoofing at DocumentCreation, and 100+ APIs for scraping, automation, and data extraction.

⚠️ Version Requirement: Binary v0.1.14+ | Library v0.0.20+

Update instructions | Version Compatibility

---

Quick Start

import piggy from "nothing-browser";

await piggy.launch({ mode: "tab", binary: "headless" });
await piggy.register("example", "https://example.com");

await piggy.example.navigate();
const title = await piggy.example.title();
console.log(title);

await piggy.close();

---

Why Piggy?

Feature	Piggy	Puppeteer
Library size	~50KB	~50MB
Communication	Socket (fast)	CDP (complex)
Anti-detection	Built-in	Plugins needed
Fingerprint spoofing	DocumentCreation	Runtime (detectable)
API count	100+	~50

Piggy is just a command mapper — thin wrapper around the Nothing Browser binary.

---

Known Issues & Platform Quirks

🪟 Windows: file:// URLs Must Use Triple Slash

On Windows, Qt WebEngine requires file:/// (three slashes) for local file URLs. Two slashes (file://) causes Qt to interpret the drive letter as a hostname, resulting in a silent load failure.

// ❌ Wrong — Qt thinks "C" is the hostname
`file://C:/Users/me/page.html`

// ✅ Correct
`file:///C:/Users/me/page.html`

Also make sure backslashes are converted to forward slashes:

const url = `file:///${join(pagesDir, "page.html").replace(/\\/g, "/")}`

Always prefer import.meta.dir over process.cwd() for building paths — it's always the script's own folder regardless of where you ran the script from.

---

🪟 Windows: The Pipe Bug (Named Pipe Connection Failure)

Symptom:

error: connect ENOENT \\.\pipe\piggy
   errno: -4058,
 syscall: "connect",
 address: "\\\\.\\pipe\\piggy",
    code: "ENOENT"

What happened: The Nothing Browser binary spawned successfully, but Windows didn't let it create the named pipe in time — or Windows Defender / UAC blocked the binary from running as a background process entirely.

The fix:

1. Open the folder containing your binary (e.g. piggy-playground/a/)
2. Double-click nothing-browser-headful.exe directly
3. If Windows shows a security prompt, click Run Anyway
4. Close the browser window that opens
5. Re-run your script

This whitelists the binary with Windows so it can spawn freely from scripts.

Do we know exactly why this happens? No.
Is it going to be fixed? Also no.
Does the workaround always work? Yes. Will you get such errorsfrequently in windows? Yes.

This issue only affects Windows. Linux and macOS do not require this step.

---

API Families

Core

• launch() — Start the browser
• connect() — Connect to remote server
• register() — Register a site
• close() — Shutdown

Navigation

• navigate() — Go to URL
• reload() — Refresh page
• goBack() / goForward() — History
• title() / url() / content() — Page info

Waiting

• wait.selector() — Wait for element state
• wait.function() — Wait for JS condition
• waitForResponse() — Wait for network

Interactions

• click() — Click elements
• type() — Type text
• hover() — Hover mouse
• select() — Dropdown options
• keyboard — Key presses
• mouse — Mouse movement
• scroll — Scroll page

Find — DOM Query

• find.css() / find.all() — CSS selector
• find.first() — First match
• find.byText() — By text content
• find.byAttr() — By attribute
• find.byTag() — By tag name
• find.byPlaceholder() — By input placeholder
• find.byRole() — By ARIA role
• find.closest() — Closest ancestor
• find.parent() / find.children() — DOM traversal
• find.filter() — Filter results
• find.count() / find.exists() — Count/check
• find.visible() / find.enabled() / find.checked() — State checks

Provide — Data Extraction

• provide.text() / provide.textAll() — Extract text
• provide.html() — Inner HTML
• provide.attr() / provide.attrAll() — Attributes
• provide.table() — HTML table to JSON
• provide.list() — Extract list items
• provide.links() / provide.images() — Links & images
• provide.form() — Form data
• provide.page() — Full page metadata
• provide.div() — Element structure
• provide.meta() — Meta tags
• provide.select() — Select dropdown
• provide.json() — Embedded JSON-LD

Fetch & Search (Legacy)

• fetch.text() / fetch.textAll() — Quick text
• fetch.links() / fetch.linksAll() — Quick links
• fetch.image() — Quick images
• search.css() / search.id() — DOM snapshots

Capture — Network

• capture.start() / capture.stop() — Start/stop recording
• capture.requests() — HTTP requests
• capture.ws() — WebSocket frames
• capture.cookies() — Network cookies
• capture.storage() — Local/session storage
• capture.clear() — Clear buffer

Interception

• intercept.block() — Block requests
• intercept.redirect() — Redirect
• intercept.headers() — Modify headers
• intercept.respond() — Mock responses
• intercept.modifyResponse() — Modify real responses
• intercept.clear() — Clear rules

Cookies

• cookies.set() / cookies.get() / cookies.delete() / cookies.list()

Session

• session.export() / session.import() — Save/load session
• session.reload() — Hot reload cookies/profile
• session.paths() — File paths
• session.setWsSave() / session.setPingsSave() — Persistence opt-in

Expose — RPC

• exposeFunction() — Call Node.js from browser
• exposeAndInject() — Expose + inject in one call
• piggy.expose() / piggy.unexpose() — Global functions

Iframe

• iframe.list() — List iframes
• iframe.evaluate() — Run JS in iframe
• iframe.click() / iframe.type() — Interact inside iframe
• iframe.text() / iframe.html() — Extract content
• iframe.waitSel() — Wait for selector

Captcha & Block

• captcha.status() / captcha.resolve() — Detect/solve
• captcha.pause() / captcha.check() — Manual intervention
• captcha.setAutoRetry() — Auto retry
• block.status() / block.retry() — Block detection

Dialog & Upload

• dialog.accept() / dialog.dismiss() — Handle alerts
• dialog.status() — Check pending dialog
• dialog.upload() — File upload
• dialog.waitAndAccept() / dialog.waitAndDismiss() — Await dialog

Human Mode

• human.set() / human.get() — Configure behavior
• human.type() / human.click() — Human-like interactions

Screenshot & PDF

• screenshot() — Take screenshot
• pdf() — Generate PDF
• blockImages() / unblockImages() — Image blocking

Proxy

• proxy.load() / proxy.fetch() / proxy.ovpn() — Load proxies
• proxy.set() / proxy.enable() / proxy.disable() — Configure
• proxy.test() / proxy.testStop() — Health check
• proxy.next() / proxy.rotation() — Rotate
• proxy.current() / proxy.stats() / proxy.list() — Status
• proxy.save() — Save proxy list

API Server

• api() — Register endpoint
• serve() / stopServer() — Start/stop HTTP server
• routes() — List routes
• all() / diff() — Multi-site operations

Storage

• store() — Schema-based data persistence

Tabs

• tabs.new() / tabs.list() / tabs.close()

Events

• onEvent() / site.on() — Subscribe to events
• captcha, dialog, navigate, exposed_call, proxy events

Types

• Full TypeScript definitions

---

Search for an API

Looking for something specific?

What you want	Use this
Extract text from a div	provide.text()
Get all links on a page	provide.links()
Wait for element to appear	wait.selector()
Click a button inside iframe	iframe.click()
Handle a confirm dialog	dialog.accept() / dialog.dismiss()
Upload a file	dialog.upload()
Rotate proxies	proxy.next() / proxy.rotation()
Save session to file	session.export() / session.import()
Call Node.js from browser	exposeFunction()
Solve CAPTCHA	captcha.resolve()

---

Response Samples

See exactly what each command returns with real examples:

• Find API Response Samples
• Provide API Response Samples
• Capture API Response Samples
• Proxy API Response Samples

All examples use the same sample HTML page. Responses shown are real.

---

Next Steps

• Installation — Get set up
• Quick Start — First scraper in 5 minutes
• Find API — DOM query (start here for scraping)

---

Nothing Ecosystem · Ernest Tech House · Kenya · 2026