iron-session is a secure, stateless, and cookie-based session management library for JavaScript environments, primarily used in Node.js applications and Next.js projects (supporting both API Routes and the App Router). The current stable version is 8.0.4. It distinguishes itself by storing encrypted and signed session data directly within HTTP cookies, thereby eliminating the need for server-side storage or external databases, a pattern inspired by frameworks like Ruby On Rails. This design promotes statelessness, improving scalability and simplifying deployment strategies. While it doesn't adhere to a fixed release schedule, major versions typically introduce significant API adjustments or compatibility updates, such as the v8 release which focused on App Router support and API simplification. The library ships with comprehensive TypeScript types, ensuring a robust and type-safe development experience.
npm install iron-sessionVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.
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.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>(...)`.
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.
No dependency data recorded yet.