createCookie

Create a cookie container for managing browser cookies

createCookie

Creates a logical container for managing a browser cookie from the server. A Cookie is a container for cookie metadata (name and options) with methods to parse and serialize cookie values.

Signature

function createCookie(
  name: string,
  options?: CookieOptions
): Cookie

name · string · required

The name of the cookie as it appears in the Cookie and Set-Cookie headers.

options · CookieOptions

Configuration options for the cookie.

secrets · string[]

Array of secrets used to sign/unsign cookie values. The first secret is used for signing new cookies. All secrets are tried when parsing to support secret rotation.

domain · string

Specifies the domain for the cookie. Defaults to the current domain.

path · string · default: "/"

Specifies the URL path that must exist in the requested URL for the browser to send the cookie.

maxAge · number

Maximum age of the cookie in seconds. Takes precedence over expires.

expires · Date

Expiration date of the cookie. Use maxAge instead for relative expiration.

httpOnly · boolean

When true, the cookie is inaccessible to JavaScript’s document.cookie API.

secure · boolean

When true, the cookie is only sent over HTTPS connections.

sameSite · 'lax' | 'strict' | 'none' · default: "lax"

Controls when the cookie is sent with cross-site requests.

• "strict" - Cookie is only sent for same-site requests
• "lax" - Cookie is sent for top-level navigations and same-site requests
• "none" - Cookie is sent for all requests (requires secure: true)

Returns

Cookie · object

A cookie container object with the following properties and methods:

name · string

The name of the cookie.

isSigned · boolean

true if the cookie uses one or more secrets for signing.

expires · Date | undefined

The expiration date of the cookie, calculated from maxAge or expires option.

parse · function

Parses a raw Cookie header and returns the value of this cookie or null if not present.

parse(cookieHeader: string | null, options?: ParseOptions): Promise<any>

serialize · function

Serializes a value and returns the Set-Cookie header string.

serialize(value: any, options?: SerializeOptions): Promise<string>

Basic Example

import { createCookie } from "react-router";

const cookie = createCookie("theme", {
  maxAge: 60 * 60 * 24 * 365, // 1 year
});

Parse Cookie Values

Extract cookie values from incoming requests:

filename=app/routes/theme.tsx

import { createCookie } from "react-router";
import type { Route } from "./+types/theme";

const themeCookie = createCookie("theme");

export async function loader({ request }: Route.LoaderArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const theme = await themeCookie.parse(cookieHeader);
  
  return { theme: theme || "light" };
}

Serialize Cookie Values

Set cookies in responses:

filename=app/routes/set-theme.tsx

import { createCookie } from "react-router";
import type { Route } from "./+types/set-theme";

const themeCookie = createCookie("theme", {
  maxAge: 60 * 60 * 24 * 365,
});

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const theme = formData.get("theme");
  
  return new Response(null, {
    headers: {
      "Set-Cookie": await themeCookie.serialize(theme),
    },
  });
}

Signed Cookies

Sign cookies to prevent tampering:

import { createCookie } from "react-router";

const userIdCookie = createCookie("userId", {
  secrets: ["s3cr3t-n3w", "s3cr3t-old"],
  httpOnly: true,
  secure: true,
  sameSite: "lax",
});

// Parse will verify signature
const userId = await userIdCookie.parse(cookieHeader);
// Returns null if signature is invalid

// Serialize will sign with the first secret
const setCookie = await userIdCookie.serialize("user-123");

Secret Rotation

Rotate secrets without invalidating existing cookies:

const cookie = createCookie("session", {
  secrets: [
    "new-secret-2024",  // Used for signing new cookies
    "old-secret-2023",  // Still validates old cookies
  ],
});

Override Options at Runtime

You can override cookie options when serializing:

const cookie = createCookie("prefs", {
  maxAge: 60 * 60 * 24 * 30, // 30 days default
});

// Extend expiration for premium users
const setCookie = await cookie.serialize(preferences, {
  maxAge: 60 * 60 * 24 * 365, // 1 year
});

Delete a Cookie

Set a cookie with past expiration:

const cookie = createCookie("token");

// Delete the cookie
const setCookie = await cookie.serialize("", {
  maxAge: 0,
});

return new Response(null, {
  headers: { "Set-Cookie": setCookie },
});

Complex Data Types

Cookies automatically serialize and deserialize JSON:

const preferenceCookie = createCookie("preferences");

// Serialize object
await preferenceCookie.serialize({
  theme: "dark",
  language: "en",
  notifications: true,
});

// Parse returns the object
const prefs = await preferenceCookie.parse(cookieHeader);
// { theme: "dark", language: "en", notifications: true }

Security Considerations

Always Sign Sensitive Cookies

Prevent tampering by signing cookies that contain important data:

// Bad - unsigned cookie can be modified by the client
const userCookie = createCookie("userId");

// Good - signed cookie is verified on parse
const userCookie = createCookie("userId", {
  secrets: [process.env.COOKIE_SECRET],
});

Use HttpOnly for Session Cookies

Prevent XSS attacks from accessing sensitive cookies:

const sessionCookie = createCookie("session", {
  httpOnly: true,  // JavaScript cannot access this cookie
  secure: true,    // Only sent over HTTPS
  sameSite: "lax", // CSRF protection
  secrets: [process.env.SESSION_SECRET],
});

Secure in Production

Always enable secure in production to prevent man-in-the-middle attacks:

const cookie = createCookie("data", {
  secure: process.env.NODE_ENV === "production",
});

Cookie Size Limits

Browsers limit cookie size to about 4KB. For larger data, use session storage instead:

// Bad - may exceed browser limits
const largeCookie = createCookie("data");
await largeCookie.serialize({ ...largeObject });

// Good - use session storage for large data
import { createCookieSessionStorage } from "react-router";
const sessionStorage = createCookieSessionStorage({
  cookie: { name: "session", secrets: ["secret"] },
});

Related

• createCookieSessionStorage - Store session data in cookies
• createSessionStorage - Custom session storage
• Sessions and Cookies - Sessions guide