Skip to content

Node Unblocker: How It Works, How to Run It, and Where It Falls Short

Node Unblocker is a free, open-source Node.js proxy library that fetches pages server-side and rewrites links so follow-on requests stay routed through your server. It is useful for simple proxying and learning, but it does not hide your server IP from target sites, rotate IPs, render JavaScript, or defeat anti-bot defenses. This guide explains setup, deployment, a Puppeteer scraping example, and when a managed scraping API is the better choice.

What Node Unblocker actually does

Node Unblocker is a URL-prefix proxy with an Express-compatible API. You request a target through a path such as /proxy/https://example.com/; the library fetches it server-side, rewrites HTML and CSS URLs on the way back, and injects a small client script so navigation and assets continue through the proxy. JavaScript responses pass through unmodified, which helps explain failures on script-heavy sites.

A common misunderstanding is anonymity: the destination sees your host server's IP on every request. The tool only hides traffic from your local network, which can help with a network-level block but does not make you anonymous to the site being scraped. There is no IP pool and no rotation built in.

Version 2.3.1, published mid-2024 under AGPL-3.0, is the current release. It still installs and runs, but recent activity is automated dependency bumps rather than features or fixes, so treat it as feature-frozen.

Set up and test the proxy locally

Prerequisites: Node.js and npm installed, for example via the official Node.js guide or a version manager such as nvm.

Checklist:

  • Create a project folder, initialise npm, and install the Express and unblocker packages. See protected module code0001.
  • Require Express and the Unblocker class. See code0002.
  • Create an Express app and an Unblocker instance, setting the prefix that marks proxied paths. See code0003.
  • Mount the instance with app.use(). See code0004.
  • Start listening on the PORT environment variable, defaulting to 8080, and attach the upgrade handler so WebSocket upgrades are handled. See code0005. The complete script is in code0006.

The configuration object controls request details and middleware, so features can be enabled selectively. The example was tested on Node.js 22 with Express 4 and 5 and runs unchanged; a fresh install now pulls Express 5.

Test locally by running the script (code0007) and confirming the startup message. Prefix a target URL with localhost, the port and /proxy/ — for example http://localhost:8080/proxy/https://finescrape.com/ — and check in DevTools that requests flow through the proxy. For detailed request logs, set DEBUG as shown in code0008.

Deploy it to a public host

A localhost proxy only serves the machine it runs on. To use it as a service it needs a public URL. Heroku's former free tier no longer exists, with Eco dynos starting at $5/month, so Render's free tier is the primary walkthrough here, with a VPS as the main alternative.

Before deploying, read your host's acceptable use policy. Public open proxies attract scrutiny because anyone who finds the URL can abuse them. Policies commonly prohibit misrepresenting identity and bypassing other sites' access restrictions. Restrict the proxy to sites you need — there is no built-in allowlist, but custom request middleware can enforce one — respect robots.txt, and send a descriptive user-agent.

Render checklist:

  • Add an engines field pinning Node 22.x, a start script, and pinned dependencies to package.json. See code0009. Node 22 is an LTS release supported through April 2027; Node 16 reached end-of-life in September 2023 and should not be used for new deployments.
  • Push index.js and package.json to a Git repository, with node_modules/ in .gitignore.
  • Create a New Web Service from that repository, set build to npm install and start to npm start, choose the Free instance type, and deploy to get a public URL.
  • Test by prefixing a target with your public URL and the proxy path, as in code0010.

Free-tier limits to plan around: the service spins down after 15 minutes without traffic, so the next request pays a cold-start delay, and each workspace gets 750 free instance-hours per month. That suits testing and light use; a proxy you depend on should move to a paid instance or VPS.

Other hosts: a cheap VPS gives a fixed IP and no spin-down, but you manage the OS and process yourself, for example with pm2 or a systemd unit. Heroku still works if you already use it, at paid Eco pricing, using the same package.json and a Git or CLI deploy. Vercel is a poor fit because short-lived serverless functions with execution limits do not suit a streaming proxy that holds connections open and handles WebSocket upgrades; prefer a persistent server such as Render or a VPS.

Scrape through it with Puppeteer

On its own, Node Unblocker only relays pages. To scrape, drive it from code: install Puppeteer (code0011), then navigate to the proxy URL plus the prefixed target rather than the target directly. The example in code0012 loads a book-catalogue page through the local proxy and extracts the first three product titles; in testing those were 'A Light in the Attic', 'Tipping the Velvet' and 'Soumission'. Swap in your deployed public URL once you have one.

