Cookies

The azion/cookies module is the Azion Lib library for HTTP cookies. Its two functions read cookies from the Cookie header of a Request and set a cookie on a Response through the Set-Cookie header. They make no API calls, need no token, and return their result directly.

Install the package:

npm install azion

The azion package receives bug fixes only, and its maintenance ends in December 2026.

The functions take the standard Request and Response objects. They run in Node.js, and they run inside a function served locally with azion dev. The getCookie and setCookie samples are TypeScript ES modules run in Node.js, and they import types with import type. Both functions are also properties of the default export, cookies.

getCookie

Reads one cookie by its name, or every cookie of the request.

TypeScript

01function getCookie(req: Request, key?: string): string | undefined | Record<string, string>;

02function getCookie(req: Request, key: string, prefixOptions: CookiePrefix): string | undefined | Record<string, string>;

Parameter	Type	Required	Description
`req`	`Request`	Yes	The request that carries the `Cookie` header.
`key`	`string`	No	The name of the cookie to read. Without it, the function returns every cookie. Required when you pass `prefixOptions`.
`prefixOptions`	`CookiePrefix`	No	The name prefix of the cookie. With `host`, the function reads `__Host-<key>`; with `secure`, it reads `__Secure-<key>`.

Returns the value of the cookie as a string when you pass key, or undefined when the request has no cookie with that name. Without key, it returns a Record<string, string> of every cookie, with each name as the request sends it, prefix included.

This sample builds a request with three cookies and reads one cookie, every cookie, a __Host- cookie, and a cookie that is not there:

TypeScript

01import { getCookie } from 'azion/cookies';

03const request = new Request('https://example.com/', {

04 headers: { Cookie: 'my-cookie=cookie-value; theme=dark; __Host-session=abc123' },

05});

07console.log(getCookie(request, 'my-cookie')); // one cookie by name

08console.log(getCookie(request)); // every cookie as an object

09console.log(getCookie(request, 'session', 'host')); // reads __Host-session

10console.log(getCookie(request, 'missing')); // undefined

Output:

Text

01cookie-value

02{

03 'my-cookie': 'cookie-value',

04 theme: 'dark',

05 '__Host-session': 'abc123'

06}

07abc123

08undefined

setCookie

Sets a cookie on a response.

function setCookie(res: Response, key: string, value: string, options?: CookieOptions): Response;

Parameter	Type	Required	Description
`res`	`Response`	Yes	The response to set the cookie on.
`key`	`string`	Yes	The name of the cookie.
`value`	`string`	Yes	The value of the cookie.
`options`	`CookieOptions`	No	The attributes of the cookie.

Returns the Response with a Set-Cookie header that holds the cookie and its attributes. Return this response from your handler, so the client receives the cookie.

With prefix: 'host', set path: '/' too. Without it, setCookie throws an error with the message path option must be set to / when using host prefix.

This sample sets a cookie with five attributes, then a cookie with the host prefix, and prints each Set-Cookie header:

TypeScript

01import { setCookie } from 'azion/cookies';

02import type { CookieOptions } from 'azion/cookies';

04const response = new Response('ok');

05const options: CookieOptions = { maxAge: 3600, path: '/', httpOnly: true, secure: true, sameSite: 'Lax' };

06const res: Response = setCookie(response, 'my-cookie', 'cookie-value', options);

07console.log(res.headers.get('Set-Cookie'));

09// the 'host' prefix requires path: '/'

10const res2 = setCookie(new Response('ok'), 'session', 'abc123', { prefix: 'host', secure: true, path: '/' });

11console.log(res2.headers.get('Set-Cookie'));

Output:

Text

01my-cookie=cookie-value; HttpOnly; Max-Age=3600; Path=/; SameSite=Lax; Secure

02__Host-session=abc123; Path=/; Secure

Read and set cookies in a function

This function reads the theme cookie, falls back to light when the request has none, and sets a visited cookie on the response:

JavaScript

01import { getCookie, setCookie } from 'azion/cookies';

03export default {

04 async fetch(request) {

05 const theme = getCookie(request, 'theme') ?? 'light';

06 const response = new Response(`theme=${theme}; all=${JSON.stringify(getCookie(request))}\n`);

07 return setCookie(response, 'visited', 'true', { maxAge: 3600, path: '/', httpOnly: true });

08 },

09};

Served locally with azion dev, a request with a Cookie header and a request without one return:

Text

01$ curl -H 'Cookie: theme=dark; lang=pt' http://localhost:3333/

02HTTP/1.1 200 OK

03content-type: text/plain;charset=UTF-8

04set-cookie: visited=true; HttpOnly; Max-Age=3600; Path=/

06theme=dark; all={"theme":"dark","lang":"pt"}

08$ curl http://localhost:3333/

09HTTP/1.1 200 OK

10content-type: text/plain;charset=UTF-8

11set-cookie: visited=true; HttpOnly; Max-Age=3600; Path=/

13theme=light; all={}

Types

The module exports these types. Import them with import type.

CookieOptions

The attributes setCookie writes on the cookie.

Property	Type	Required	Description
`domain`	`string`	No	The domain the cookie is valid for.
`expires`	`Date`	No	The expiration date of the cookie.
`httpOnly`	`boolean`	No	With `true`, adds the `HttpOnly` attribute, which keeps the cookie out of reach of JavaScript in the browser through `document.cookie`.
`maxAge`	`number`	No	The maximum age of the cookie, in seconds. Written as `Max-Age`.
`path`	`string`	No	The path the client sends the cookie for. Must be `/` with `prefix: 'host'`.
`sameSite`	`'Lax' \| 'None' \| 'Strict'`	No	How the client sends the cookie with cross-site requests.
`secure`	`boolean`	No	With `true`, adds the `Secure` attribute, so the client sends the cookie over HTTPS only.
`prefix`	`CookiePrefix`	No	The name prefix. With `host`, the cookie name starts with `__Host-`.
`partitioned`	`boolean`	No	With `true`, adds the `Partitioned` attribute.