Cookie Helper

Helper functions for managing HTTP cookies in Hono

The Cookie Helper provides utilities for getting, setting, and managing HTTP cookies, including support for signed cookies and cookie prefixes.

Import

import { getCookie, setCookie, deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie'

Functions

getCookie()

Retrieves cookie values from the request.

function getCookie(c: Context, key: string): string | undefined
function getCookie(c: Context): Cookie
function getCookie(c: Context, key: string, prefixOptions?: CookiePrefixOptions): string | undefined

c · Context · required

The Hono context object

key · string

The name of the cookie to retrieve. If omitted, returns all cookies as an object.

prefixOptions · 'secure' | 'host'

Cookie prefix option:

• 'secure': Looks for __Secure- prefixed cookie
• 'host': Looks for __Host- prefixed cookie

return · string | undefined | Cookie

The cookie value, or undefined if not found. Returns all cookies as an object when key is omitted.

Example

app.get('/cookies', (c) => {
  // Get a specific cookie
  const sessionId = getCookie(c, 'session_id')
  
  // Get all cookies
  const allCookies = getCookie(c)
  
  // Get a secure prefixed cookie
  const token = getCookie(c, 'token', 'secure') // looks for __Secure-token
  
  return c.json({ sessionId, allCookies })
})

setCookie()

Sets a cookie in the response.

function setCookie(
  c: Context,
  name: string,
  value: string,
  opt?: CookieOptions
): void

c · Context · required

The Hono context object

name · string · required

The name of the cookie

value · string · required

The value of the cookie

opt · CookieOptions

Cookie options:

• domain: Cookie domain
• expires: Expiration date
• httpOnly: HttpOnly flag
• maxAge: Max age in seconds
• path: Cookie path (defaults to /)
• secure: Secure flag
• sameSite: SameSite attribute ('Strict', 'Lax', or 'None')
• prefix: Cookie prefix ('secure' or 'host')

Example

app.post('/login', (c) => {
  // Set a basic cookie
  setCookie(c, 'session_id', 'abc123')
  
  // Set with options
  setCookie(c, 'user_token', 'xyz789', {
    path: '/',
    secure: true,
    httpOnly: true,
    maxAge: 3600,
    sameSite: 'Lax'
  })
  
  // Set with secure prefix
  setCookie(c, 'auth', 'token123', {
    prefix: 'secure' // Creates __Secure-auth cookie
  })
  
  return c.text('Logged in')
})

deleteCookie()

Deletes a cookie by setting its max age to 0.

function deleteCookie(
  c: Context,
  name: string,
  opt?: CookieOptions
): string | undefined

c · Context · required

The Hono context object

name · string · required

The name of the cookie to delete

opt · CookieOptions

Cookie options (should match the options used when setting the cookie)

return · string | undefined

The value of the deleted cookie, or undefined if it didn’t exist

Example

app.post('/logout', (c) => {
  const oldValue = deleteCookie(c, 'session_id')
  return c.text('Logged out')
})

getSignedCookie()

Retrieves and verifies signed cookies.

function getSignedCookie(
  c: Context,
  secret: string | BufferSource,
  key: string
): Promise<string | undefined | false>

function getSignedCookie(
  c: Context,
  secret: string | BufferSource
): Promise<SignedCookie>

function getSignedCookie(
  c: Context,
  secret: string | BufferSource,
  key: string,
  prefixOptions?: CookiePrefixOptions
): Promise<string | undefined | false>

c · Context · required

The Hono context object

secret · string | BufferSource · required

The secret key used to sign the cookie

key · string

The name of the cookie. If omitted, returns all signed cookies.

prefixOptions · 'secure' | 'host'

Cookie prefix option

return · Promise<string | undefined | false | SignedCookie>

Returns:

• The cookie value if signature is valid
• false if signature is invalid
• undefined if cookie doesn’t exist
• Object of all signed cookies when key is omitted

Example

app.get('/profile', async (c) => {
  const secret = 'my-secret-key'
  
  // Get a specific signed cookie
  const userId = await getSignedCookie(c, secret, 'user_id')
  
  if (userId === false) {
    return c.text('Invalid signature', 401)
  }
  
  if (!userId) {
    return c.text('Not authenticated', 401)
  }
  
  // Get all signed cookies
  const allCookies = await getSignedCookie(c, secret)
  
  return c.json({ userId })
})

setSignedCookie()

Sets a signed cookie in the response.

function setSignedCookie(
  c: Context,
  name: string,
  value: string,
  secret: string | BufferSource,
  opt?: CookieOptions
): Promise<void>

c · Context · required

The Hono context object

name · string · required

The name of the cookie

value · string · required

The value of the cookie

secret · string | BufferSource · required

The secret key used to sign the cookie

opt · CookieOptions

Cookie options (same as setCookie)

Example

app.post('/login', async (c) => {
  const secret = 'my-secret-key'
  const userId = '12345'
  
  await setSignedCookie(c, 'user_id', userId, secret, {
    httpOnly: true,
    secure: true,
    maxAge: 86400 // 24 hours
  })
  
  return c.text('Logged in')
})

Cookie Prefixes

Cookie prefixes are security features that enforce certain requirements:

• __Secure-: Cookie must be set with the secure attribute
• __Host-: Cookie must be set with secure, must have path=/, and must not have a domain attribute

// Using prefix option
setCookie(c, 'token', 'abc123', {
  prefix: 'host' // Creates __Host-token with secure=true, path=/, no domain
})

// Reading prefixed cookie
const token = getCookie(c, 'token', 'host') // Reads __Host-token

Types

interface CookieOptions {
  domain?: string
  expires?: Date
  httpOnly?: boolean
  maxAge?: number
  path?: string
  secure?: boolean
  sameSite?: 'Strict' | 'Lax' | 'None'
  prefix?: 'secure' | 'host'
}

type Cookie = Record<string, string>
type SignedCookie = Record<string, string | false>
type CookiePrefixOptions = 'secure' | 'host'