To spread traffic, run several instances and rotate between their URLs in round-robin fashion, as in code0013. Rotation only provides different exit IPs if each instance sits on a different host; multiple instances on one server share that server's single IP. A single provider may also route a whole region through one set of egress IPs, so spread instances across regions or providers. This avoids hammering one endpoint but is not a substitute for a real rotating-proxy pool.

Limitations to plan around

OAuth and postMessage flows: sites using OAuth forms are unlikely to work well, while standard login forms and most AJAX content do. This is unlikely to be fixed.

Complex websites: applications such as Discord, Twitter and YouTube do not work correctly; content may be missing or requests may fail. Two underlying reasons: the proxy rewrites markup but does not run a browser, so client-side JavaScript is not rendered and browser-built content arrives incomplete unless you add a headless browser such as Puppeteer; and it does nothing against anti-bot systems, so Cloudflare, DataDome and CAPTCHA challenges see a single server IP with no browser fingerprint and block it.

No IP rotation or anonymity: every request leaves from your server's one IP. With no proxy pool, a rate limit or ban on that IP stops the whole setup until you redeploy elsewhere. Multiple instances help only on different hosts. For many IPs, pair it with an external rotating or residential proxy pool, or use an API that manages rotation.

Maintenance effort: self-managed proxies require ongoing work — complying with cloud provider policies, managing instances, and handling failures — which adds up quickly, especially across large clusters.

Alternatives when Node Unblocker is not enough

Three paths go further, in rough order of how much work you hand off:

  • Headless browser with rotating proxies: Puppeteer or Playwright renders JavaScript like a real browser, and a rotating proxy pool supplies IP diversity. You still run and maintain browsers and the pool yourself.
  • A commercial web unblocker API: not the same as a plain proxy, which only swaps your IP. A web unblocker API bundles managed rotating proxies, a real headless browser for JavaScript rendering, and automatic anti-bot and CAPTCHA handling behind one endpoint, retrying and re-routing until a request succeeds.
  • A full scraping API: you send a URL and receive the page or structured data, with proxies, browser and anti-bot defences handled for you.

Decision rule: self-hosting suits readers comfortable operating servers and scraping cooperative sites. When the priority is retrieved data despite resistant targets, delegating proxy handling to a managed service is more practical.

Choosing between self-hosting and a managed API
SituationReasonable choice
Simple pages, learning, local-network blockSelf-hosted Node Unblocker
JavaScript-heavy pages, many IPs neededHeadless browser plus rotating proxies, or a managed API
Anti-bot protection, CAPTCHAs, OAuth, scaleWeb unblocker or full scraping API

Guidance only; no commercial offer is made on this page.

Frequently asked questions

Is node-unblocker free?

Yes, the library itself is open source under AGPL-3.0. Hosting and any external proxies you add are separate costs, and because no IP pool is included, a production scraping setup will normally still incur expense.

Does node-unblocker hide your IP address?

No. It hides traffic from your local network, but the destination site sees the host server's IP on every request. Anonymity toward the target requires external proxies or a managed service.

Is node-unblocker still maintained?

Only minimally. Version 2.3.1 from mid-2024 is the latest npm release, with only automated dependency updates since. Basic proxying still works, but treat it as feature-frozen and avoid relying on it for production without a fallback.

Can node-unblocker bypass Cloudflare or CAPTCHAs?

No. Cloudflare, DataDome, CAPTCHA challenges, OAuth sign-in flows and complex applications such as YouTube commonly fail. Simple to moderately complex pages are the realistic scope; protected targets need a headless browser with stealth tooling or a scraping API.

Is using node-unblocker legal?

The software itself is legal, but use matters. Check the target's terms and robots.txt, your host's acceptable use policy, and local law. Do not bypass access controls or harvest personal data, and pair the proxy with residential or datacenter proxies or a managed API if you need IP masking or rotation.

{
  "name": "proxy",
  "version": "1.0.0",
  "main": "index.js",
  "private": true,
  "engines": {
    "node": "22.x"
  },
  "dependencies": {
    "express": "^5.1.0",
    "unblocker": "^2.3.1"
  },
  "scripts": {
    "start": "node index.js"
  }
}