Node.js Netscape HTTP Cookie File Parser

1.0.10 verified Thu Apr 23 auth: no javascript abandoned

The `cookiefile` package for Node.js provides utilities for reading, writing, and manipulating Netscape HTTP Cookie Files, a format commonly used by cURL and wget. It also supports parsing and generating `Set-Cookie` and `Cookie` HTTP headers for HTTP request and response contexts. The current stable version is 1.0.10, released in 2018. Due to its age, it does not support modern cookie directives such as `Max-Age` or `Same-Site`, which are crucial for contemporary web applications and security best practices. The package has seen no updates since 2018, indicating it is no longer actively maintained and may not be fully compatible with newer Node.js versions or evolving cookie specifications. Its primary utility lies in legacy systems or specific integrations requiring the exact Netscape cookie file format.

Common errors

error Error: Cannot find module 'http-cookiefile' ↓

cause The package name is `cookiefile`, but the documentation (and common mistake) refers to `http-cookiefile`.

fix

Change your import statement from require('http-cookiefile') to require('cookiefile').

error Cookie 'my_cookie' was not set with Max-Age or Same-Site attributes in generated header. ↓

cause The library does not support the `Max-Age` or `Same-Site` cookie directives, as stated in its limitations.

fix

This is a known limitation of the library. You must either avoid using these directives or manually parse/generate them outside of this package's functionality. Consider using a different, more modern cookie library if these features are critical.

Warnings

breaking The `cookiefile` package is abandoned, with its last commit in March 2018. It is not maintained for modern Node.js versions, security updates, or contemporary web standards. Using it in new projects is discouraged due to potential compatibility and security risks. ↓

fix Consider alternative, actively maintained cookie parsing libraries if possible, especially for new projects or those requiring full RFC compliance.

gotcha The README and some documentation incorrectly suggest importing from `'http-cookiefile'`. The correct package name for `require` or `import` is `'cookiefile'`. Using the wrong path will result in a 'Cannot find module' error. ↓

fix Always use `require('cookiefile')` or `import { ... } from 'cookiefile'`.

gotcha This package explicitly does not support modern cookie directives such as `Max-Age` and `Same-Site`. Cookies using these directives will not be parsed or generated correctly, which can lead to unexpected behavior or security vulnerabilities in modern web environments. ↓

fix Developers must manually handle these directives if they are critical for their application. This limitation severely restricts its use in modern web development.

Install

npm install cookiefile

yarn add cookiefile

pnpm add cookiefile

Imports

Cookie
wrong
```
const { Cookie } = require('http-cookiefile');
```
correct
```
const { Cookie } = require('cookiefile');
```
The package name is 'cookiefile', not 'http-cookiefile' as erroneously shown in older READMEs.
CookieMap
wrong
```
const { CookieMap } = require('http-cookiefile');
```
correct
```
const { CookieMap } = require('cookiefile');
```
Used for loading and managing collections of cookies, typically from a file or headers.

CookieError

wrong

const { CookieError } = require('http-cookiefile');

correct

const { CookieError } = require('cookiefile');

Custom error class for cookie-related operations.

Quickstart

This quickstart demonstrates how to create `Cookie` objects, initialize `CookieMap` from a file, add new cookies, save them to a Netscape format file, and generate HTTP `Cookie` and `Set-Cookie` headers.

import { Cookie, CookieMap } from 'cookiefile';
import * as fs from 'fs';

async function run() {
  const cookieFilePath = 'my.cookiefile';

  // 1. Create a new Cookie object
  const myCookie = new Cookie({
    domain: '.example.com',
    name: 'session_id',
    value: 'abc123def456',
    https: true,
    httpOnly: true,
    crossDomain: false,
    expire: Date.now() + (3600 * 1000) // Expires in 1 hour
  });

  // 2. Initialize a CookieMap and add the new cookie
  const cookieMap = new CookieMap();
  cookieMap.set(myCookie);

  // 3. Simulate loading from an existing Netscape cookie file
  // For this example, we'll create a dummy file first.
  const dummyCookieFileContent = `# Netscape HTTP Cookie File\n.google.com\tFALSE\t/\tFALSE\t0\tPREF\tabcde12345`;
  fs.writeFileSync('temp.cookiefile', dummyCookieFileContent);

  const loadedCookieMap = new CookieMap('temp.cookiefile');
  console.log('Loaded cookies from file:');
  loadedCookieMap.forEach((cookie, name) => console.log(` - ${name}: ${cookie.value}`));

  // Add another cookie to the loaded map
  loadedCookieMap.set(new Cookie({
    domain: '.another.com',
    name: 'user_token',
    value: 'xyz987',
    https: false,
    httpOnly: false,
    crossDomain: false,
    expire: 0 // Session cookie
  }));

  // 4. Save the combined cookies to a new file
  await loadedCookieMap.save(cookieFilePath);
  console.log(`Cookies saved to ${cookieFilePath}`);

  // 5. Generate HTTP Request/Response headers
  const requestHeader = loadedCookieMap.toRequestHeader();
  console.log('Generated Request Header:', requestHeader);

  const responseHeader = loadedCookieMap.toResponseHeader();
  console.log('Generated Response Header:', responseHeader);

  // Clean up dummy file
  fs.unlinkSync('temp.cookiefile');
}

run().catch(console.error);