next-session

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

For a more battle-tested solution, you should use express-session with next-connect instead.

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!

next-session

• session

  to be used as a Connect/Express middleware. (Use next-connect if used in Next.js)

• withSession

  to be used as HOC in Page Components or API Routes wrapper (and several others).

• applySession

  , to manually initialize

  next-session

  by providing

  req

  and

  res

  .

Use one of them to work with

next-session

(req, res)

Warning The default session store,

MemoryStore

API Routes

Usage in API Routes may result in

API resolved without sending a response

export const config = {
  api: {
    externalResolver: true,
  },
}

...or setting

options.autoCommit

false

await session.commit()

{ session }

import { session } from 'next-session';
import nextConnect from 'next-connect';

const handler = nextConnect()
  .use(session({ ...options }))
  .all(() => {
    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).
    );
  })
export default handler;

{ withSession }

import { withSession } from 'next-session';

function handler(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).
  );
}
export default withSession(handler, options);

{ applySession }

import { applySession } from 'next-session';

export default async function handler(req, res) {
  await applySession(req, res, options);
  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).
  );
}

Pages

next-session

~~

{ withSession }

(

getInitialProps

)~~

This will be deprecated in the next major release!

[email protected]>9.3.0

recommends using

getServerSideProps

instead of

getInitialProps

. Also, it is not reliable since

req

or

req.session

is only available on server only

import { withSession } from 'next-session';

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

Page.getInitialProps = ({ req }) => {
  let views;
  if (typeof window === 'undefined') {
    // req.session is only available on server-side.
    req.session.views = req.session.views ? req.session.views + 1 : 1;
    views = req.session.views;
  }
  // WARNING: On client-side routing, neither req nor req.session is available.
  return { views };
};
export default withSession(Page, options);

{ applySession }

(

getServerSideProps

)

import { applySession } from 'next-session';

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

export async function getServerSideProps({ req, res }) {
  await applySession(req, res, options);
  req.session.views = req.session.views ? req.session.views + 1 : 1;
  return {
    props: {
      views: req.session.views
    }
  }
}

Options

Regardless of the above approaches, to avoid bugs, you want to reuse the same

options

// Define the option only once
// foo/bar/session.js
export const options = { ...someOptions };

// Always import it at other places
// pages/index.js
import { options } from 'foo/bar/session';
/* ... /
export default withSession(Page, options);
// pages/api/index.js
import { options } from 'foo/bar/session';
/ ... */
await applySession(req, res, 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

req.session

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

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

req.session.destroy()

Destroy to current session and remove it from session store.

if (loggedOut) await req.session.destroy();

req.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

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

req.session.id

The unique id that associates to the current session.

req.session.isNew

Return true if the session is new.

Session Store

The session store to use for session middleware (see

options

Compatibility with Express/Connect stores

To use Express/Connect stores, you may need to use

expressSession

next-session

const session = require('express-session');
const MongoStore = require('connect-mongo')(session);

// Use expressSession as the replacement
import { expressSession } from 'next-session';
const MongoStore = require('connect-mongo')(expressSession);

Implementation

A compatible session store must include three functions:

set(sid, session)

get(sid)

destroy(sid)

touch(sid, session)

// Both of the below work!

function get(sid) {
  return promiseGetFn(sid)
}
function get(sid, done) {
  cbGetFn(sid, done);
}

Contributing

Please see my contributing.md.

License

MIT