Idiomatic Cookie Session Module for NestJS. Built on top of cookie-session 😎
This module implements a session with storing data directly in `Cookie`. If you want to store data in one of [external stores](https://github.com/expressjs/session#compatible-session-stores) and passing ID of session to client via `Cookie`/`Set-Cookie` headers, you can look at [nestjs-session](https://github.com/iamolegga/nestjs-session). ## Example Register module: ```ts // app.module.ts import { Module } from '@nestjs/common'; import { NestCookieSessionOptions, CookieSessionModule, } from 'nestjs-cookie-session'; import { ViewsController } from './views.controller'; @Module({ imports: [ // sync params: CookieSessionModule.forRoot({ session: { secret: 'keyboard cat' }, }), // or async: CookieSessionModule.forRootAsync({ imports: [ConfigModule], inject: [Config], // TIP: to get autocomplete in return object // add `NestCookieSessionOptions` here ↓↓↓ useFactory: async (config: Config): PromiseThis is the documentation for v5. Compatibility with earlier versions:
| nestjs-cookie-session | NestJS | Node.js | | --------------------- | ------------ | ------- | | v5 | 11.2+, 12 | >=22.12 | | [v4](https://github.com/iamolegga/nestjs-cookie-session/tree/4.0.0#readme) | 8, 9, 10, 11 | >=18 | --- ## Install ```sh npm i nestjs-cookie-session cookie-session @types/cookie-session ``` ## API ### CookieSessionModule `CookieSessionModule` class has two static methods, that returns `DynamicModule`, that you need to import: - `CookieSessionModule.forRoot` for sync configuration without dependencies - `CookieSessionModule.forRootAsync` for sync/async configuration with dependencies ### CookieSessionModule.forRoot Accept `NestCookieSessionOptions`. Returns NestJS `DynamicModule` for import. ### CookieSessionModule.forRootAsync Accept `NestCookieSessionAsyncOptions`. Returns NestJS `DynamicModule` for import. ### NestCookieSessionOptions `NestCookieSessionOptions` is the interface of all options, has next properties: - `session` - **required** - [cookie-session options](https://github.com/expressjs/cookie-session#options). - `forRoutes` - **optional** - same as NestJS built-in `MiddlewareConfigProxy['forRoutes']` [See examples in official docs](https://docs.nestjs.com/middleware#applying-middleware). Specify routes, that should have access to session. If `forRoutes` and `exclude` will not be set, then sessions will be set to all routes. - `exclude` - **optional** - same as NestJS built-in `MiddlewareConfigProxy['exclude']` [See examples in official docs](https://docs.nestjs.com/middleware#applying-middleware). Specify routes, that should not have access to session. If `forRoutes` and `exclude` will not be set, then sessions will be set to all routes. ### NestCookieSessionAsyncOptions `NestCookieSessionOptions` is the interface of options to create cookie session module, that depends on other modules, has next properties: - `imports` - **optional** - modules, that cookie session module depends on. See [official docs](https://docs.nestjs.com/modules). - `inject` - **optional** - providers from `imports`-property modules, that will be passed as arguments to `useFactory` method. - `useFactory` - **required** - method, that returns `NestCookieSessionOptions`. ## Migration ### v5 Requires NestJS 11.2 or 12 and Node.js >=22.12. The package is now published from `dist/` with an `exports` map instead of copying the build output into the package root, so deep imports such as `nestjs-cookie-session/index` no longer resolve — import from the package root. The default route changed from `*` to `{/*splat}`, which fixes the global prefix root. With `app.setGlobalPrefix('v1')` and no explicit `forRoutes`: | request | before | after | | -------------- | -------------- | ------- | | `/v1` | **no session** | session | | `/v1/anything` | session | session | NestJS converted the old `*` into `/v1/{*path}`, which matches everything under the prefix but not the prefix itself. Nothing changes if you pass your own `forRoutes`, or if you do not set a global prefix; paths excluded from the global prefix keep the session middleware as before. ### v2 `cookie-session` and `@types/cookie-session` are moved to peer dependencies, so you can update them independently.