Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cookies
✓ import { cookies } from 'popsicle-cookie-jar';
✗ const cookies = require('popsicle-cookie-jar').cookies;
The library primarily uses named exports. While CommonJS `require` works, the recommended approach in modern Node.js is ESM `import`.
CookieJar
✓ import { CookieJar } from 'popsicle-cookie-jar';
✗ const { CookieJar } = require('popsicle-cookie-jar');
Used for explicitly providing a custom `tough-cookie` compatible `CookieJar` instance to the middleware.
compose
✓ import { compose } from 'servie';
✗ import { compose } from 'popsicle-cookie-jar';
While used in examples for `popsicle-cookie-jar`, `compose` is a utility typically provided by `servie` itself or a similar middleware orchestration library, not directly from this package. Make sure to import it from the correct source, usually `servie`.
This quickstart demonstrates how to apply `popsicle-cookie-jar` middleware to a Popsicle client to enable automatic cookie handling, showing both default in-memory and custom `CookieJar` usage.
import { cookies, CookieJar } from "popsicle-cookie-jar";
import { compose } from 'servie';
// Assume 'transport' is another middleware, e.g., from 'popsicle-transport-http'
// For demonstration, we'll create a dummy transport and Popsicle client.
interface Context {
request: { url: string; headers?: Record<string, string>; };
response?: { status: number; headers: Record<string, string>; body?: any; };
}
async function dummyTransport(ctx: Context, next: () => Promise<void>) {
console.log(`Sending request to: ${ctx.request.url}`);
ctx.response = {
status: 200,
headers: { 'Set-Cookie': 'session=abc; Path=/; HttpOnly' },
body: 'Hello World'
};
await next();
}
// Create an in-memory cookie jar
const myCookieJar = new CookieJar();
// Compose the middleware with a custom cookie jar
const middlewareWithJar = compose([cookies(myCookieJar), dummyTransport]);
// Or let it create a default in-memory jar
const middlewareDefault = compose([cookies(), dummyTransport]);
async function makeRequest(middleware: (ctx: Context, next: () => Promise<void>) => Promise<void>) {
const ctx: Context = { request: { url: 'http://example.com/login' } };
await middleware(ctx, async () => {}); // No further middleware after transport
console.log('Response headers:', ctx.response?.headers);
console.log('Cookies in jar (after request):', myCookieJar.getCookiesSync('http://example.com/login'));
}
console.log('--- Using custom CookieJar ---');
await makeRequest(middlewareWithJar);
console.log('\n--- Using default (new) CookieJar instance for separate calls ---');
// Each call to cookies() without an argument creates a new jar
await makeRequest(compose([cookies(), dummyTransport]));
Debug
Known issues
gotchaWhen using `cookies()` without an argument, an *in-memory* `CookieJar` is created. If you create multiple middleware instances this way (e.g., for different requests or clients), they will each have their own independent cookie stores, which might not be the desired behavior for persistent sessions. To share cookies, pass the same `CookieJar` instance.fixInitialize a `new CookieJar()` once and pass that same instance to `cookies()` for all related middleware compositions: `const myJar = new CookieJar(); const mw = compose([cookies(myJar), transport()]);`
affects: >=1.0.0
breakingThe `popsicle` library (which this middleware extends) moved its core cookie functionality into `popsicle-cookie-jar` starting from `popsicle` v10.0.0. If you are upgrading `popsicle` from an older version, you must now explicitly install and include `popsicle-cookie-jar` middleware to retain cookie support.fixInstall `popsicle-cookie-jar` (`npm install popsicle-cookie-jar`) and include `cookies()` in your middleware chain: `compose([cookies(), transport()])`.
affects: >=10.0.0 of popsicle
gotchaWhile `popsicle-cookie-jar` provides cookie functionality, it relies on `tough-cookie` for the actual cookie parsing and storage logic. Developers should be aware of `tough-cookie`'s API and limitations, especially concerning cookie domain matching and path rules, as well as any security advisories related to `tough-cookie` itself.fixRegularly update `popsicle-cookie-jar` to ensure you benefit from `tough-cookie` security patches. Consult the `tough-cookie` documentation for advanced cookie management needs or debugging.
affects: >=1.0.0
deprecatedAs this package is middleware for `popsicle`, users should be aware that `popsicle` itself appears to be in a maintenance-only state with no recent feature development, suggesting this middleware will likely follow a similar pattern. Consider alternatives if active development and a robust feature roadmap are critical.fixEvaluate newer, actively maintained HTTP clients and their cookie management solutions if starting a new project or if long-term feature support is a concern.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'servie'
The `servie` package is a peer dependency but has not been installed.
fixInstall `servie`: `npm install servie`.
TypeError: Cannot read properties of undefined (reading 'headers') at cookiesMiddleware
The `popsicle-cookie-jar` middleware expects the `context.request` object to exist, typically populated by a preceding middleware or the initial Popsicle client call.
fixEnsure `popsicle-cookie-jar` is used within a valid Popsicle/Servie middleware chain where the `context.request` object is properly initialized before `cookies()` is called.
Audit
Dependencies
servierequiredPeer dependency for the core `servie` request/response interface that Popsicle builds upon.