![\"npm\"](\"https://img.shields.io/npm/v/nestjs-session\")
\n \n \n ![\"npm\"](\"https://img.shields.io/npm/dm/nestjs-session\")
\n \n \n ![\"Code](\"https://qlty.sh/gh/iamolegga/projects/nestjs-session/coverage.svg\")
\n \n \n ![\"Known](\"https://snyk.io/test/github/iamolegga/nestjs-session/badge.svg\"){kind=icon}
\n \n \n ![\"Libraries.io\"](\"https://img.shields.io/librariesio/release/npm/nestjs-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 Session Module for NestJS. Built on top of express-session 😎
\n\nThis module implements a session with storing 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.\n\nIf you want to store data directly in `Cookie`, you can look at [nestjs-cookie-session](https://github.com/iamolegga/nestjs-cookie-session).\n\n## Example\n\nRegister module:\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { NestSessionOptions, SessionModule } from 'nestjs-session';\nimport { ViewsController } from './views.controller';\n\n@Module({\n imports: [\n // sync params:\n\n SessionModule.forRoot({\n session: { secret: 'keyboard cat' },\n }),\n\n // or async:\n\n SessionModule.forRootAsync({\n imports: [ConfigModule],\n inject: [Config],\n // TIP: to get autocomplete in return object\n // add `NestSessionOptions` here ↓↓↓\n useFactory: async (config: Config): PromiseThis is the documentation for v5. Compatibility with earlier versions:
\n\n| nestjs-session | NestJS | Node.js |\n| -------------- | ------ | ------- |\n| v5 | 11.2+, 12 | >=22.12 |\n| [v4](https://github.com/iamolegga/nestjs-session/tree/4.0.0#readme) | 8, 9, 10, 11 | >=18 |\n\n---\n\n## Install\n\n```sh\nnpm i nestjs-session express-session @types/express-session\n```\n\n## API\n\n### SessionModule\n\n`SessionModule` class has two static methods, that returns `DynamicModule`, that you need to import:\n\n- `SessionModule.forRoot` for sync configuration without dependencies\n- `SessionModule.forRootAsync` for sync/async configuration with dependencies\n\n### SessionModule.forRoot\n\nAccept `NestSessionOptions`. Returns NestJS `DynamicModule` for import.\n\n### SessionModule.forRootAsync\n\nAccept `NestSessionAsyncOptions`. Returns NestJS `DynamicModule` for import.\n\n### NestSessionOptions\n\n`NestSessionOptions` is the interface of all options. It has next properties:\n\n- `session` - **required** - [express-session options](https://github.com/expressjs/session#options).\n- `forRoutes` - **optional** - same as NestJS buil-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 buil-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- `retries` - **optional** - `number` - by default if your session store lost connection to database it will return session as `undefined`, and no errors will be thrown, and then you need to check session in controller. But you can set this property how many times it should retry to get session, and on fail `InternalServerErrorException` will be thrown. If you don't want retries, but just want to `InternalServerErrorException` to be throw, then set to `0`. Set this option, if you dont't want manualy check session inside controllers.\n- `retriesStrategy` - **optional** - `(attempt: number) => number` - function that returns number of ms to wait between next attempt. Not calls on first attempt.\n\n### NestSessionAsyncOptions\n\n`NestSessionAsyncOptions` is the interface of options to create session module, that depends on other modules. It has next properties:\n\n- `imports` - **optional** - modules, that 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 `NestSessionOptions`.\n\n## Migration\n\n### v5\n\nNestJS 8, 9 and 10 are dropped: `@nestjs/common` is now a peer dependency with the range `^11.2.0 || ^12.0.0`, and Node.js >=22.12 is required. The package is also published from `dist/` with an `exports` map instead of copying the build output into the package root, so deep imports such as `nestjs-session/retriesMiddleware` no longer resolve — import from the package root.\n\nThe default route changed from `*` to `{/*splat}`, which fixes the global prefix 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 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.\n\n### v2\n\n`express-session` and `@types/express-session` are moved to peer dependencies, so you can update them independently.\n\n