Skip to content

[DO NOT MERGE] add shadcn nextjs quickstart option #2506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[DO NOT MERGE] add shadcn nextjs quickstart option #2506

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2153b36
add shadcn nextjs quickstart option
alexcarpenter Aug 15, 2025
95aa491
add next steps
alexcarpenter Aug 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
355 changes: 208 additions & 147 deletions docs/quickstarts/nextjs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,154 +203,215 @@ sdk: nextjs
<If condition={!experiment.enabled}>
<LLMPrompt displayText="Use this pre-built prompt to get started faster." src="prompts/nextjs-quickstart.md" />

<Steps>
## Create a new Next.js application
<Tabs items={["Manual install", "shadcn/ui CLI"]}>
<Tab>
<Steps>
## Create a new Next.js application

Run the following command to [create a new Next.js application](https://nextjs.org/docs/getting-started/installation). It will create an app with the name `my-clerk-app`, but you can replace it with any name you want.

<CodeBlockTabs options={["npm", "yarn", "pnpm", "bun"]}>
```bash {{ filename: 'terminal' }}
npm create next-app@latest my-clerk-app -- --yes
```

```bash {{ filename: 'terminal' }}
yarn create next-app my-clerk-app --yes
```

```bash {{ filename: 'terminal' }}
pnpm create next-app my-clerk-app --yes
```

```bash {{ filename: 'terminal' }}
bun create next-app my-clerk-app --yes
```
</CodeBlockTabs>

## Install `@clerk/nextjs`

Run the following command to install the Next.js SDK:

<CodeBlockTabs options={["npm", "yarn", "pnpm", "bun"]}>
```bash {{ filename: 'terminal' }}
npm install @clerk/nextjs
```

```bash {{ filename: 'terminal' }}
yarn add @clerk/nextjs
```

```bash {{ filename: 'terminal' }}
pnpm add @clerk/nextjs
```

```bash {{ filename: 'terminal' }}
bun add @clerk/nextjs
```
</CodeBlockTabs>

## Add `clerkMiddleware()` to your app

`clerkMiddleware()` grants you access to user authentication state throughout your app.

1. Create a `middleware.ts` file.

Run the following command to [create a new Next.js application](https://nextjs.org/docs/getting-started/installation). It will create an app with the name `my-clerk-app`, but you can replace it with any name you want.
- If you're using the `/src` directory, create `middleware.ts` in the `/src` directory.
- If you're not using the `/src` directory, create `middleware.ts` in the root directory.

<CodeBlockTabs options={["npm", "yarn", "pnpm", "bun"]}>
```bash {{ filename: 'terminal' }}
npm create next-app@latest my-clerk-app -- --yes
```
1. In your `middleware.ts` file, export the `clerkMiddleware()` helper:

```tsx {{ filename: 'middleware.ts' }}
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

export const config = {
matcher: [
// Skip Next.js internals and all static files, unless found in search params
'/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
// Always run for API routes
'/(api|trpc)(.*)',
],
}
```

1. By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection for routes. See the [`clerkMiddleware()` reference](/docs/references/nextjs/clerk-middleware) to learn how to require authentication for specific routes.

## Add `<ClerkProvider>` and Clerk components to your app

1. Add the [`<ClerkProvider>`](/docs/components/clerk-provider) component to your app's layout. This component provides Clerk's authentication context to your app.
1. Copy and paste the following file into your `layout.tsx` file. This creates a header with Clerk's [prebuilt components](/docs/components/overview) to allow users to sign in and out.

```tsx {{ filename: 'app/layout.tsx', mark: [[2, 9], 34, [37, 45], 49] }}
import type { Metadata } from 'next'
import {
ClerkProvider,
SignInButton,
SignUpButton,
SignedIn,
SignedOut,
UserButton,
} from '@clerk/nextjs'
import { Geist, Geist_Mono } from 'next/font/google'
import './globals.css'

const geistSans = Geist({
variable: '--font-geist-sans',
subsets: ['latin'],
})

const geistMono = Geist_Mono({
variable: '--font-geist-mono',
subsets: ['latin'],
})

```bash {{ filename: 'terminal' }}
yarn create next-app my-clerk-app --yes
```

```bash {{ filename: 'terminal' }}
pnpm create next-app my-clerk-app --yes
```

```bash {{ filename: 'terminal' }}
bun create next-app my-clerk-app --yes
```
</CodeBlockTabs>

## Install `@clerk/nextjs`

Run the following command to install the Next.js SDK:

<CodeBlockTabs options={["npm", "yarn", "pnpm", "bun"]}>
```bash {{ filename: 'terminal' }}
npm install @clerk/nextjs
```

```bash {{ filename: 'terminal' }}
yarn add @clerk/nextjs
```

```bash {{ filename: 'terminal' }}
pnpm add @clerk/nextjs
```

```bash {{ filename: 'terminal' }}
bun add @clerk/nextjs
```
</CodeBlockTabs>

## Add `clerkMiddleware()` to your app

`clerkMiddleware()` grants you access to user authentication state throughout your app.

1. Create a `middleware.ts` file.

- If you're using the `/src` directory, create `middleware.ts` in the `/src` directory.
- If you're not using the `/src` directory, create `middleware.ts` in the root directory.

1. In your `middleware.ts` file, export the `clerkMiddleware()` helper:

```tsx {{ filename: 'middleware.ts' }}
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

export const config = {
matcher: [
// Skip Next.js internals and all static files, unless found in search params
'/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
// Always run for API routes
'/(api|trpc)(.*)',
],
}
```

1. By default, `clerkMiddleware()` will not protect any routes. All routes are public and you must opt-in to protection for routes. See the [`clerkMiddleware()` reference](/docs/references/nextjs/clerk-middleware) to learn how to require authentication for specific routes.

## Add `<ClerkProvider>` and Clerk components to your app

1. Add the [`<ClerkProvider>`](/docs/components/clerk-provider) component to your app's layout. This component provides Clerk's authentication context to your app.
1. Copy and paste the following file into your `layout.tsx` file. This creates a header with Clerk's [prebuilt components](/docs/components/overview) to allow users to sign in and out.

```tsx {{ filename: 'app/layout.tsx', mark: [[2, 9], 34, [37, 45], 49] }}
import type { Metadata } from 'next'
import {
ClerkProvider,
SignInButton,
SignUpButton,
SignedIn,
SignedOut,
UserButton,
} from '@clerk/nextjs'
import { Geist, Geist_Mono } from 'next/font/google'
import './globals.css'

const geistSans = Geist({
variable: '--font-geist-sans',
subsets: ['latin'],
})

const geistMono = Geist_Mono({
variable: '--font-geist-mono',
subsets: ['latin'],
})

export const metadata: Metadata = {
title: 'Clerk Next.js Quickstart',
description: 'Generated by create next app',
}

export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode
}>) {
return (
<ClerkProvider>
<html lang="en">
<body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
<header className="flex justify-end items-center p-4 gap-4 h-16">
<SignedOut>
<SignInButton />
<SignUpButton>
<button className="bg-[#6c47ff] text-white rounded-full font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 cursor-pointer">
Sign Up
</button>
</SignUpButton>
</SignedOut>
<SignedIn>
<UserButton />
</SignedIn>
</header>
{children}
</body>
</html>
</ClerkProvider>
)
}
```

## Create your first user

<Include src="_partials/nextjs/create-first-user" />

## It's time to build!

You've added Clerk to your Next.js app 🎉. From here, you can continue developing your application.

To make configuration changes to your Clerk development instance, claim the Clerk keys that were generated for you by selecting **Claim your application** in the bottom right of your app. This will associate the application with your Clerk account.
</Steps>

## Next steps

<Include src="_partials/nextjs/next-steps" />
export const metadata: Metadata = {
title: 'Clerk Next.js Quickstart',
description: 'Generated by create next app',
}

export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode
}>) {
return (
<ClerkProvider>
<html lang="en">
<body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
<header className="flex justify-end items-center p-4 gap-4 h-16">
<SignedOut>
<SignInButton />
<SignUpButton>
<button className="bg-[#6c47ff] text-white rounded-full font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 cursor-pointer">
Sign Up
</button>
</SignUpButton>
</SignedOut>
<SignedIn>
<UserButton />
</SignedIn>
</header>
{children}
</body>
</html>
</ClerkProvider>
)
}
```

