Decorators for Managing Cookies with NestJS
Version Compatibility - Nest v7
For the time being at least (until I can invest more time in this), Nest v7 will be supported in the
@email@example.com code line (sorry if that's not correct SEMVER; what I mean is version
1.1.x is built on Nest 7). Nest 6 will be supported on the
1.0.x version line.
The incompatibility is due to a change in Nest's
createParamDecorator() function, and at the moment I haven't tried to figure out how to maintain compatibility across the two.
Please file an issue if you have difficulties with
v1.1.x and Nest v7.
npm install @nestjsplus/cookies
NestJS doesn't currently have decorators for getting and setting cookies. While it's not too hard to read cookies, it's convenient to have a parameter decorator to do so.
Setting cookies is a little less straightforward. You either need to utilize the platform-specific
res) object, or write an interceptor. The former is pretty straightforward, though
takes a non-Nest-like imperative style. It also puts you into
manual response mode,
meaning you can no longer rely on features like
@HttpCode() or interceptors that modify the response,
and makes testing harder (you'll have to mock the response
object, etc.). The
@SetCookies() decorator from this package wraps an interceptor
in a declarative decorator that solves these issues.
@ClearCookies() decorators in this package
provide a convenient set of features that make it easier to manage cookies in a standard and declarative way,
and minimize boilerplate code.
If you like these decorators, you may also be interested in the NestJS Redirect decorator.
Importing the Decorators
Import the decorators, just as you would other Nest decorators, in the controllers that use them as shown below:
Regular (non-signed) Cookies
@Cookies() route parameter decorator to get "regular" cookies.
get@Cookies cookies: string
This will bind an array of all (non-signed) cookies to the
See below to access a named cookie.
@SignedCookies() route parameter decorator to get signed cookies.
@Cookies(), this will bind an array of all signed cookies to the
parameter. Access individual signed cookies as described below.
Accessing Specific (Named) Cookies
Pass the name of a specific cookie in the
to access a specific cookie:
@SetCookies() route handler method decorator to set cookies.
Here's the API:
Here's how it works. You have two options, depending on whether the cookie settings are static or dynamic.
For static cookies, where the cookie name and/or value are known at compile time, you can set them in the
@SetCookies()decorator by passing a CookieSettings object.
For dynamic cookies, where the cookie name and/or value are computed at run-time, you can provide the cookie name/value pairs to be set when the route handler method runs. Provide these values by passing them on the
req._cookiesarray property. (The decorator creates the
_cookiesproperty automatically for you). Note: Of course if you are using this technique, you are de facto accessing the
requestobject, so you must bind
@Request()to a route parameter.
Defaults and overriding
You can mix and match
CookieSettings in the decorator and
in the method body as needed. This example
shows dynamic cookies with defaults inherited from the decorator, and
overrides in the body:
As a result of the above,
cookie1 will be set as
cookie2 will not.
- Set default cookie options by passing a
CookieOptionsobject in the decorator. Options set on individual cookies, if provided, override these defaults.
As shown above, each cookie you set has the shape:
options are provided for a cookie, they completely replace any options
specified in the
@SetCookies() decorator. If omitted for a cookie, they default
to options specified on the
@SetCookies() decorator, or Express's default cookie settings
if none were set.
Cookie options may be set at the method level (
@SetCookies()), providing a set of
defaults, or for individual cookies. In either case, they have the following shape:
Route Handler Results and Behavior
The route handler otherwise proceeds as normal. It can return values, and it can
use other route handler method decorators (such as
@Render()) and other route
parameter decorators (such as
Setting cookies isn't hard! See a full example here in the test folder.
Clearing (deleting) Cookies
Delete cookies in one of two ways:
@SetCookies()and pass in only the cookie name (leave the value property off of the object).
@ClearCookies(), passing in a comma separated list of cookies to clear.
These decorators currently only work with Nest applications running on
@platform-express. Fastify support is not
Note that reading cookies depends on the standard Express cookie-parser package. Be sure to install it and configure it in your app. For example:
npm install cookie-parser
and in your
Decorators Can't Access
Note that decorators have access to the
class (Controller), but not the instance. This means that, for example,
if you want to pass a variable to a
SetCookies() decorator, you should pass a variable set in the outer scope of
the file (e.g., a
const above the controller class definition), as opposed to a property on the controller class.
See the controller in the test folder for an example.
See Changelog for more information.
Contributions welcome! See Contributing.
- John Biundo (Y Prospect on Discord)
Licensed under the MIT License - see the LICENSE file for details.