npm i popsicle


Simple HTTP requests for node and the browser

by serviejs

12.1.0 (see all)License:MITTypeScript:Built-In
Categories:Node.js HTTP
npm i popsicle


NPM version NPM downloads Build status Test coverage Bundle size

Advanced HTTP requests in node.js and browsers, using Servie.


npm install popsicle --save


import { fetch } from "popsicle";

const res = await fetch("http://example.com");
const data = await res.text();

Popsicle is a universal package, meaning node.js and browsers are supported without any configuration. This means the primary endpoint requires some dom types in TypeScript. When in a node.js or browser only environments prefer importing popsicle/dist/{node,browser} instead.

Popsicle re-exports Request, Response, Headers and AbortController from servie. The fetch function accepts the same arguments as Request and returns a promise that resolves to Response. You can use the Signal event emitter (from AbortController#signal) to listen to request life cycle events.


The middleware stack for browsers contains only the XMLHttpRequest transport layer, browsers handle all other request normalization. This means a smaller and faster package for browsers.


The middleware stack for node.js includes normalization to act similar to browsers:

  • Default User-Agent
  • Support for decoding compressed payloads
  • Follows HTTP redirects
  • Caches cookies in-memory

Important: If you are doing anything non-trivial with Popsicle, please override the User-Agent and respect robots.txt.


Aborting a Request

import { fetch, AbortController } from "popsicle";

const controller = new AbortController();

setTimeout(() => controller.abort(), 500);

const res = fetch("http://example.com", {
  signal: controller.signal


Transports can return an error. The built-in codes are documented below:

  • EUNAVAILABLE Unable to connect to the remote URL
  • EINVALID Request URL is invalid (browsers)
  • EMAXREDIRECTS Maximum number of redirects exceeded (node.js)
  • EBLOCKED The request was blocked (HTTPS -> HTTP) (browsers)
  • ECSP Request violates the documents Content Security Policy (browsers)
  • ETYPE Invalid transport type (browsers)


Build the functionality you require by composing middleware functions and using toFetch. See src/node.ts for an example.


Creating Plugins

See Throwback for more information:

type Plugin = (
  req: Request,
  next: () => Promise<Response>
) => Promise<Response>;


This project is written using TypeScript and publishes the types to NPM alongside the package.

  • Superagent - HTTP requests for node and browsers
  • Fetch - Browser polyfill for promise-based HTTP requests
  • Axios - HTTP request API based on Angular's $http service