iron-session

iron-session stores session data in signed and encrypted cookies that your server decodes statelessly — no session store, database, or network round-trip required. This is the same technique long used by frameworks like Ruby on Rails, brought to JavaScript with a small, dependency-light API built on the iron encryption seal.

Because sessions live entirely in the cookie itself, iron-session works cleanly in serverless and edge environments where a persistent session store is awkward or costly to maintain. It’s framework-agnostic at the core but ships first-class helpers for Next.js (getIronSession for the App Router and Pages Router API routes) and is featured directly in the official Next.js authentication documentation.

What You Get

• A getIronSession<T>() function returning a typed, mutable session object backed by an encrypted cookie
• Zero server-side session storage — no Redis, database, or session store to provision or scale
• First-class Next.js support for both the App Router and Pages Router API routes
• Works with any Node.js-based framework (Express, Fastify, etc.) via a generic request/response adapter
• Configurable cookie options (name, TTL, secure/sameSite/httpOnly flags) via sessionOptions
• A tiny bundle footprint reported directly in the README via bundlejs badges

Common Use Cases

• Adding login sessions to a Next.js app deployed on serverless/edge platforms where a sticky session store isn’t available
• Storing lightweight per-user state (cart contents, wizard progress, feature flags) without a database round-trip
• Migrating an Express app off a server-side session store (e.g. express-session + Redis) to reduce infrastructure
• Building auth flows where the session itself carries claims (user id, role) rather than a bare session id

Under The Hood

Architecture - The library is deliberately small: src/core.ts (~500 lines) implements the seal/unseal cycle atop the iron primitive and the cookie read/write adapter that normalizes different request/response shapes (Next.js App Router’s cookies(), Pages Router’s req/res, and generic Node IncomingMessage/ServerResponse), while src/index.ts is a thin public re-export surface, keeping the framework-specific glue isolated from the core encryption logic.

Tech Stack - TypeScript compiled to dual ESM/CJS output (dist/index.js / dist/index.cjs), built on the iron password-based encryption library for the actual sealing, with no runtime dependencies beyond it — a conscious design choice given the project’s stated goal of staying framework-agnostic and edge-runtime compatible.

Code Quality - src/index.test.ts (~500 lines, roughly matching the core implementation’s size) exercises the seal/unseal round trip, cookie option handling, and Next.js-specific adapter paths; CI runs via GitHub Actions on every push, and the project has shipped 34 releases over its life, though recent commit activity has slowed (health-score data shows low activity/maintenance in the last period despite the library being feature-complete and widely depended upon).

API Design - A single getIronSession() entry point covering all supported frameworks is a deliberately minimal, easy-to-learn surface — most integration is copy-pasting one call plus a sessionOptions object with a secret password and cookie name; TypeScript generics (getIronSession<T>) give consumers full type safety over their custom session shape with no extra boilerplate.