App Directory beta

Prerequisites

You will need to have done the following before using the App directory beta:

Install @clerk/nextjs
Create your .env.local with your keys
Create a middleware file at the root of your project

Install <ClerkProvider>

Please note that @clerk/nextjs@4.6.0 is the minimum compatible version for App Directory.

Update your root layout (/app/layout.tsx) to include the <ClerkProvider> wrapper. Please note that your layout must be configured as a server component, so there cannot be a "use client" directive at the top.

1
import { ClerkProvider } from "@clerk/nextjs/app-beta";
2
export default function RootLayout({ children }) {
3
  return (
4
    <ClerkProvider>
5
      <html lang="en">
6
        <head>
7
          <title>Next.js 13 with Clerk</title>
8
        </head>
9
        <body>{children}</body>
10
      </html>
11
    </ClerkProvider>
12
  );
13
}

1
import React from "react"
2
import { ClerkProvider } from "@clerk/nextjs/app-beta";
3
export default function RootLayout({ children }: { children: React.ReactNode }) {
4
  return (
5
    <ClerkProvider>
6
      <html lang="en">
7
        <head>
8
          <title>Next.js 13 with Clerk</title>
9
        </head>
10
        <body>{children}</body>
11
      </html>
12
    </ClerkProvider>
13
  );
14
}

New Server Component Helpers

auth()

We have introduced a new auth() helper that returns the same Authentication Object as getAuth(req) in middleware, getServerSideProps, and API routes.

Since request data like headers() and cookies() is now available in the global scope for Next.js, you no longer need to explicitly pass a Request object to Clerk.

1
import { auth } from '@clerk/nextjs/app-beta';
2
export default function Page() {
3
  const { userId } = auth();
4
  // ...
5
}

1
import { auth } from '@clerk/nextjs/app-beta';
2
export default function Page() {
3
  const { userId: string | null } = auth();
4
  // ...
5
}

currentUser()

Current user loads the User object for the authenticated user from Clerk's backend API. This is helpful if you want to render information like their first and last name directly from the server.

Under the hood, this calls fetch() so it is automatically deduped per request.

1
import { currentUser } from '@clerk/nextjs/app-beta';
2
export default async function Page() {
3
  const user = await currentUser();
4
  // ...
5
}

1
import { currentUser } from '@clerk/nextjs/app-beta';
2
import type { User } from '@clerk/nextjs/dist/api'
3
export default async function Page() {
4
  const user: User | null = await currentUser();
5
  // ...
6
}

Route handler

In the 13.2 release of Next.js they introduced route handlers, and Clerk can now support them using our helpers currentUser and auth. Below is an example of a route handler.

1
import { currentUser } from "@clerk/nextjs/app-beta"
2

3
export async function GET() {
4
  const user = await currentUser();
5
  if (!user) {
6
    return new Response('Hello, world!')
7
  }
8

9
  return new Response(`Hello, ${user.firstName}!`)
10
}

Other changes

<SignedIn> and <SignedOut>

There are currently two versions of <SignedIn> and <SignedOut>, and it is up to the developer to choose the correct one.

If you are in a server component, import from @clerk/nextjs/app-beta. This ensures that the helpers do not add unnecessary Javascript to your bundle.

import { SignedIn, SignedOut } from "@clerk/nextjs/app-beta";

If you are in a client component, import from @clerk/nextjs/app-beta/client. This depends on React.Context instead:

import { SignedIn, SignedOut } from "@clerk/nextjs/app-beta/client";

We have been informed of a React RFC that will help us improve this developer experience and are actively investigating a better solution.

The /app directory currently does not support fast "path" routing between the different pages of these components, so you should use the default "hash" routing instead:

We know this is undesirable and have submitted feedback to request support.

If you are unhappy with hash routing, you can still embed these components in the /pages directory, where "path" routing is supported.

Support

If you have any questions or feedback, please reach out on Discord to @ClerkDev on Twitter