feat: Nitro v3 compatibility

[productdevbook]

Summary

• support Nuxt 4/Nitro 2 and Nuxt 5/Nitro 3 from the same module release
• select the matching runtime and type imports during Nuxt setup, so consumer bundles never include unavailable cross-major APIs
• add clean packed-consumer build and runtime checks for Nuxt 4.5 and the Nuxt 5 nightly

Root cause

The server runtime imported H3 and Nitro 2 entry points directly. Replacing those imports with Nitro 3 entry points would break Nuxt 4, while runtime feature detection would still leave unavailable static imports in consumer bundles. The module now resolves one source-level compatibility implementation for the active Nuxt major.

Closes #86

Testing

• pnpm lint
• pnpm typecheck
• pnpm prepack
• pnpm dev:build
• pnpm build:docs
• pnpm test (GitHub CI)
• pnpm exec vitest run --project integration (5 files, 20 tests)
• GitHub compatibility matrix: Nuxt 4.5/Nitro 2 and Nuxt 5 nightly/Nitro 3 both install the packed module, build, start, and serve the Better Auth endpoint

[vercel]

@productdevbook is attempting to deploy a commit to the maximogarciamartinez's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
nuxt-better-auth-docs	Error		Jan 27, 2026 6:01am

[productdevbook]

@onmax I just added this. better-auth:client:extend

[onmax]

Hey @productdevbook, nice work on this PR. Just checked, and I like the direction :). could you split out everything not directly tied to Nitro v3 compatibility? I’d keep this PR focused on the nitro/* import changes + getRouteRules/request handling updates.

Move to separate PR:

• better-auth:client:extend feature (hooks types + module hook + defineClientAuth/useUserSession changes)
• .nuxtrc
• auth.config.ts + server/auth.config.ts (if just examples)

If you’d rather, I can extract these into a separate PR.

[productdevbook]

It would be good if you could separate them because I'll be away from nuxt for 2-3 months.

[productdevbook]

When closing, it is beneficial to state your thoughts here. The reason for closing should not remain with you. :)

[onmax]

Sorry, I miss clicked. I didn't mean to close this pr. You are right :)

[onmax]

Hi @productdevbook, I wanted to share a parallel architecture idea I’ve been playing with and get your thoughts on it.

I opened #281 as a draft spike to explore a different direction for Nitro v3 support:

• keep a single package
• keep . and ./config Nuxt-first
• add dedicated Nitro entry points like ./nitro and ./nitro/config
• keep the Nitro v3 work isolated for now, without refactoring the Nuxt entry to consume it yet

The main goal is to move toward a more layered architecture: establish a Nitro-first server layer first, then later make the Nuxt module consume that layer internally.

This is not meant as “#281 instead of #87”. It’s more of an architectural experiment to validate another shape for the module. Ideally, if this direction makes sense, we would still merge the work through #87 rather than replace it with my draft PR.

I also think this could make it easier to support other Nitro-based frameworks in the future.

I’d also like to know if you’re interested in continuing to develop this direction yourself, or if you’d prefer that I take it over. I don’t want to throw away the work you already did, but I do really like this approach.

If you have any comments on the architecture, tradeoffs, or anything that feels wrong with this direction, I’d really like to hear them before this goes any further.

Thank you!

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@onmax/nuxt-better-auth@87

commit: e2513b7

[productdevbook]

🚀

[productdevbook]

I'm sorry I couldn't answer; I can't focus on open source at all because of my job search.