doc: migrate more auth guide to v3

[ymc9]

Summary by CodeRabbit

• Documentation
  • Better-Auth guide updated with a sidebar label, clarified examples, and a recommended pattern to use an auth-enabled ORM client plus guidance on creating user-bound clients.
  • New Clerk authentication integration guide covering setup, model/configuration guidance, user sync, and creating user-bound ORM clients.
  • New custom authentication guide with required auth-field mapping, runtime user retrieval advice, and user-bound client examples.

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
zenstack-new-site	Ready	Preview	Comment	Nov 18, 2025 5:51pm

[coderabbitai]

Walkthrough

Adds/edits documentation in v3.x auth integration: updates Better-Auth examples to use an auth-enabled ORM client (authDb.$setAuth(...)) and adds two new recipe pages for Clerk and custom authentication, both showing how to create user-bound ORM clients via $setAuth().

Changes

Cohort / File(s)	Change Summary
Better-Auth update versioned_docs/version-3.x/recipe/auth-integration/better-auth.md	Added sidebar_label metadata, clarified import comments, and replaced db.$setAuth(...) usages with authDb.$setAuth(...), plus guidance line about creating user-bound ORM clients after obtaining session data.
Clerk integration guide (new) versioned_docs/version-3.x/recipe/auth-integration/clerk.md	New page describing Clerk setup with ZenStack, ZModel @@auth usage, Post model example, user sync guidance, and server-side examples that obtain Clerk session (auth()) and call $setAuth() on an auth-enabled ORM client.
Custom auth guide (new) versioned_docs/version-3.x/recipe/auth-integration/custom.md	New page describing required auth fields (id, role, permissions), mapping auth() to a model/type, runtime user resolution (JWT/service), and example creating a user-bound ORM client via ZenStackClient.$setAuth(...).

Sequence Diagram(s)

sequenceDiagram
    autonumber
    actor Client
    participant Server
    participant AuthService as Auth Service
    participant AuthDB as authDb (ORM w/ access policy)

    Client->>Server: Request (authenticated)
    Server->>AuthService: retrieve session / current user
    AuthService-->>Server: user { id, role, ... }
    note right of Server `#DDEBF7`: create user-bound ORM client
    Server->>AuthDB: authDb.$setAuth({ userId, role, ... })
    AuthDB-->>Server: auth-enabled client ready
    Server->>AuthDB: perform DB operations (enforced by access policies)
    AuthDB-->>Server: query/mutation results
    Server-->>Client: response

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Docs-only changes, consistent patterns across files.
• Pay attention to:
  • Correctness of updated code snippets (imports and authDb usage).
  • Accurate explanation of @@auth mapping and required auth fields.
  • Consistency between Clerk examples and server helper usage.

Possibly related PRs

• doc: release 3.0.0-beta.24 #509: Touches the same Better-Auth doc and similarly updates examples to use an auth-enabled ORM client (authDb.$setAuth).
• docs: release v2.9.0 #389: Related Clerk documentation changes around the User representation and creating user-bound/auth-enabled clients.
• blog: better auth multi-tenancy #409: Modifies Clerk and Better-Auth examples; likely overlaps in $setAuth usage and auth flow examples.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: migrating additional authentication guides to version 3. It directly matches the changeset which adds/updates three auth integration documentation files (Better-Auth, Clerk, and custom auth) for the v3 documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch doc/more-auth-guide

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0365a5c and c82bc0a.

📒 Files selected for processing (1)

• versioned_docs/version-3.x/recipe/auth-integration/clerk.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• versioned_docs/version-3.x/recipe/auth-integration/clerk.md

---

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: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 56847d8 and 0365a5c.

📒 Files selected for processing (3)

• versioned_docs/version-3.x/recipe/auth-integration/better-auth.md (5 hunks)
• versioned_docs/version-3.x/recipe/auth-integration/clerk.md (1 hunks)
• versioned_docs/version-3.x/recipe/auth-integration/custom.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

versioned_docs/version-3.x/recipe/auth-integration/clerk.md

11-11: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

🔇 Additional comments (5)

versioned_docs/version-3.x/recipe/auth-integration/custom.md (1)

1-59: Custom auth guide is well-structured and complete.

versioned_docs/version-3.x/recipe/auth-integration/clerk.md (1)

1-9: Clerk integration guide is comprehensive and clear.

The documentation properly covers setup, schema configuration, and the user-bound ORM client creation pattern with clear code examples for Next.js.

versioned_docs/version-3.x/recipe/auth-integration/better-auth.md (3)

3-3: Metadata update is appropriate.

---

29-31: Import comment and pattern are clear.

The clarifying comment for the auth-enabled ORM client and the shift to authDb import align with the v3 migration pattern shown in the other auth integration guides.

---

85-89: Consistent migration to user-bound ORM pattern.

Both code examples properly switch from db.$setAuth() to authDb.$setAuth(), maintaining consistency with the new authentication integration approach across all guides.

Also applies to: 120-121