Create Auth.js migration guide

apps/api/app/webhooks/clerk/route.ts

@@ -1,11 +1,11 @@
+import { analytics } from '@repo/analytics/posthog/server';
 import type {
   DeletedObjectJSON,
   OrganizationJSON,
   OrganizationMembershipJSON,
   UserJSON,
   WebhookEvent,
-} from '@clerk/nextjs/server';
-import { analytics } from '@repo/analytics/posthog/server';
+} from '@repo/auth/server';
 import { env } from '@repo/env';
 import { log } from '@repo/observability/log';
 import { headers } from 'next/headers';

apps/api/app/webhooks/stripe/route.ts

@@ -1,5 +1,5 @@
-import { clerkClient } from '@clerk/nextjs/server';
 import { analytics } from '@repo/analytics/posthog/server';
+import { clerkClient } from '@repo/auth/server';
 import { env } from '@repo/env';
 import { parseError } from '@repo/observability/error';
 import { log } from '@repo/observability/log';

apps/api/package.json

@@ -10,8 +10,8 @@
     "stripe": "stripe listen --forward-to localhost:3002/webhooks/stripe"
   },
   "dependencies": {
-    "@clerk/nextjs": "^6.3.4",
     "@repo/analytics": "workspace:*",
+    "@repo/auth": "workspace:*",
     "@repo/database": "workspace:*",
     "@repo/design-system": "workspace:*",
     "@repo/env": "workspace:*",

apps/app/app/(authenticated)/components/posthog-identifier.tsx

@@ -1,7 +1,7 @@
 'use client';
 
-import { useUser } from '@clerk/nextjs';
 import { analytics } from '@repo/analytics/posthog/client';
+import { useUser } from '@repo/auth/client';
 import { usePathname, useSearchParams } from 'next/navigation';
 import { useEffect, useRef } from 'react';
 

apps/app/app/(authenticated)/components/sidebar.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { OrganizationSwitcher, UserButton } from '@clerk/nextjs';
+import { OrganizationSwitcher, UserButton } from '@repo/auth/client';
 import { ModeToggle } from '@repo/design-system/components/mode-toggle';
 import {
   Collapsible,

apps/app/app/(authenticated)/layout.tsx

@@ -1,4 +1,4 @@
-import { auth, currentUser } from '@clerk/nextjs/server';
+import { auth, currentUser } from '@repo/auth/server';
 import { SidebarProvider } from '@repo/design-system/components/ui/sidebar';
 import { showBetaFeature } from '@repo/feature-flags';
 import arcjet, { detectBot, request } from '@repo/security';

apps/app/app/(authenticated)/page.tsx

@@ -1,4 +1,4 @@
-import { auth } from '@clerk/nextjs/server';
+import { auth } from '@repo/auth/server';
 import { database } from '@repo/database';
 import {
   Breadcrumb,

apps/app/app/actions/users/get.ts

@@ -4,7 +4,7 @@ import {
   type OrganizationMembership,
   auth,
   clerkClient,
-} from '@clerk/nextjs/server';
+} from '@repo/auth/server';
 import { tailwind } from '@repo/tailwind-config';
 
 const getName = (user: OrganizationMembership): string | undefined => {

apps/app/app/actions/users/search.ts

@@ -4,7 +4,7 @@ import {
   type OrganizationMembership,
   auth,
   clerkClient,
-} from '@clerk/nextjs/server';
+} from '@repo/auth/server';
 import Fuse from 'fuse.js';
 
 const getName = (user: OrganizationMembership): string | undefined => {

apps/app/app/api/collaboration/auth/route.ts

@@ -1,4 +1,4 @@
-import { auth, currentUser } from '@clerk/nextjs/server';
+import { auth, currentUser } from '@repo/auth/server';
 import { authenticate } from '@repo/collaboration/auth';
 import { tailwind } from '@repo/tailwind-config';
 

apps/app/middleware.ts

@@ -1,6 +1,6 @@
-import { clerkMiddleware } from '@clerk/nextjs/server';
+import { authMiddleware } from '@repo/auth/middleware';
 
-export default clerkMiddleware();
+export default authMiddleware();
 
 export const config = {
   matcher: [

apps/app/package.json

@@ -9,7 +9,6 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@clerk/nextjs": "^6.3.4",
     "@prisma/client": "5.22.0",
     "@repo/auth": "workspace:*",
     "@repo/analytics": "workspace:*",

apps/web/middleware.ts

@@ -1,4 +1,4 @@
-import { clerkMiddleware } from '@clerk/nextjs/server';
+import { authMiddleware } from '@repo/auth/middleware';
 import arcjet, { detectBot } from '@repo/security';
 import { NextResponse } from 'next/server';
 
@@ -21,7 +21,7 @@ const aj = arcjet.withRule(
   })
 );
 
-export default clerkMiddleware(async (_auth, request) => {
+export default authMiddleware(async (_auth, request) => {
   const decision = await aj.protect(request);
 
   if (

apps/web/package.json

@@ -10,7 +10,6 @@
   },
   "dependencies": {
     "@arcjet/next": "1.0.0-alpha.28",
-    "@clerk/nextjs": "^6.3.4",
     "@content-collections/mdx": "^0.2.0",
     "@radix-ui/react-icons": "^1.3.2",
     "@repo/design-system": "workspace:*",

docs/authentication/authjs.mdx

@@ -0,0 +1,132 @@
+---
+title: Switch to Auth.js
+description: How to switch from Clerk to Auth.js.
+---
+
+<Warning>
+next-forge support for Auth.js is currently blocked by [this issue](https://github.com/nextauthjs/next-auth/issues/11076).
+</Warning>
+
+Here's how to switch from Clerk to [Auth.js](https://authjs.dev/).
+
+## 1. Replace the dependencies
+
+Uninstall the existing Clerk dependencies from the `auth` package...
+
+```sh Terminal
+pnpm remove @clerk/nextjs @clerk/themes @clerk/types --filter auth
+```
+
+... and install the Auth.js dependencies.
+
+```sh Terminal
+pnpm add next-auth@beta --filter auth
+```
+
+## 2. Generate an Auth.js secret
+
+Auth.js requires a random value secret, used by the library to encrypt tokens and email verification hashes. In each of the relevant app directories, generate a secret with the following command:
+
+```sh Terminal
+cd apps/app && npx auth secret
+cd apps/web && npx auth secret
+cd apps/api && npx auth secret
+```
+
+This will automatically add an `AUTH_SECRET` environment variable to the `.env.local` file in each directory.
+
+## 3. Replace the relevant files
+
+Delete the existing `client.ts` and `server.ts` files in the `auth` package. Then, create the following file:
+
+```tsx packages/auth/index.ts
+import NextAuth from "next-auth";
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+  providers: [],
+});
+```
+
+## 4. Update the middleware
+
+Update the `middleware.ts` file in the `auth` package with the following content:
+
+```tsx packages/auth/middleware.ts
+import 'server-only';
+
+export { auth as authMiddleware } from './';
+```
+
+## 5. Update the auth components
+
+Auth.js has no concept of "sign up", so we'll use the `signIn` function to sign up users. Update both the `sign-in.tsx` and `sign-up.tsx` components in the `auth` package with the same content:
+
+<CodeGroup>
+
+```tsx packages/auth/components/sign-in.tsx
+import { signIn } from '../';
+
+export const SignIn = () => (
+  <form
+    action={async () => {
+      "use server";
+      await signIn();
+    }}
+  >
+    <button type="submit">Sign in</button>
+  </form>
+);
+```
+
+```tsx packages/auth/components/sign-up.tsx
+import { signIn } from '../';
+
+export const SignUp = () => (
+  <form
+    action={async () => {
+      "use server";
+      await signIn();
+    }}
+  >
+    <button type="submit">Sign up</button>
+  </form>
+);
+```
+
+</CodeGroup>
+
+## 6. Update the Provider file
+
+Auth.js has no concept of a Provider as a higher-order component, so you can either remove it entirely or just replace it with a stub, like so:
+
+```tsx packages/auth/provider.tsx
+import type { ReactNode } from 'react';
+
+type AuthProviderProps = {
+  children: ReactNode;
+};
+
+export const AuthProvider = ({ children }: AuthProviderProps) => children;
+```
+
+## 7. Create an auth route handler
+
+In your `app` application, create an auth route handler file with the following content:
+
+```tsx apps/app/api/auth/[...nextauth]/route.ts
+import { handlers } from "@repo/auth"
+
+export const { GET, POST } = handlers;
+```
+
+## 8. Update your apps
+
+From here, you'll need to replace any remaining Clerk implementations in your apps with Auth.js references. This means swapping out references like:
+
+```tsx page.tsx
+const { orgId } = await auth();
+const { redirectToSignIn } = await auth();
+const user = await currentUser();
+```
+
+Etcetera. Keep in mind that you'll need to build your own "organization" logic as Auth.js doesn't have a concept of organizations.

docs/authentication.mdx → docs/authentication/overview.mdx

@@ -1,9 +1,9 @@
 ---
-title: Authentication
+title: Overview
 description: We use Clerk to handle authentication, user and organization management.
 ---
 
-[Clerk](https://clerk.com/) is used for authentication in next-forge. Clerk provides a complete authentication and user management solution that integrates seamlessly with Next.js applications.
+next-forge manages authentication through the use of a `auth` package. By default, this package is a wrapper around [Clerk](https://clerk.com/) which provides a complete authentication and user management solution that integrates seamlessly with Next.js applications.
 
 ## In-App
 

docs/mint.json

@@ -53,7 +53,10 @@
           "group": "Analytics",
           "pages": ["analytics/web", "analytics/product"]
         },
-        "authentication",
+        {
+          "group": "Authentication",
+          "pages": ["authentication/overview", "authentication/authjs"]
+        },
         "blog",
         "bundle-analysis",
         "collaboration",

packages/auth/client.ts

@@ -0,0 +1 @@
+export * from '@clerk/nextjs';

packages/auth/middleware.ts

@@ -0,0 +1 @@
+export { clerkMiddleware as authMiddleware } from '@clerk/nextjs/server';

packages/auth/package.json

@@ -7,7 +7,8 @@
     "@clerk/themes": "^2.1.45",
     "@repo/tailwind-config": "workspace:*",
     "next-themes": "^0.4.3",
-    "react": "^18.3.1"
+    "react": "^18.3.1",
+    "server-only": "^0.0.1"
   },
   "devDependencies": {
     "@clerk/types": "^4.34.0",

packages/auth/server.ts

@@ -0,0 +1,3 @@
+import 'server-only';
+
+export * from '@clerk/nextjs/server';

packages/feature-flags/lib/create-flag.ts

@@ -1,5 +1,5 @@
-import { auth } from '@clerk/nextjs/server';
 import { analytics } from '@repo/analytics/posthog/server';
+import { auth } from '@repo/auth/server';
 import { unstable_flag as flag } from '@vercel/flags/next';
 
 export const createFlag = (key: string) =>

packages/feature-flags/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "dependencies": {
-    "@clerk/nextjs": "^6.3.4",
+    "@repo/auth": "workspace:*",
     "@repo/analytics": "workspace:*",
     "@repo/design-system": "workspace:*",
     "@vercel/flags": "^2.6.3"

packages/webhooks/lib/svix.ts

@@ -1,5 +1,5 @@
 import 'server-only';
-import { auth } from '@clerk/nextjs/server';
+import { auth } from '@repo/auth/server';
 import { env } from '@repo/env';
 import { Svix } from 'svix';
 

packages/webhooks/package.json

@@ -3,8 +3,8 @@
   "version": "0.0.0",
   "private": true,
   "dependencies": {
+    "@repo/auth": "workspace:*",
     "@repo/env": "workspace:*",
-    "@clerk/nextjs": "^6.3.4",
     "svix": "^1.40.0"
   },
   "devDependencies": {