puppyproxy

library1.1.9jsnpmunverified

puppyproxy is a Node.js library for managing, scraping, and using proxies with fetch and WebSocket support. Current stable version is 1.1.9, released in 2025. It provides built-in proxy scraping from free sources with configurable pool management, automatic rotation, and retry logic. Key differentiators include combined HTTP/HTTPS/SOCKS4/SOCKS5 support, integrated WebSocket proxy handler, and easy configuration with optional IPvanish provider support. The library ships TypeScript types and is ESM-only. Active development with monthly releases.

testing

npm install puppyproxy

package ↗

INSTALL

IMPORT

SIG · PUPPYPROXY

puppyproxy

testingjavascriptv1.1.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import PuppyProxy from 'puppyproxy'

✗ const PuppyProxy = require('puppyproxy')

Package is ESM-only. CommonJS require will fail.

PuppyProxy (type)

✓ import type PuppyProxy from 'puppyproxy'

TypeScript types are bundled. Use type-only import for type-checking.

PuppyProxyConfig

✓ import type { PuppyProxyConfig } from 'puppyproxy'

✗ import { PuppyProxyConfig } from 'puppyproxy' (value import of type)

Config interface is exported as a named type.

Initializes PuppyProxy with proxy scraping enabled, forces a collection run, then fetches IP address through a proxy.

import PuppyProxy from 'puppyproxy'; const config = { scraper: { use: true, timeBetweenScrapes: 1, maxProxiesToCheck: 100, limitProxies: 1000, timeoutPerProxy: 15, proxyTypes: ['socks5', 'http'], method: 'http', timeoutFetch: 10000, maxRetries: 3, }, }; const pp = new PuppyProxy(config); await pp.init(true); const response = await pp.request.fetch('http://ifconfig.me/ip'); console.log(await response.text());

Debug

Known issues

breakingIn v1.1.0, the API changed from constructor options to a config object. Old code using positional arguments will fail.

fix

Pass a single config object to the constructor as shown in the documentation.

affects: <1.1.0

breakingIn v1.0.0, the package switched from CommonJS to ESM-only. require() calls will throw an error.

fix

Use import statements. If CommonJS is required, use dynamic import() or downgrade to v0.x.

affects: >=1.0.0

deprecatedThe `method: 'ws'` in scraper config is deprecated as of v1.2.0 (planning). Use `method: 'http'` for better compatibility.

fix

Set scraper.method to 'http' instead of 'ws'.

affects: >=1.1.0

gotchaScraper may take a long time with high maxProxiesToCheck values; can hang Node.js process.

fix

Set maxProxiesToCheck to a reasonable number like 500 for testing. Increase timeoutMax if needed.

affects: >=0.1.0

gotchaFree proxies are unreliable; fetchBasic may fail frequently even if proxies are in pool.

fix

Use pp.request.fetch() which has built-in retry logic, or implement your own error handling.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: PuppyProxy is not a constructor

Using require() on an ESM-only package.

fix

Use import PuppyProxy from 'puppyproxy' instead of require.

Error: Cannot find module 'puppyproxy'

Package not installed or installed globally.

fix

Run npm install puppyproxy in your project directory.

SyntaxError: Unexpected token 'export'

Trying to import ESM module in a CommonJS file without using ES modules.

fix

Add "type": "module" to your package.json or rename file to .mjs.

Error: Invalid config: scraper.timeBetweenScrapes must be a number

Config property type mismatch; timeBetweenScrapes expects minutes as number.

fix

Ensure scraper.timeBetweenScrapes is a number (e.g., 45).

Upgrade

Version history

1.1.9latest on npm

Audit

Dependencies

puppylogoptionalused for logging in examples, but not a hard dependency

puppymiscoptionalprovides `wait` utility used in examples, optional

Agent activity

6 hits · last 30 days

node

Resources

packagepuppyproxy ↗