fix(docs): better-auth documentation

[hexadecimal233]

this PR fixes the 404 social callback issue mentioned in #576.

also fixed lifecycle error not triggering while mounting to root.

The mount will automatically pass errors to the Better Auth handlers, causing all request to return plain 404 rather than predefined lifecycle errors in onError hook.

Summary by CodeRabbit

• Documentation
  • Updated Better Auth docs with revised routing recommendations (use route-wide handlers) and updated examples.
  • Clarified URL/basePath configuration, custom endpoint prefixing, and corresponding access URLs to avoid 404s.
  • Added note that the new routing preserves OAuth callback behavior but does not rewrite path headers, so manual URL/header adjustments may be needed.

[coderabbitai]

Walkthrough

This PR updates Better Auth docs to replace .mount(...) with route-wide .all(...) usage, changes example URL prefixes (including a custom /v1/auth* endpoint), adjusts basePath from /api to /v1/auth, and adds notes about .all() path/header behavior and OAuth callback preservation.

Changes

Cohort / File(s)	Summary
Better Auth integration docs docs/integrations/better-auth.md	Replaces .mount(...) examples with .all("/api/auth*", ...) and a custom .all("/v1/auth*", ...) example; updates basePath from /api to /v1/auth; adds notes that .all() prevents interception and preserves OAuth callbacks but does not rewrite path headers (manual URL setting required); adjusts example access URLs accordingly.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 I hopped through docs with nimble paws,
Swapping mounts for .all() because,
Paths now prefixed and tidy, too—
OAuth callbacks safe and true. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'fix(docs): better-auth documentation' is vague and doesn't convey the specific changes. The PR actually addresses routing strategy changes and fixes for OAuth callback handling and lifecycle errors, which are not reflected in the generic title.	Consider a more specific title like 'fix(docs): better-auth routing strategy and OAuth callback handling' or 'fix(docs): better-auth mount behavior and lifecycle error fixes' to better reflect the actual changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/integrations/better-auth.md (1)

160-174: ⚠️ Potential issue | 🟠 Major

CORS section still uses .mount(auth.handler) — the pattern this PR is fixing.

The PR's stated goal is to replace .mount() because it causes plain-404 responses and suppresses lifecycle hooks. The CORS and Macro sections (lines 168 and 186) still use .mount(auth.handler) unchanged, so users following those examples will hit the same bugs.

Both sections need to be updated to use .all() and pass the URL explicitly, consistent with the Handler section.

✏️ Proposed fix (CORS section, line 168)

 const app = new Elysia()
     .use(
         cors({ ... })
     )
-    .mount(auth.handler)
+    .all("/api/auth*", ({ request }) => auth.handler(request))
     .listen(3000)

✏️ Proposed fix (Macro section, line 186)

 const betterAuth = new Elysia({ name: 'better-auth' })
-    .mount(auth.handler)
+    .all("/api/auth*", ({ request }) => auth.handler(request))
     .macro({ ... })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/integrations/better-auth.md` around lines 160 - 174, The docs still
demonstrate the deprecated pattern by using .mount(auth.handler) in the CORS and
Macro examples; update both examples to call .all() with an explicit route
(e.g., .all('/auth', auth.handler)) matching the Handler section so lifecycle
hooks and proper responses are preserved; find the instances of
.mount(auth.handler) in the CORS and Macro examples and replace them with .all()
plus the URL path while keeping the cors(...) and macro setup unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/integrations/better-auth.md`:
- Around line 42-46: Fix the typo and correct the misleading claim in the note
about routing: change "does not auth rewrite" to "does not rewrite" and update
the explanatory sentence to state that `.all()` preserves the full URL
(including the `/api/auth` prefix) which Better Auth relies on, whereas
`.mount()` strips that prefix and breaks Better Auth’s routing; reference the
`.all()` and `.mount()` examples in the note so readers see the behavior matches
the code example.
- Around line 87-90: The current Better Auth configuration uses a wildcard in
basePath which prevents route matching; update the auth export where betterAuth
is called (the auth constant / betterAuth(...) invocation) to use a plain path
string for basePath (e.g., '/v1/auth' or '/api/auth') instead of '/v1/auth*' so
incoming routes like '/v1/auth/sign-in' will match correctly.

---

Outside diff comments:
In `@docs/integrations/better-auth.md`:
- Around line 160-174: The docs still demonstrate the deprecated pattern by
using .mount(auth.handler) in the CORS and Macro examples; update both examples
to call .all() with an explicit route (e.g., .all('/auth', auth.handler))
matching the Handler section so lifecycle hooks and proper responses are
preserved; find the instances of .mount(auth.handler) in the CORS and Macro
examples and replace them with .all() plus the URL path while keeping the
cors(...) and macro setup unchanged.