Skip to content

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

Open
Mnigos wants to merge 1 commit into
middleapi:mainfrom
Mnigos:better-auth-integration-guide
Open

docs(server): restore Better Auth integration guide for v2#1992
Mnigos wants to merge 1 commit into
middleapi:mainfrom
Mnigos:better-auth-integration-guide

Conversation

@Mnigos

@Mnigos Mnigos commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Restores the Better Auth integration guide for v2 with two examples: resolving the session in protected middleware, and reusing a session already loaded into context. 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.

Draft while the proposed scope is being discussed.

@Mnigos
Mnigos marked this pull request as ready for review September 6, 2026 23:29

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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).

Pullfrog  | View workflow run | Using DeepSeek Flash (free via Pullfrog for OSS) | 𝕏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant