Complete migration to Clerk from NextAuth.js by adamsardo · Pull Request #3 · adamsardo/saas-starter-kit

adamsardo · 2025-07-04T00:05:52Z

Complete the full migration from NextAuth.js to Clerk for authentication.

This PR completes the comprehensive migration of the application's authentication system from NextAuth.js to Clerk. It involves removing all NextAuth.js code, updating API routes and UI components to use Clerk's session management and hooks, and thoroughly updating all relevant documentation and configuration files to reflect the new authentication provider.

Summary by CodeRabbit

New Features
- Authentication is now powered by Clerk, supporting email/password, OAuth (GitHub, Google), magic links, SAML SSO, and two-factor authentication.
- Enhanced security features including attack protection, advanced password policies, and built-in email verification.
- Organization management with multi-tenancy, RBAC, team invitations, and domain allowlisting.
Bug Fixes
- Session management and sign-out flows streamlined for consistency across authentication methods.
Documentation
- Comprehensive updates to guides, README, and internal docs reflecting Clerk integration and setup.
- Added new authentication documentation and removed obsolete migration guides.
Refactor
- Replaced all NextAuth.js logic, hooks, and session handling with Clerk-based implementations.
- Updated components and hooks to use Clerk for authentication and session data.
Chores
- Cleaned up environment variables and deployment configurations to remove NextAuth references and add Clerk settings.
- Removed unused dependencies and type declarations related to NextAuth.

Co-authored-by: adam <adam@medreport.ai>

coderabbitai · 2025-07-04T00:05:59Z

Walkthrough

This change completes a comprehensive migration from NextAuth.js to Clerk for authentication, session, and security management across the application. All NextAuth.js code, configuration, and dependencies were removed. Clerk is now fully integrated, with updated authentication hooks, middleware, session handling, documentation, environment variables, and deployment templates.

Changes

Files / Groups	Change Summary
`lib/nextAuth.ts`, `pages/api/auth/[...nextauth].ts`, `pages/api/auth/custom-signout.ts`, `types/next-auth.d.ts`, `CLERK_MIGRATION_GUIDE.md`	Deleted all NextAuth.js authentication logic, API routes, and type augmentations; removed migration guide.
`package.json`, `tsconfig.json`, `app.json`, `.github/workflows/main.yml`, `.do/deploy.template.yaml`	Removed NextAuth dependencies and config; added Clerk env vars and deployment setup; updated workflow/test env vars.
`lib/env.ts`, `lib/auth.ts`, `lib/clerk.ts`	Removed NextAuth config and provider logic; added static Clerk provider config and password policies.
`lib/session.ts`, `pages/api/sessions/index.ts`, `pages/api/password.ts`, `pages/api/auth/reset-password.ts`	Refactored session logic to use Clerk; removed session token/cookie logic; always delete all sessions after password changes.
`hooks/auth.ts`, `hooks/useAuth.ts`, `hooks/useSession.ts`	Added new hooks for Clerk-based authentication, sign-in/out, session, and user/org context.
`hooks/useCustomSignout.ts`	Refactored signout logic to use Clerk SDK directly.
`components/auth/`, `components/shared/`, `components/account/`, `components/team/Members.tsx`, `pages/auth/`, `pages/invitations/[token].tsx`, `pages/settings/security.tsx`, `pages/teams/switch.ts`	Updated imports and logic to use new Clerk-based hooks and session data; removed all NextAuth references.
`types/next.ts`	Updated type definitions for page props and authentication; added `NextPageWithUser`.
`README.md`, `CLAUDE.md`, `docs/authentication.md`, `.cursor/rules/*`, `MIGRATION_COMPLETE.md`	Overhauled documentation to reflect Clerk integration, usage, migration steps, and updated best practices.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant UI
    participant ClerkSDK
    participant ClerkDashboard
    participant AppAPI

    User->>UI: Initiate login (email/password, OAuth, SSO, magic link)
    UI->>ClerkSDK: Call useSignIn / useAuth hook
    ClerkSDK->>ClerkDashboard: Authenticate user & manage session
    ClerkDashboard-->>ClerkSDK: Return user/org/session info
    ClerkSDK-->>UI: Provide session/user/org context
    UI->>AppAPI: Make authenticated API request with Clerk session
    AppAPI->>ClerkDashboard: Validate session via Clerk middleware
    ClerkDashboard-->>AppAPI: Return user/org context for authorization
    AppAPI-->>UI: Respond with protected resource/data

