Simple promise-based session middleware for Next.js, micro, Express, and more
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.
// NPM npm install next-session // Yarn yarn add next-session
: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-sessionhas several named exports:
sessionto be used as a Connect/Express middleware. (Use next-connect if used in Next.js)
withSessionto be used as HOC in Page Components or API Routes wrapper (and several others).
applySession, to manually initialize
next-sessionby providing
reqand
res.
Use one of them to work with
next-session. Can also be used in other frameworks in the same manner as long as they have
(req, res)handler signature.
Warning The default session store,
MemoryStore, should not be used in production since it does not persist nor work in Serverless.
Usage in API Routes may result in
API resolved without sending a response. This can be solved by either adding:
export const config = { api: { externalResolver: true, }, }
...or setting
options.autoCommitto
falseand do
await session.commit()(See this).
{ 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).
); }
next-sessiondoes not work in Custom App since it leads to deoptimization.
{ withSession }(
getInitialProps)~~
This will be deprecated in the next major release!
[email protected]>9.3.0recommends usinggetServerSidePropsinstead ofgetInitialProps. Also, it is not reliable sincereqorreq.sessionis 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 } } }
Regardless of the above approaches, to avoid bugs, you want to reuse the same
optionsto in every route. For example:
// 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-sessionaccepts the properties below.
| options | description | default | |---------|-------------|---------| | name | The name of the cookie to be read from the request and set to the response. |
sid| | store | The session store instance to be used. |
MemoryStore| | genid | The function that generates a string for a new session ID. |
nanoid| | encode | Transforms session ID before setting cookie. It takes the raw session ID and returns the decoded/decrypted session ID. | undefined | | decode | Transforms session ID back while getting from cookie. It should return the encoded/encrypted session ID | undefined | | touchAfter | Only touch after an amount of time. Disabled by default or if set to
-1. See touchAfter. |
-1(Disabled) | | autoCommit | Automatically commit session. Disable this if you want to manually
session.commit()|
true| | cookie.secure | Specifies the boolean value for the Secure
Set-Cookieattribute. |
false| | cookie.httpOnly | Specifies the boolean value for the httpOnly
Set-Cookieattribute. |
true| | cookie.path | Specifies the value for the Path
Set-Cookieattribute. |
/| | cookie.domain | Specifies the value for the Domain
Set-Cookieattribute. | unset | | cookie.sameSite | Specifies the value for the SameSite
Set-Cookieattribute. | unset | | cookie.maxAge | (in seconds) Specifies the value for the Max-Age
Set-Cookieattribute. | unset (Browser session) |
Touching refers to the extension of session lifetime, both in browser (by modifying
Expiresattribute in Set-Cookie header) and session store (using its respective method). This prevents the session from being expired after a while.
In
autoCommitmode (which is enabled by default), for optimization, a session is only touched, not saved, if it is not modified. The value of
touchAfterallows you to skip touching if the session is still recent, thus, decreasing database load.
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), });
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"
Destroy to current session and remove it from session store.
if (loggedOut) await req.session.destroy();
Save the session and set neccessary headers. Return Promise. It must be called before sending the headers (
res.writeHead) or response (
res.send,
res.end, etc.).
You must call this if
autoCommitis set to
false.
req.session.hello = 'world'; await req.session.commit(); // always calling res.end or res.writeHead after the above
The unique id that associates to the current session.
Return true if the session is new.
The session store to use for session middleware (see
optionsabove).
To use Express/Connect stores, you may need to use
expressSessionfrom
next-sessionif the store has the following pattern.
const session = require('express-session'); const MongoStore = require('connect-mongo')(session);// Use
expressSession
as the replacementimport { expressSession } from 'next-session'; const MongoStore = require('connect-mongo')(expressSession);
A compatible session store must include three functions:
set(sid, session),
get(sid), and
destroy(sid). The function
touch(sid, session)is recommended. All functions can either return Promises or allowing callback in the last argument.
// Both of the below work!function get(sid) { return promiseGetFn(sid) }
function get(sid, done) { cbGetFn(sid, done); }
Please see my contributing.md.