A cookie-based session storage API for Next.js projects, similar to Remix's createCookieSessionStorage. It provides an easy-to-use API for creating and managing cookie sessions, including encoding and signing.
- Cookie-based session storage.
- Easy integration with Next.js.
- Built-in Base64 encoding.
- Built-in support for signing.
- Supports custom encoding and encryption.
- Compatible with middlewares, route handlers, server actions and getServerSideProps.
- This library is designed for use in server-side environments only.
- Cookies are HttpOnly and Secure, with the Path set to '/' by default.
- Cookies are encoded to Base64 by default, but this can be disabled or customized.
$ npm install next-cookie-session-storageimport { createCookieSessionStorage } from 'next-cookie-session-storage';
export async function GET(request) {
const { getSession, commitSession } = createCookieSessionStorage({
cookie: { name: '<session cookie name>' },
});
const session = await getSession(request);
session.set('id', 1111);
const response = NextResponse.json({ message: 'success' }, { status: 200 });
response.headers.set('Set-Cookie', await commitSession(session));
return response;
}import { NextResponse } from 'next/server';
import { createCookieSessionStorage } from 'next-cookie-session-storage';
export async function middleware(request) {
const { getSession, commitSession } = createCookieSessionStorage({
cookie: { name: '<session cookie name>' },
});
const session = await getSession(request);
session.set('id', 1111);
const response = NextResponse.next();
response.headers.set('Set-Cookie', await commitSession(session));
return response;
}'use server';
import { createCookieSessionStorage } from 'next-cookie-session-storage';
import { cookies } from 'next/headers';
export async function serverAction() {
const { getSession, setCookie } = createCookieSessionStorage({
cookie: { name: '<session cookie name>' },
});
const session = await getSession(cookies());
session.set('id', 1111);
setCookie(session);
return; //...
}import { createCookieSessionStorage } from 'next-cookie-session-storage';
export const getServerSideProps = async ({ req, res }) => {
const { getSession, commitSession, destroySession } =
createCookieSessionStorage({
cookie: {
name: '<session-cookie-name>',
},
});
const session = await getSession(req);
session.set('id', 1111);
res.setHeader('Set-Cookie', await commitSession(session));
return {
props: {},
};
};import { createCookieSessionStorage } from 'next-cookie-session-storage';
export async function GET(request: NextRequest) {
const storage = createCookieSessionStorage({
cookie: { name: 'en_session' },
});
const session = await storage.getSession(request);
// setting a new data
session.set('username', 'John Doe');
session.set('id', 1111);
// retrieving the value of a data
session.get('username');
// retrieving the entire session data
session.getData(); // returns { username: 'John Doe', id: 1111 }
// retrieving the session data as string
session.toString();
// deleting a data
session.delete('username');
}Important! Setting or manipulating session data does not automatically set the cookie. The session data must be finalized by committing it in a response's Set-Cookie header using commitSession method.
import { createCookieSessionStorage } from 'next-cookie-session-storage';
export async function GET(request) {
const { getSession, destroySession } = createCookieSessionStorage({
cookie: { name: '<session cookie name>' },
});
const session = await getSession(request);
const response = NextResponse.json({ message: 'success' }, { status: 200 });
response.headers.set('Set-Cookie', await destroySession(session));
return response;
}Destroying session with deleteCookie method (Cookies API only)
import { createCookieSessionStorage } from 'next-cookie-session-storage';
import { cookies } from 'next/headers';
export async function serverAction() {
const storage = createCookieSessionStorage({
cookie: { name: '<session-cookie-name>' },
});
const session = await storage.getSession(cookies());
storage.deleteCookie(session); // this will work as destroySession
return; //...;
}The options.cookie parameter of the createCookieSessionStorage function includes a secrets property that accepts an array of strings. Once this array is provided, signing will be enabled automatically.
import { createCookieSessionStorage } from 'next-cookie-session-storage';
const storage = createCookieSessionStorage({
cookie: { name: 'en_session', secrets: ['qwerty'] },
});Encoding can be enabled, disabled, or customized using the options parameter of the createCookieSessionStorage function. By default, cookies are encoded in Base64. You can disable this by setting the encoding option to false. Note that the cookie string will still be URI encoded.
import { createCookieSessionStorage } from 'next-cookie-session-storage';
const storage = createCookieSessionStorage({
cookie: { name: 'en_session' },
encoding: false, // Default encoding disabled
});Custom encoding or encryption can be added by passing an object with encoder and decoder functions. These functions must accept at least one parameter, which is the value to encode or decode. If additional parameters are needed, they can be provided as arrays in the encoderParams and decoderParams properties. For more information, see createCookieSessionStorage reference and Custom encoding
Example without additional parameters:
import { createCookieSessionStorage } from 'next-cookie-session-storage';
function customEncoder(value) {
// encode...
return encodedValue;
}
function customDecoder(value) {
// decode...
return decodedValue;
}
const storage = createCookieSessionStorage({
cookie: { name: 'en_session' },
encoding: {
encoder: customEncoder,
decoder: customDecoder,
},
});Example with additional parameters:
import { createCookieSessionStorage } from 'next-cookie-session-storage';
function customEncoder(value, secrets, salt) {
// encode...
return encodedValue;
}
function customDecoder(value, secrets, salt) {
// decode...
return decodedValue;
}
const storage = createCookieSessionStorage({
cookie: { name: 'en_session' },
encoding: {
encoder: customEncoder,
encoderParams: [process.env.ENCODING_SECRETS, process.env.SALT],
decoder: customDecoder,
decoderParams: [process.env.ENCODING_SECRETS, process.env.SALT],
},
});Creates a cookie session storage.
const storage = createCookieSessionStorage({
cookie: { name: 'en_session' },
});or you can strictly type the session data:
const type SessionData = {
user: string;
id: number;
}
const storage = createCookieSessionStorage<SessionData>({
cookie: { name: 'en_session' },
});T extends Record<string, any>: Defines the structure of the session data.
Type: Object
Consists of cookie and encoding properties.
An object with the following methods:
getSession
commitSession
destroySession
setCookie
deleteCookie
Type: Object
name: Session cookie name
domain: Specifies the value for the Domain attribute in the Set-Cookie header. By default, no domain is set, so most clients will consider the cookie to apply only to the current domain.
httpOnly: Specifies the boolean value for the HttpOnly attribute in the Set-Cookie header. By default, set to true.
expires: Specifies a Date object for the Expires attribute in the Set-Cookie header. By default, no expiration is set, so most clients will treat this as a "non-persistent cookie" and delete it under conditions such as closing the web browser.
maxAge: Specifies the number (in seconds) for the Max-Age attribute in the Set-Cookie header. The given number will be converted to an integer by rounding down. By default, no maximum age is set. According to the cookie storage model specification, if both Expires and Max-Age are set, Max-Age takes precedence. However, not all clients may adhere to this rule, so if both are used, they should refer to the same date and time.
path: Specifies the value for the Path attribute in the Set-Cookie header. By default, path is set to "/"
samSite: Can be lax, strict or none. lax will set the SameSite attribute to Lax , which provides lax same-site enforcement. none will set the SameSite attribute to None, indicating an explicit cross-site cookie. strict will set the SameSite attribute to Strict, enforcing strict same-site restrictions.
priority: Specifies the string to be the value for the Priority Set-Cookie attribute. low will set the Priority attribute to Low. medium will set the Priority attribute to Medium, which is the default when not specified. high will set the Priority attribute to High. This attribute is not yet fully standardized and may change in the future, meaning many clients might ignore it until it becomes more widely understood.
partitioned: Specifies the boolean value for the Partitioned attribute in the Set-Cookie header. By default, the Partitioned attribute is not set. This attribute is not yet fully standardized and may change in the future, meaning many clients might ignore it until it becomes more widely understood.
secure: Specifies the boolean value for the Secure attribute in the Set-Cookie header. By default, the Secure attribute is enabled, enforcing that the cookie is only sent over HTTPS connections.
secrets: Specifies the secrets used for signing. If no secrets are provided, signing is disabled.
omitSignPrefix: When set to true, omits the s: prefix from the cookie string.
Type: Boolean | Object | undefined
Default: enabled
options.encoding = false; // Disables encodingoptions.encoding = true; // Explicitly enables encodingor set as an object for custom encoding
{
encoder: (value: string, ...args: any[]) => string;
encoderParams?: any[];
decoder: (value: string, ...args: any[]) => string;
decoderParams?: any[];
}See Custom encoding for details
Retrieves the session data from the cookie source.
getSession(source: unknown): Promise<CookieSession<T>>Parameters source: unknown: The source from which to extract the cookie (e.g., NextRequest, cookies API).
Returns Promise<CookieSession>: A promise that resolves to the session object.
Serializes and signs the session data for setting in a cookie.
commitSession(session: CookieSession<T>): Promise<string>Parameters session: CookieSession: The session object containing the data to commit.
Returns Promise: A promise that resolves to the serialized cookie string.
Destroys the session by invalidating the cookie.
destroySession(session: CookieSession<T>): Promise<string>Parameters session: CookieSession: The session object to destroy.
Returns Promise: A promise that resolves to the serialized cookie string with maxAge set to 0.
Sets the session cookie using the Cookies API. Important! Can only be used when the session is retrieved by Cookies API
setCookie(session: CookieSession<T>): Promise<void>Parameters session: CookieSession: The session object to set as a cookie.
Returns Promise: A promise that resolves once the cookie has been set.
Deletes the session cookie using Cookies API. Important! Can only be used when the session is retrieved by Cookies API
deleteCookie(session: CookieSession<T>): Promise<void>Parameters session: CookieSession: The session object to delete.
Returns Promise: A promise that resolves once the cookie has been deleted.
Created by the createCookieSessionStorage function's getSession method. Contains the following methods:
set
get
delete
clear
getData
toString
Sets the value of the specified key
session.set(key: string, value: string): voidRetrieves the value of the specified key
session.get(key: string): stringRemoves the specified key from the session data
session.delete(key: string): voidClears the entire session data
session.clear(): voidRetrieves the entire session data as an object
session.getData(): ObjectRetrieves the entire session data as a string
session.toString(): stringFor custom encoding or encryption, set options.encoding to an object with the following properties:
encoder: Custom encoder function
encoder: (value: string[, ...args: any[]]) => stringParameters
value: Session data as string
(You can include additional parameters as needed. Be sure to add them to encoderParams.)
Returns Encoded/encrypted string
encoderParams: encoder function extra parameters (Optional)
decoder: Custom decoder function
decoder: (value: string[, ...args: any[]]) => stringParameters
value: Encoded/encrypted string
(You can include additional parameters as needed. Be sure to add them to decoderParams.)
Returns Decoded/decrypted session data as string
decoderParams: decoder function extra parameters (Optional)
This project is licensed under the MIT License.