Possibly related PRs

adamsardo/saas-starter-kit#1: Introduced initial Clerk integration and migration support, enabling parallel operation and data sync with NextAuth.js. This PR is directly extended and completed by the current migration.

Poem

🐇✨

Goodbye to NextAuth, Clerk takes the stage,
With hooks and sessions, we turn the page.
Docs refreshed, the code is neat,
Teams and roles now can't be beat.
The bunny hops with glee and cheer—
Secure and simple, Clerk is here!

🥕

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

npm error Exit handler never called!
npm error This is an error with npm itself. Please report this error at:
npm error https://github.com/npm/cli/issues
npm error A complete log of this run can be found in: /.npm/_logs/2025-07-04T00_07_20_521Z-debug-0.log

✨ Finishing Touches

📝 Generate Docstrings

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

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

openhands-ai · 2025-07-04T00:07:25Z

Looks like there are a few issues preventing this PR from being merged!

GitHub Actions are failing:
- Build

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #3

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

coderabbitai

Actionable comments posted: 19

🔭 Outside diff range comments (2)

components/shared/shell/Header.tsx (1)
3-30: Loading component imported but never displayed

CI flags the unused import. Either remove it or render it while the session is loading:
-  if (status === 'loading' || !data) {
-    return null;
-  }
+  if (status === 'loading' || !data) {
+    return <Loading />;
+  }
This keeps the UX responsive and satisfies ESLint.
components/auth/MagicLink.tsx (1)
15-17: Remove unused csrfToken parameter.

