docs(server): restore Better Auth integration guide for v2

[Mnigos]

Restores the Better Auth integration guide for v2 with two examples: resolving the session in protected middleware, and lazily loading a session once per request, shared across batch sub-requests. Both show public and protected procedures, inferred session types, and the lookup/error-handling tradeoffs.

Related to #1892. This is a documentation-first contribution; the dedicated package remains open for discussion.

Validation:

• pnpm docs:validate
• pnpm --filter @orpc/content build
• Both extracted examples typechecked against Better Auth 1.7.2, including an additional user field.

[pullfrog]

✅ No new issues found.

Reviewed changes — a single new doc page apps/content/docs/integrations/better-auth.mdx that restores the Better Auth integration guide for v2. It covers two patterns: resolving the session in a requireSession middleware (headers from initial context, getSession lookup, ORPCError('UNAUTHORIZED') on absence), and reusing a session already resolved outside the oRPC handler (typed as Awaited<ReturnType<typeof auth.api.getSession>>, narrowed by the middleware while public handlers check for it). Both show public plus protected procedures, inferred session types, handler setup with RPCHandler, and the cookie-header-forwarding caveat.

I verified the load-bearing claims against the repo and Better Auth's docs/source:

• The oRPC v2 API usage (os.$context, base.middleware, base.use, next({ context }) merge, RPCHandler.handle with prefix/context) matches the existing context.mdx, middleware.mdx, and fetch-api.mdx docs.
• auth.api.getSession({ headers }) matches Better Auth's official API, and the returned type { session, user } | null (confirmed from the better-auth get-session route source) lines up with the Session typing and both hander narrowings in the examples.
• Both external links resolve and their anchors exist.
• The page is auto-discovered by Blume's filesystem content source and its sidebar.label matches sibling integration pages, so no navigation config change is needed.

Technical details below only for the note about the PR description, which is editorial and non-blocking.

ℹ️ PR description says "Draft" while the PR is ready

The description still ends with "Draft while the proposed scope is being discussed.", but the PR is currently marked ready for review (draft: false). Consider updating the description to reflect the current state, e.g. noting the scope decision (docs-first, dedicated package still open per #1892).

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[dinwwwh]

@Mnigos I just updated latest docs - review it if you have time.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@1992

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@1992

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@1992

@orpc/client

npm i https://pkg.pr.new/@orpc/client@1992

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@1992

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@1992

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@1992

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@1992

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@1992

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@1992

@orpc/experimental-msw

npm i https://pkg.pr.new/@orpc/experimental-msw@1992

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@1992

@orpc/next

npm i https://pkg.pr.new/@orpc/next@1992

@orpc/node

npm i https://pkg.pr.new/@orpc/node@1992

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@1992

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@1992

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@1992

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@1992

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@1992

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@1992

@orpc/server

npm i https://pkg.pr.new/@orpc/server@1992

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@1992

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@1992

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@1992

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@1992

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@1992

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@1992

commit: 868c798

[pullfrog]

ℹ️ No critical issues — two doc-completeness nits inline, plus one cross-cutting note.

Reviewed changes — a single revision commit (868c798, "Revise Better Auth integration details in documentation") on top of the previously approved page:

• Reworked the first example around the Request Headers Plugin (context.reqHeaders with an empty-Headers fallback), and documented the plugin-less path (server-side calls) plus the per-sub-request lookup cost in batches.
• Replaced the pre-resolved-session pattern with a lazy memoized getSession getter shared across a request, including batch sub-requests.
• Trimmed the narrative framing (dropped the ./auth import setup sentence and the external installation/getting-headers links).

I re-verified the new load-bearing claims against repo sources and better-auth's source: RequestHeadersHandlerPluginContext / reqHeaders semantics match packages/server/src/plugins/request-headers.ts:10; per-sub-request middleware execution matches packages/server/src/plugins/batch.ts:202; server-side calls accept an initial context per client/server-side.mdx; and better-auth's get-session route returns null when the headers carry no session cookie (api/routes/session.ts), so the empty fallback yields UNAUTHORIZED rather than an error in both examples.

ℹ️ Session cookie refreshes are silently dropped in both examples

Both examples call auth.api.getSession server-side, but neither captures the response's set-cookie — in the first via the middleware, in the second via the fetch wrapper. The rewrite removed the info box that warned about exactly this for the reuse pattern, and the caveat now applies to both examples. With default better-auth settings, the sliding-session refresh never reaches the browser, so active sessions expire at their initial expiry instead of being extended. Consider restoring a short note (the removed text, plus a pointer to forwarding the response headers, e.g. via the Response Headers Plugin).

Technical details

# Better Auth response headers not forwarded to the client

## Affected sites
- apps/content/docs/integrations/better-auth.mdx — both examples call `auth.api.getSession` server-side; neither forwards the response's `set-cookie`, so sliding-session refreshes are lost.

## Required outcome
- Readers are told that (a) `getSession` may emit `set-cookie` (sliding-session refresh) and (b) the examples drop it, with a pointer to forwarding the headers (e.g. the Response Headers Plugin or better-auth's response-headers guidance).

## Suggested approach (optional)
- Restore an info box like the removed one, which referenced better-auth.com/docs/concepts/api#getting-headers alongside the framework's cookie integration.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[codspeed-hq]

Merging this PR will not alter performance

✅ 30 untouched benchmarks

---

_{Comparing Mnigos:better-auth-integration-guide (868c798) with main (9379b50)}

[Mnigos]

@dinwwwh Made small adjustments, now LGTM

[pullfrog]

ℹ️ Prior feedback largely addressed; the delta reads accurately. One earlier minor point remains open.

Reviewed changes — a single delta commit (436957b, "docs: clarify Better Auth session headers and cookies") on top of the previously reviewed revision:

• Reworded the server-side-call paragraph (better-auth.mdx:49): the empty Headers fallback now correctly states that getSession returns null when no session cookie is present, rather than implying it throws — matching Better Auth's behavior.
• Added a closing note (better-auth.mdx:109) that both examples may need to forward session cookies to the browser, pointing to Better Auth's response-headers guidance. I verified the URL and its #getting-headers anchor both resolve, and the note directly addresses the cookie-forwarding concern from the prior review.

Of the feedback from the previous review, the wording nit is resolved (thread closed) and the cookie-forwarding note is addressed by the closing sentence. The one remaining item is the thread at line 12 — the example still never shows RequestHeadersHandlerPlugin registration, leaving readers on their own to enable it; that's a minor doc-completeness suggestion, not a blocker, and I'm leaving the thread open for the author to decide whether to add a pointer.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}