![\"npm\"](\"https://img.shields.io/npm/v/nestjs-cookie-session\")
\n \n \n ![\"npm\"](\"https://img.shields.io/npm/dm/nestjs-cookie-session\")
\n \n \n ![\"Code](\"https://qlty.sh/gh/iamolegga/projects/nestjs-cookie-session/coverage.svg\")
\n \n \n ![\"Known](\"https://snyk.io/test/github/iamolegga/nestjs-cookie-session/badge.svg\"){kind=icon}
\n \n \n ![\"Libraries.io\"](\"https://img.shields.io/librariesio/release/npm/nestjs-cookie-session\")
\n \n ![\"Supported](\"https://img.shields.io/badge/platforms-Express-green\"){kind=icon}
\n\n \n \n \n \n
\n \n \n \n \n \n \n
Idiomatic Cookie Session Module for NestJS. Built on top of cookie-session 😎
\n\nThis module implements a session with storing data directly in `Cookie`.\n\nIf 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).\n\n## Example\n\nRegister module:\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport {\n NestCookieSessionOptions,\n CookieSessionModule,\n} from 'nestjs-cookie-session';\nimport { ViewsController } from './views.controller';\n\n@Module({\n imports: [\n // sync params:\n\n CookieSessionModule.forRoot({\n session: { secret: 'keyboard cat' },\n }),\n\n // or async:\n\n CookieSessionModule.forRootAsync({\n imports: [ConfigModule],\n inject: [Config],\n // TIP: to get autocomplete in return object\n // add `NestCookieSessionOptions` here ↓↓↓\n useFactory: async (config: Config): PromiseThis is the documentation for v5. Compatibility with earlier versions:
\n\n| nestjs-cookie-session | NestJS | Node.js |\n| --------------------- | ------------ | ------- |\n| v5 | 11.2+, 12 | >=22.12 |\n| [v4](https://github.com/iamolegga/nestjs-cookie-session/tree/4.0.0#readme) | 8, 9, 10, 11 | >=18 |\n\n---\n\n## Install\n\n```sh\nnpm i nestjs-cookie-session cookie-session @types/cookie-session\n```\n\n## API\n\n### CookieSessionModule\n\n`CookieSessionModule` class has two static methods, that returns `DynamicModule`, that you need to import:\n\n- `CookieSessionModule.forRoot` for sync configuration without dependencies\n- `CookieSessionModule.forRootAsync` for sync/async configuration with dependencies\n\n### CookieSessionModule.forRoot\n\nAccept `NestCookieSessionOptions`. Returns NestJS `DynamicModule` for import.\n\n### CookieSessionModule.forRootAsync\n\nAccept `NestCookieSessionAsyncOptions`. Returns NestJS `DynamicModule` for import.\n\n### NestCookieSessionOptions\n\n`NestCookieSessionOptions` is the interface of all options, has next properties:\n\n- `session` - **required** - [cookie-session options](https://github.com/expressjs/cookie-session#options).\n- `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.\n- `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.\n\n### NestCookieSessionAsyncOptions\n\n`NestCookieSessionOptions` is the interface of options to create cookie session module, that depends on other modules, has next properties:\n\n- `imports` - **optional** - modules, that cookie session module depends on. See [official docs](https://docs.nestjs.com/modules).\n- `inject` - **optional** - providers from `imports`-property modules, that will be passed as arguments to `useFactory` method.\n- `useFactory` - **required** - method, that returns `NestCookieSessionOptions`.\n\n## Migration\n\n### v5\n\nRequires NestJS 11.2 or 12 and Node.js >=22.12. The package is now published\nfrom `dist/` with an `exports` map instead of copying the build output into the\npackage root, so deep imports such as `nestjs-cookie-session/index` no longer\nresolve — import from the package root.\n\nThe default route changed from `*` to `{/*splat}`, which fixes the global\nprefix root. With `app.setGlobalPrefix('v1')` and no explicit `forRoutes`:\n\n| request | before | after |\n| -------------- | -------------- | ------- |\n| `/v1` | **no session** | session |\n| `/v1/anything` | session | session |\n\nNestJS converted the old `*` into `/v1/{*path}`, which matches everything under\nthe prefix but not the prefix itself. Nothing changes if you pass your own\n`forRoutes`, or if you do not set a global prefix; paths excluded from the\nglobal prefix keep the session middleware as before.\n\n### v2\n\n`cookie-session` and `@types/cookie-session` are moved to peer dependencies, so you can update them independently.\n\n