Iron Session

Common errors

• ReferenceError: require is not defined

  cause `iron-session` is primarily designed as an ES Module (ESM) since version 6.0.0. Using `require()` syntax in an ESM-only context will lead to this error.
  fix Update your import statements to use ES Module syntax: `import { getIronSession } from 'iron-session';`. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions for your source files.

• Property 'session' does not exist on type 'NextApiRequest'

  cause This TypeScript error often occurs when developers expect `req.session` to be automatically available on a Next.js request object without proper type augmentation or explicit session retrieval.
  fix After calling `const session = await getIronSession(req, res, sessionOptions);`, access session properties directly on the `session` object. For type safety, define a `SessionData` interface and pass it to `getIronSession<SessionData>(...)`.

• TypeError: session.destroy(...).then is not a function

  cause This error arises when attempting to use `.then()` or `await` with `session.destroy()` after version 8.0.1, where `destroy()` was changed to be synchronous.
  fix Remove `await` or `.then()` from `session.destroy()`. Simply call `session.destroy();`. Remember to follow it with `await session.save()` if you want the cookie to be immediately cleared from the client.

Warnings

• breaking Version 8.0.0 significantly refactored the API to align with the Next.js App Router and simplify the overall surface. All previous opinionated wrapper functions like `withIronSessionSsr` or `withIronSessionApiRoute` have been removed in favor of a single `getIronSession()` method.
  Fix: Migrate your code to use the `getIronSession(req, res, sessionOptions)` or `getIronSession(cookieStore, sessionOptions)` method directly. Refer to the official migration guide for specific examples.
• breaking Version 6.0.0 was a complete rewrite of the library in TypeScript and involved a package rename from `next-iron-session` to `iron-session`. This introduced numerous breaking changes to the API, types, and internal structure.
  Fix: If upgrading from `next-iron-session` (v5 or lower), a full migration is required. Install `iron-session` and update all imports and API calls according to the v6 migration guide. Ensure your project is configured for TypeScript if not already.
• gotcha As of v8.0.1, the `session.destroy()` method is synchronous and returns `void`. Previous versions might have returned a `Promise<void>`, leading to developers incorrectly awaiting or chaining `.then()` to it.
  Fix: Call `session.destroy()` without `await` or `.then()`. Remember to call `await session.save()` *after* `session.destroy()` to ensure the session cookie is correctly invalidated and cleared from the browser.
• gotcha The `password` option in `sessionOptions` is critical for the security of your sessions. It must be a strong, cryptographically secure random string of at least 32 characters. Hardcoding this password or using a weak one makes your sessions vulnerable to decryption and tampering.
  Fix: Always store your session password as an environment variable (e.g., `process.env.IRON_SESSION_PASSWORD`) and ensure it meets the minimum length and randomness requirements. Do not hardcode it in your source code.

Install

• npm install iron-session npm
• yarn add iron-session yarn
• pnpm add iron-session pnpm

Imports

• getIronSession
  wrong:

  const getIronSession = require('iron-session');

  correct:

  import { getIronSession } from 'iron-session';

  Since v6.0.0 (the TypeScript rewrite), iron-session primarily uses ESM for its main exports. CommonJS `require()` is not officially supported for the primary entry point.
• IronSession
  wrong:

  import { IronSession } from 'iron-session';

  correct:

  import type { IronSession } from 'iron-session';

  This is a TypeScript type definition. Use `import type` to ensure it's removed during compilation, preventing potential runtime issues or bundle size increases.
• sealData
  wrong:

  import sealData from 'iron-session';

  correct:

  import { sealData } from 'iron-session';

  Both `sealData` and `unsealData` are named exports for manual encryption/decryption of data outside the standard session flow.

Quickstart

This quickstart demonstrates how to initialize, read, update, and destroy a user's session using `getIronSession` in a Next.js API Route context. It includes examples for handling user login/logout and managing session state, emphasizing proper type usage and secure password handling.

import { getIronSession, type IronSession } from 'iron-session';
import { type NextApiRequest, type NextApiResponse } from 'next'; // Example for Next.js

// Define a type for your session data
interface SessionData {
  username?: string;
  isLoggedIn: boolean;
  // Add other properties you want to store in the session
}

// Define session options, including a strong secret password
const sessionOptions = {
  password: process.env.IRON_SESSION_PASSWORD ?? 'a-very-long-secret-password-at-least-32-chars-long',
  cookieName: 'my-app-session-cookie',
  cookieOptions: {
    maxAge: 60 * 60 * 24 * 30, // 30 days
    secure: process.env.NODE_ENV === 'production', // Set to true in production
    httpOnly: true,
    path: '/',
    sameSite: 'lax'
  }
};

// Example GET handler to retrieve session data
export async function getSessionHandler(req: NextApiRequest, res: NextApiResponse) {
  const session = await getIronSession<SessionData>(req, res, sessionOptions);

  // Initialize if not set for new sessions
  if (session.isLoggedIn === undefined) {
    session.isLoggedIn = false;
  }

  return res.status(200).json({ isLoggedIn: session.isLoggedIn, username: session.username });
}

// Example POST handler (e.g., login) to update session data
export async function loginHandler(req: NextApiRequest, res: NextApiResponse) {
  const session = await getIronSession<SessionData>(req, res, sessionOptions);

  // In a real app, you'd validate user credentials here
  if (req.body.username === 'demo' && req.body.password === 'password') {
    session.username = req.body.username;
    session.isLoggedIn = true;
    await session.save(); // Persist changes to the session cookie
    return res.status(200).json({ message: 'Logged in successfully' });
  }

  return res.status(401).json({ message: 'Invalid credentials' });
}

// Example handler for logging out a user
export async function logoutHandler(req: NextApiRequest, res: NextApiResponse) {
  const session = await getIronSession<SessionData>(req, res, sessionOptions);
  session.destroy(); // This is synchronous since v8.0.1, removes the session cookie
  await session.save(); // Ensure the cookie is cleared from the browser
  return res.status(200).json({ message: 'Logged out successfully' });
}