## Create your first user

<Include src="_partials/nextjs/create-first-user" />

## It's time to build!

You've added Clerk to your Next.js app 🎉. From here, you can continue developing your application.

To make configuration changes to your Clerk development instance, claim the Clerk keys that were generated for you by selecting **Claim your application** in the bottom right of your app. This will associate the application with your Clerk account.
</Steps>

## Next steps

<Include src="_partials/nextjs/next-steps" />
</Tab>

<Tab>
<Steps>
## Create a new Next.js application

Run the following command to [create a new Next.js application](https://nextjs.org/docs/getting-started/installation).

<CodeBlockTabs options={["npm", "yarn", "pnpm", "bun"]}>
```bash {{ filename: 'terminal' }}
npm create next-app@latest
```

```bash {{ filename: 'terminal' }}
yarn create next-app my-clerk-app
```

```bash {{ filename: 'terminal' }}
pnpm create next-app my-clerk-app
```

```bash {{ filename: 'terminal' }}
bun create next-app my-clerk-app
```
</CodeBlockTabs>

## Install quickstart via shadcn/ui CLI

<CodeBlockTabs options={["npm", "pnpm", "yarn", "bun"]}>
```bash {{ filename: 'terminal' }}
npx shadcn@latest add https://clerk.com/r/nextjs-quickstart.json
```

```bash {{ filename: 'terminal' }}
pnpm dlx shadcn@latest add https://clerk.com/r/nextjs-quickstart.json
```

```bash {{ filename: 'terminal' }}
yarn shadcn@latest add https://clerk.com/r/nextjs-quickstart.json
```

```bash {{ filename: 'terminal' }}
bunx --bun shadcn@latest add https://clerk.com/r/nextjs-quickstart.json
```
</CodeBlockTabs>

## Create your first user

<Include src="_partials/nextjs/create-first-user" />

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to include the "It's time to build!" step here like the non-shadcn one?

## Next steps

<Cards>
- [Install Clerk with shadcn/ui CLI](/docs/references/nextjs/shadcn)
- Learn how to install Clerk with the shadcn/ui CLI.
Comment on lines +411 to +412
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can improve this copy. This makes it seem like another quickstart approach. Should next steps be more fleshed out like the other quickstart?

</Cards>
</Steps>
</Tab>
</Tabs>
</If>