next-session

Lightweight promise-based session middleware for Next.js. Also works in micro or Node.js HTTP Server, Express, and more.

Also check out alternatives like next-iron-session. Take a look at nextjs-mongodb-app to see this module in use.

Installation

// NPM
npm install next-session
// Yarn
yarn add next-session

Usage

:point_right: Upgrading from v1.x to v2.x? Please read the release notes here!

:point_right: Upgrading from v2.x to v3.x? Please read the release notes here!

:point_right: Upgrading from v3.x to v4.x? Please read the release notes here!

Warning The default session store (if

options?.store

undefined

MemoryStore

// ./lib/get-session.js
import nextSession from "next-session";
export const getSession = nextSession(options);

API Routes

import { getSession } from "./lib/get-session.js";

export default function handler(req, res) {
  const session = await getSession(req, res);
  session.views = session.views ? session.views + 1 : 1;
  // Also available under req.session:
  // req.session.views = req.session.views ? req.session.views + 1 : 1;
  res.send(
    In this session, you have visited this website ${session.views} time(s).
  );
}

Usage in API Routes may result in

API resolved without sending a response

import nextSession from "next-session";
const getSession = nextSession();

export default function handler(req, res) {
  const session = await getSession(req, res);
  /* ... */
}
export const config = {
  api: {
    externalResolver: true,
  },
};

...or setting

options.autoCommit

false

await session.commit()

import nextSession from "next-session";
const getSession = nextSession({ autoCommit: false });

export default function handler(req, res) {
  const session = await getSession(req, res);
  /* ... */
  await session.commit();
}

getServerSideProps

import { getSession } from "./lib/get-session.js";

export default function Page({ views }) {
  return (
    
In this session, you have visited this website {views} time(s).
  );
}

export async function getServerSideProps({ req, res }) {
  const session = await getSession(req, res);
  session.views = session.views ? session.views + 1 : 1;
  // Also available under req.session:
  // req.session.views = req.session.views ? req.session.views + 1 : 1;
  return {
    props: {
      views: session.views,
    },
  };
}

Others

express, next-connect

const express = require("express");
const app = express();
app.use(async (req, res, next) => {
  await getSession(req, res); // session is set to req.session
  next();
});
app.get("/", (req, res) => {
  req.session.views = req.session.views ? req.session.views + 1 : 1;
  res.send(
    `In this session, you have visited this website ${req.session.views} time(s).`
  );
});

micro, Vercel Serverless Functions

module.exports = (req, res) => {
  const session = await getSession(req, res);
  res.end(
    `In this session, you have visited this website ${session.views} time(s).`
  );
};

Node.js HTTP Server

const http = require("http");

const server = http.createServer(async (req, res) => {
  const session = await getSession(req, res);
  res.end(In this session, you have visited this website ${session.views} time(s).;
});
server.listen(8080);

Options

next-session

| options | description | default | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | name | The name of the cookie to be read from the request and set to the response. |

sid

MemoryStore

nanoid

-1

-1

session.commit()

true

Set-Cookie

false

Set-Cookie

true

Set-Cookie

/

Set-Cookie

Set-Cookie

Set-Cookie

touchAfter

Touching refers to the extension of session lifetime, both in browser (by modifying

Expires

In

autoCommit

touchAfter

encode/decode

You may supply a custom pair of function that encode/decode or encrypt/decrypt the cookie on every request.

// `express-session` signing strategy
const signature = require("cookie-signature");
const secret = "keyboard cat";
session({
  decode: (raw) => signature.unsign(raw.slice(2), secret),
  encode: (sid) => (sid ? "s:" + signature.sign(sid, secret) : null),
});

API

session object

This allows you to set or get a specific value that associates to the current session.

//  Set a value
if (loggedIn) session.user = "John Doe";
//  Get a value
const currentUser = session.user; // "John Doe"

session.touch()

Manually extends the session expiry by maxAge. Note: You must still call session.commit() if

autoCommit = false

session.touch();

If

touchAfter

session.destroy()

Destroy to current session and remove it from session store.

if (loggedOut) await session.destroy();

session.commit()

Save the session and set neccessary headers. Return Promise. It must be called before sending the headers (

res.writeHead

res.send

res.end

You must call this if

autoCommit

false

session.hello = "world";
await session.commit();
// always calling res.end or res.writeHead after the above

session.id

The unique id that associates to the current session.

Session Store

The session store to use for session middleware (see

options

Implementation

A compatible session store must include three functions:

set(sid, session)

get(sid)

destroy(sid)

touch(sid, session)

Refer to MemoryStore.

TypeScript: the

SessionStore

import type { SessionStore } from "next-session";

class CustomStore implements SessionStore {}

Compatibility with Express/Connect stores

Promisify functions

To use Express/Connect stores, you must promisify

get

set

destroy

touch

util.promisify

We include the util

promisifyStore

next-session/lib/compat

import nextSession from "next-session";
import { promisifyStore } from "next-session/lib/compat";
import SomeConnectStore from "connect-xyz";

const connectStore = new SomeConnectStore();
const getSession = nextSession({
  store: promisifyStore(connectStore),
});

You can use

expressSession

next-session/lib/compat

const session = require("express-session");
const RedisStore = require("connect-redis")(session);

// Use expressSession from next-session/lib/compat as the replacement
import { expressSession } from "next-session/lib/compat";
import RedisStoreFactory from "connect-redis";
const RedisStore = RedisStoreFactory(expressSession);

Contributing

Please see my contributing.md.

License

MIT