Secure Cookie Signing: Built-in cryptographic signing using HMAC-SHA256 to prevent cookie tampering, with support for secret rotation without breaking existing cookies.
Secret Rotation Support: Seamlessly rotate signing secrets while maintaining backward compatibility with existing cookies.
Web Standards Compliant: Built on Web Crypto API and standard cookie parsing, making it runtime-agnostic (Node.js, Bun, Deno, Cloudflare Workers).

Installation

npm i remix

Usage

import { createCookie } from 'remix/cookie'

let sessionCookie = createCookie('session', {
  httpOnly: true,
  secrets: ['s3cret1'],
  secure: true,
})

cookie.name // "session"
cookie.httpOnly // true
cookie.secure // true
cookie.signed // true

// Get the value of the "session" cookie from the request's `Cookie` header
let value = await sessionCookie.parse(request.headers.get('Cookie'))

// Set the value of the cookie in a Response's `Set-Cookie` header
let response = new Response('Hello, world!', {
  headers: {
    'Set-Cookie': await sessionCookie.serialize(value),
  },
})

cookie.secure and cookie.httpOnly return undefined when those options were not configured, so middleware can distinguish defaults from explicit false. Use cookie.secure ?? false when you need a boolean. Direct serialization omits either attribute unless enabled; partitioned cookies always enable Secure.

Signing Cookies

This library supports signing cookies, which is useful for ensuring the integrity of the cookie value and preventing tampering. Signing happens automatically when you provide a secrets option to the Cookie constructor.

Secret rotation is also supported, so you can easily rotate in new secrets without breaking existing cookies.

import { Cookie } from 'remix/cookie'

// Start with a single secret
let sessionCookie = createCookie('session', {
  secrets: ['secret1'],
})

console.log(sessionCookie.signed) // true

let response = new Response('Hello, world!', {
  headers: {
    'Set-Cookie': await sessionCookie.serialize(value),
  },
})

All cookies sent in this scenario will be signed with the secret secret1. Later, when it's time to rotate secrets, add a new secret to the beginning of the array and all existing cookies will still be able to be parsed.

let sessionCookie = createCookie('session', {
  secrets: ['secret2', 'secret1'],
})

// This works for cookies signed with either secret
let value = await sessionCookie.parse(request.headers.get('Cookie'))

// Newly serialized cookies will be signed with the new secret
let response = new Response('Hello, world!', {
  headers: {
    'Set-Cookie': await sessionCookie.serialize(value),
  },
})

Custom Encoding

By default, cookie values are percent-encoded and wrapped in base64 so arbitrary string values can be safely stored in cookies. This is suitable for most use cases, but you can provide your own functions to customize the encoding and decoding of the cookie value.

let sessionCookie = createCookie('session', {
  encode: (value) => value.replaceAll(' ', '-'),
  decode: (value) => value.replaceAll('-', ' '),
})

Custom encode functions are used as the full cookie value codec. Their return values are signed when secrets are configured and then serialized as-is, without the default base64 wrapper. This can be useful for viewing the value of cookies in a human-readable format in the browser's developer tools. But you should be sure that the encoded cookie value contains only characters that are valid in a cookie value and safe for HTTP headers. Raw Unicode characters should be escaped or encoded by your custom function before they are returned.