The csrfToken parameter is no longer needed with Clerk authentication and should be removed to clean up the interface.
-interface MagicLinkProps {
-  csrfToken: string | undefined;
-}
-
-const MagicLink = ({ csrfToken }: MagicLinkProps) => {
+const MagicLink = () => {

🧹 Nitpick comments (6)

pages/api/auth/reset-password.ts (1)
6-6: Remove unused import.

The env import is not used anywhere in the file and should be removed to clean up the code.
-import env from '@/lib/env';
components/team/Members.tsx (1)
3-3: Resolve global name shadowing issue.

The Error import shadows the global Error constructor, which can cause confusion. Consider renaming this import to avoid conflicts.
import {
- Error,
+ ErrorMessage,
  LetterAvatar,
  Loading,
} from '@/components/shared';
Then update the usage on line 43:
- return <Error message={isError.message} />;
+ return <ErrorMessage message={isError.message} />;
hooks/useSession.ts (1)
38-42: Consider providing a more helpful update function.

The current update function only logs a warning and returns null, which may confuse developers expecting NextAuth-style session updates. Consider either removing it entirely or providing a more helpful implementation.
-  // Update function for compatibility - Clerk automatically syncs user data
-  const update = async () => {
-    console.warn('Session update is not supported. User data is automatically synced.');
-    return null;
-  };
+  // Update function for compatibility - Clerk automatically syncs user data
+  const update = async () => {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn('Session update is not needed with Clerk. User data syncs automatically.');
+    }
+    // Return current session data to maintain compatibility
+    return { data, status };
+  };
.do/deploy.template.yaml (1)
12-14: Minor: quote interpolation braces to avoid unintended templating

Lines referencing ${saas-starter-kit-db.DATABASE_URL} work for DO App-Spec, but quoting them makes the YAML safer when processed by other tooling.
-          value: ${saas-starter-kit-db.DATABASE_URL}
+          value: "${saas-starter-kit-db.DATABASE_URL}"
Also applies to: 34-39
.cursor/rules/auth-security.mdc (2)
50-64: Example still implies bespoke session helpers instead of Clerk SDK

The snippet uses getCurrentUserWithTeam and session checks reminiscent of the old NextAuth flow.
Since Clerk exposes auth()/currentUser helpers, consider updating the example to:
import { auth } from "@clerk/nextjs/server"

const { userId, orgId } = auth()
if (!userId) {
  return res.status(401).json({ error: "Unauthorized" })
}

await throwIfNoTeamAccess(orgId, teamId)
await throwIfNotAllowed(userId, "team_webhook", "create")
Keeps documentation consistent with the new runtime.

6-13: Broken inline link: mdc:middleware.ts

The custom mdc: scheme won’t render on GitHub/MD; switch to a relative path (../middleware.ts) or fully qualify the URL so readers can follow it outside Cursor.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6b2dd49 and c08050d.

⛔ Files ignored due to path filters (1)

package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (44)

.cursor/rules/auth-security.mdc (1 hunks)
.cursor/rules/project-overview.mdc (1 hunks)
.cursor/rules/testing-patterns.mdc (1 hunks)
.do/deploy.template.yaml (1 hunks)
.github/workflows/main.yml (2 hunks)
CLAUDE.md (3 hunks)
CLERK_MIGRATION_GUIDE.md (0 hunks)
MIGRATION_COMPLETE.md (1 hunks)
README.md (4 hunks)
app.json (1 hunks)
components/account/ManageSessions.tsx (4 hunks)
components/account/UpdateName.tsx (3 hunks)
components/auth/GithubButton.tsx (1 hunks)
components/auth/GoogleButton.tsx (1 hunks)
components/auth/MagicLink.tsx (4 hunks)
components/shared/TeamDropdown.tsx (1 hunks)
components/shared/shell/AppShell.tsx (2 hunks)
components/shared/shell/Header.tsx (2 hunks)
components/team/Members.tsx (2 hunks)
docs/authentication.md (1 hunks)
hooks/auth.ts (1 hunks)
hooks/useAuth.ts (1 hunks)
hooks/useCustomSignout.ts (1 hunks)
hooks/useSession.ts (1 hunks)
lib/auth.ts (2 hunks)
lib/clerk.ts (0 hunks)
lib/env.ts (1 hunks)
lib/nextAuth.ts (0 hunks)
lib/session.ts (1 hunks)
package.json (0 hunks)
pages/_app.tsx (2 hunks)
pages/api/auth/[...nextauth].ts (0 hunks)
pages/api/auth/custom-signout.ts (0 hunks)
pages/api/auth/reset-password.ts (1 hunks)
pages/api/password.ts (1 hunks)
pages/api/sessions/index.ts (1 hunks)
pages/auth/idp-login.tsx (2 hunks)
pages/auth/sso/index.tsx (3 hunks)
pages/invitations/[token].tsx (1 hunks)
pages/settings/security.tsx (1 hunks)
pages/teams/switch.tsx (1 hunks)
tsconfig.json (1 hunks)
types/next-auth.d.ts (0 hunks)
types/next.ts (1 hunks)

💤 Files with no reviewable changes (7)

lib/clerk.ts
package.json
pages/api/auth/[...nextauth].ts
types/next-auth.d.ts
CLERK_MIGRATION_GUIDE.md
pages/api/auth/custom-signout.ts
lib/nextAuth.ts

🧰 Additional context used

📓 Path-based instructions (24)

`components/**/*`: React UI components are organized by feature in `/components`...

components/**/*: React UI components are organized by feature in /components and shared components in /components/shared
Tailwind CSS with DaisyUI is used for styling UI components

📄 Source: CodeRabbit Inference Engine (CLAUDE.md)