nestjs-cookie-session

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 and passing ID of session to client via Cookie/Set-Cookie headers, you can look at nestjs-session.

Example

Register module:

// 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): Promise<NestCookieSessionOptions> => {
        return {
          session: { secret: config.secret },
        };
      },
    }),
  ],
  controllers: [ViewsController],
})
export class AppModule {}

Use in controllers with NestJS built-in Session decorator:

// views.controller.ts
import { Controller, Get, Session } from '@nestjs/common';

@Controller('views')
export class ViewsController {
  @Get()
  getViews(@Session() session: { views?: number }) {
    session.views = (session.views || 0) + 1;
    return session.views;
  }
}

To run examples:

git clone https://github.com/iamolegga/nestjs-cookie-session.git
cd nestjs-cookie-session
npm i
npm run build
cd example
npm i
npm start

---

This is the documentation for v5. Compatibility with earlier versions:

nestjs-cookie-session	NestJS	Node.js
v5	11.2+, 12	>=22.12
v4	8, 9, 10, 11	>=18

---

Install

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.
• forRoutes - optional - same as NestJS built-in MiddlewareConfigProxy['forRoutes'] See examples in official docs. 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. 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.
• 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.

Do you use this library?
Don't be shy to give it a star! ★

Also if you are into NestJS you might be interested in one of my other NestJS libs.