Preference cookies
Persist a short-lived browser preference such as a theme selection.
Express.js · Function
res.cookie
res.cookie() adds a named cookie to an Express response by setting the HTTP Set-Cookie header. It accepts string or JSON-serialized object values and optional attributes for lifetime, scope, encoding, and security.
How it works
Call res.cookie() on a response to add a Set-Cookie header. The value can be text or an object that Express serializes as JSON, while the options object controls attributes such as lifetime, scope, encoding, security, and signing; the method returns the response so calls can be chained.
Syntax
res.cookie(name, value [, options])Parameters
| Name | Type | Description |
|---|---|---|
name | String | Cookie name. |
value | String | Object | Cookie value; objects are serialized as JSON. |
options | Object | undefined | Attributes for the Set-Cookie header, including domain, encode, expires, httpOnly, maxAge, path, partitioned, priority, secure, signed, and sameSite. |
Returns
Response; sets cookie name to value.
Key points
- The method adds a cookie with the supplied name and value to the outgoing response.
- Cookie values accept either strings or objects; objects are converted to JSON.
- Use maxAge when the lifetime should be expressed as a duration from the current time.
- Multiple cookies can be attached to one response by invoking the method repeatedly.
- httpOnly prevents client-side browser scripts from accessing the cookie.
- secure restricts the cookie to HTTPS requests.
- Set signed to enable signing for the cookie value.
Common mistakes
- A custom encode function must be synchronous; asynchronous encoders are not supported.
- Leaving expires unset, or setting it to 0, produces a session cookie rather than a persistent one.
- Options you omit inherit the defaults specified by RFC 6265.
Example: Set a preference cookie
const express = require('express');
const app = express();
app.get('/preferences', (req, res) => {
res.cookie('theme', 'dark', {
httpOnly: true,
maxAge: 900000,
sameSite: 'lax'
});
res.json({ok: true});
});
app.listen(3000);This route sets a cookie with server-only access, a 15-minute lifetime, and a SameSite policy before returning JSON.
When to use it
Authentication state
Issue an HTTP-only cookie for a server-managed login or session identifier.
Cookie policy configuration
Apply domain, path, expiry, SameSite, or HTTPS constraints to a cookie.
Interview questions
QWhat does res.cookie() do, and what does it return?
res.cookie() sets the response's HTTP Set-Cookie header and returns the Response object. Its value may be a string or an object, with objects serialized as JSON.
Follow-up: How would you set several cookies? Call res.cookie() multiple times on the same response; the documentation explicitly supports that pattern.
QWhich options are available for controlling a cookie?
The options object configures cookie attributes, including domain, path, expiry, maxAge, httpOnly, secure, sameSite, partitioned, priority, signed, and encode. The path defaults to /.
Follow-up: What is the difference between expires and maxAge? expires is an absolute GMT Date, while maxAge expresses expiry relative to now in milliseconds.
QHow are cookie values and encoding handled?
A string is used as the cookie value directly, while an object is serialized as JSON. The encode option selects a synchronous value-encoding function and defaults to encodeURIComponent.
Follow-up: Can encode perform asynchronous work? No; the documentation says asynchronous encoding functions are unsupported.
Related
res.clearCookie()res.set()res.get()cookie-parser