Skip to content

v9.0.0

Choose a tag to compare

View all tags
@vvo vvo released this 30 Aug 20:56
· 7 commits to main since this release
v9.0.0
88145a5
This commit was created on GitHub.com and signed with GitHub鈥檚 verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode. 
pnpm add iron-session

Needs Node 22.13+ and is ESM-only (require() works on Node 22.13+). Stuck on older Node, or need CommonJS? Stay on iron-session@8.

How to upgrade

Most apps change two things. Both are things v8 got wrong quietly.

- session.lastSeen = new Date();   // v8 sealed this as a string
+ session.lastSeen = Date.now();

- const userId = session.user.id;  // empty on a first visit
+ const userId = session.user?.id;

Nothing else is required:

  • getIronSession(req, res, options) and getIronSession(await cookies(), options) both still work. Delete any as any you had on await cookies().
  • v9 reads v8 cookies and v8 reads v9 cookies, so a deploy rolls back without signing everyone out.
  • Users on pre-v8 cookies (iron-session 6 and older) sign in once more. That format picked its shape from a marker outside the signature, so an attacker could flip it.

Full guide: MIGRATION.md.

What's new

  1. Sessions work in Next.js Proxy (middleware), via nextProxyCookies
  2. Sessions can be bigger than 4KB, with chunk: true
  3. getIronSession(await cookies(), options) typechecks
  4. Four bugs that lost sessions or logouts without an error are fixed
  5. onUnsealError tells you why a cookie was rejected
  6. TypeScript catches reads of a session that may not exist
  7. Tested in Chromium, Firefox and WebKit, plus Node 22/24/26, Bun and Deno

The detail behind each of these is in the v9.0.0-beta.0 notes, and beta.1 softened four guards that turned out to break working logout handlers.

v9 runs in production on TurnShift, which is how the logout bug in beta.0 was found: existing sessions, magic links generated by AWS Lambda, session reads and writes, and logout were all verified against a real app before this release.

Assets 2
Loading