From 553643aec50db9de8b5926f41f803e92f3ce6915 Mon Sep 17 00:00:00 2001 From: Shane Kercheval Date: Fri, 4 Sep 2026 15:08:30 -0700 Subject: [PATCH 1/5] docs(nextjs): Surface clerk init in exported doc comments - Add a keys note to the doc comments on ClerkProvider, clerkMiddleware() and auth(), the exports an agent reads when wiring up Clerk - Match the wording of the existing missing-key guidance in @clerk/shared so there is one sentence to keep true - Lead the README prerequisites and installation with clerk init and drop the claim that an existing Clerk application is required - Keep the Next.js Quickstart as the by-hand alternative --- .changeset/nextjs-cli-hint-in-types.md | 5 +++++ packages/nextjs/README.md | 8 ++++++-- packages/nextjs/src/app-router/server/auth.ts | 3 +++ packages/nextjs/src/index.ts | 4 ++++ packages/nextjs/src/server/clerkMiddleware.ts | 3 +++ 5 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 .changeset/nextjs-cli-hint-in-types.md diff --git a/.changeset/nextjs-cli-hint-in-types.md b/.changeset/nextjs-cli-hint-in-types.md new file mode 100644 index 00000000000..4cc185feb07 --- /dev/null +++ b/.changeset/nextjs-cli-hint-in-types.md @@ -0,0 +1,5 @@ +--- +'@clerk/nextjs': patch +--- + +Add a note to the `ClerkProvider`, `clerkMiddleware()` and `auth()` doc comments explaining that `npx clerk@latest init` creates a Clerk application and writes its keys with no Clerk account or login required. Update the README prerequisites and installation section to say the same, replacing the statement that an existing Clerk application and account are required. diff --git a/packages/nextjs/README.md b/packages/nextjs/README.md index d25acecb193..965af395b33 100644 --- a/packages/nextjs/README.md +++ b/packages/nextjs/README.md @@ -34,11 +34,15 @@ - Next.js 15.2.8 or later - React 18 or later - Node.js `>=20.9.0` or later -- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_nextjs). +- A Clerk application. Run `npx clerk@latest init` to create one and write its keys to your `.env` file. No Clerk account or login required. Or [create your account](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_nextjs) and copy the keys from the dashboard. ### Installation -The fastest way to get started with Clerk is by following the [Next.js Quickstart](https://clerk.com/docs/quickstarts/nextjs?utm_source=github&utm_medium=clerk_nextjs). +The fastest way to get started is the Clerk CLI. In an existing Next.js project, run `npx clerk@latest init`. In an empty directory, run `npx clerk@latest init --framework next` and it scaffolds the Next.js app as well. + +Either way it installs `@clerk/nextjs`, creates a Clerk application, writes the keys to your `.env` file, and adds ``, the middleware, and sign-in and sign-up pages. No Clerk account or login required and the command is non-interactive. + +To set things up by hand instead, follow the [Next.js Quickstart](https://clerk.com/docs/quickstarts/nextjs?utm_source=github&utm_medium=clerk_nextjs). You'll learn how to install `@clerk/nextjs`, set up your environment keys, add `` to your application, use the Clerk middleware, and use Clerk's prebuilt components. diff --git a/packages/nextjs/src/app-router/server/auth.ts b/packages/nextjs/src/app-router/server/auth.ts index f1bae2c325e..7fb04883f4a 100644 --- a/packages/nextjs/src/app-router/server/auth.ts +++ b/packages/nextjs/src/app-router/server/auth.ts @@ -73,6 +73,9 @@ export type AuthFn = GetAuthFnNoRequest & { * - Only available for App Router. * - Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions. * - Requires [`clerkMiddleware()`](https://clerk.com/docs/reference/nextjs/clerk-middleware) to be configured. + * + * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to + * your .env file. No Clerk account or login required and the command is non-interactive. See https://clerk.com/docs/cli. */ export const auth: AuthFn = (async (options?: AuthOptions) => { // eslint-disable-next-line @typescript-eslint/no-require-imports diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts index a90a2a975c6..96dd6f00129 100644 --- a/packages/nextjs/src/index.ts +++ b/packages/nextjs/src/index.ts @@ -84,6 +84,10 @@ import * as ComponentsModule from '#components'; import type { ServerComponentsServerModuleTypes } from './components.server'; +/** + * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to + * your .env file. No Clerk account or login required and the command is non-interactive. See https://clerk.com/docs/cli. + */ export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsServerModuleTypes['ClerkProvider']; export const Show = ComponentsModule.Show as ServerComponentsServerModuleTypes['Show']; diff --git a/packages/nextjs/src/server/clerkMiddleware.ts b/packages/nextjs/src/server/clerkMiddleware.ts index 98d7edb26f4..18b1e62248a 100644 --- a/packages/nextjs/src/server/clerkMiddleware.ts +++ b/packages/nextjs/src/server/clerkMiddleware.ts @@ -136,6 +136,9 @@ interface ClerkMiddleware { /** * The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through Middleware. `clerkMiddleware()` is compatible with both the App and Pages routers. + * + * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to + * your .env file. No Clerk account or login required and the command is non-interactive. See https://clerk.com/docs/cli. */ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddlewareReturn => { const [request, event] = parseRequestAndEvent(args); From d9a2014a6c97185783fe7ddbfb2349b64c15f14d Mon Sep 17 00:00:00 2001 From: Shane Kercheval Date: Fri, 4 Sep 2026 15:42:57 -0700 Subject: [PATCH 2/5] docs(nextjs): Link the CLI docs instead of a bare URL --- packages/nextjs/src/app-router/server/auth.ts | 3 ++- packages/nextjs/src/index.ts | 3 ++- packages/nextjs/src/server/clerkMiddleware.ts | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/nextjs/src/app-router/server/auth.ts b/packages/nextjs/src/app-router/server/auth.ts index 7fb04883f4a..da7f69eff57 100644 --- a/packages/nextjs/src/app-router/server/auth.ts +++ b/packages/nextjs/src/app-router/server/auth.ts @@ -75,7 +75,8 @@ export type AuthFn = GetAuthFnNoRequest & { * - Requires [`clerkMiddleware()`](https://clerk.com/docs/reference/nextjs/clerk-middleware) to be configured. * * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to - * your .env file. No Clerk account or login required and the command is non-interactive. See https://clerk.com/docs/cli. + * your .env file. No Clerk account or login required and the command is non-interactive. See the + * [Clerk CLI docs](https://clerk.com/docs/cli). */ export const auth: AuthFn = (async (options?: AuthOptions) => { // eslint-disable-next-line @typescript-eslint/no-require-imports diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts index 96dd6f00129..60ff2784f85 100644 --- a/packages/nextjs/src/index.ts +++ b/packages/nextjs/src/index.ts @@ -86,7 +86,8 @@ import type { ServerComponentsServerModuleTypes } from './components.server'; /** * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to - * your .env file. No Clerk account or login required and the command is non-interactive. See https://clerk.com/docs/cli. + * your .env file. No Clerk account or login required and the command is non-interactive. See the + * [Clerk CLI docs](https://clerk.com/docs/cli). */ export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsServerModuleTypes['ClerkProvider']; export const Show = ComponentsModule.Show as ServerComponentsServerModuleTypes['Show']; diff --git a/packages/nextjs/src/server/clerkMiddleware.ts b/packages/nextjs/src/server/clerkMiddleware.ts index 18b1e62248a..87bcbd252a7 100644 --- a/packages/nextjs/src/server/clerkMiddleware.ts +++ b/packages/nextjs/src/server/clerkMiddleware.ts @@ -138,7 +138,8 @@ interface ClerkMiddleware { * The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through Middleware. `clerkMiddleware()` is compatible with both the App and Pages routers. * * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to - * your .env file. No Clerk account or login required and the command is non-interactive. See https://clerk.com/docs/cli. + * your .env file. No Clerk account or login required and the command is non-interactive. See the + * [Clerk CLI docs](https://clerk.com/docs/cli). */ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddlewareReturn => { const [request, event] = parseRequestAndEvent(args); From 0d44f5c85a9e67796773c40ed6af0748b55499d1 Mon Sep 17 00:00:00 2001 From: Shane Kercheval Date: Fri, 4 Sep 2026 16:28:14 -0700 Subject: [PATCH 3/5] docs(nextjs): Correct the env file, npx flag and account claim - Name .env.local, the file the CLI writes for Next.js, instead of .env - Use npx -y so the command does not stop on the npx install prompt - Replace the absolute no-login claim: clerk init only skips login for agents or an empty directory, not for a signed-out user in an existing project --- packages/nextjs/README.md | 6 +++--- packages/nextjs/src/app-router/server/auth.ts | 6 +++--- packages/nextjs/src/index.ts | 6 +++--- packages/nextjs/src/server/clerkMiddleware.ts | 6 +++--- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/packages/nextjs/README.md b/packages/nextjs/README.md index 965af395b33..aed054ec9e3 100644 --- a/packages/nextjs/README.md +++ b/packages/nextjs/README.md @@ -34,13 +34,13 @@ - Next.js 15.2.8 or later - React 18 or later - Node.js `>=20.9.0` or later -- A Clerk application. Run `npx clerk@latest init` to create one and write its keys to your `.env` file. No Clerk account or login required. Or [create your account](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_nextjs) and copy the keys from the dashboard. +- A Clerk application. Run `npx -y clerk@latest init` to create one and write its keys to your `.env.local` file. No Clerk account required to get started — it can provision temporary development keys. Or [create your account](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_nextjs) and copy the keys from the dashboard. ### Installation -The fastest way to get started is the Clerk CLI. In an existing Next.js project, run `npx clerk@latest init`. In an empty directory, run `npx clerk@latest init --framework next` and it scaffolds the Next.js app as well. +The fastest way to get started is the Clerk CLI. In an existing Next.js project, run `npx -y clerk@latest init`. In an empty directory, run `npx -y clerk@latest init --framework next` and it scaffolds the Next.js app as well. -Either way it installs `@clerk/nextjs`, creates a Clerk application, writes the keys to your `.env` file, and adds ``, the middleware, and sign-in and sign-up pages. No Clerk account or login required and the command is non-interactive. +Either way it installs `@clerk/nextjs`, creates a Clerk application, writes the keys to your `.env.local` file, and adds ``, the middleware, and sign-in and sign-up pages. No Clerk account required to get started — it can provision temporary development keys. To set things up by hand instead, follow the [Next.js Quickstart](https://clerk.com/docs/quickstarts/nextjs?utm_source=github&utm_medium=clerk_nextjs). diff --git a/packages/nextjs/src/app-router/server/auth.ts b/packages/nextjs/src/app-router/server/auth.ts index da7f69eff57..050831b5d02 100644 --- a/packages/nextjs/src/app-router/server/auth.ts +++ b/packages/nextjs/src/app-router/server/auth.ts @@ -74,9 +74,9 @@ export type AuthFn = GetAuthFnNoRequest & { * - Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions. * - Requires [`clerkMiddleware()`](https://clerk.com/docs/reference/nextjs/clerk-middleware) to be configured. * - * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to - * your .env file. No Clerk account or login required and the command is non-interactive. See the - * [Clerk CLI docs](https://clerk.com/docs/cli). + * Need Clerk keys? In your terminal run `npx -y clerk@latest init`. It creates a Clerk application and writes the keys + * to your .env.local file. No Clerk account required to get started — it can provision temporary development keys. + * See the [Clerk CLI docs](https://clerk.com/docs/cli). */ export const auth: AuthFn = (async (options?: AuthOptions) => { // eslint-disable-next-line @typescript-eslint/no-require-imports diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts index 60ff2784f85..ffcf345b765 100644 --- a/packages/nextjs/src/index.ts +++ b/packages/nextjs/src/index.ts @@ -85,9 +85,9 @@ import * as ComponentsModule from '#components'; import type { ServerComponentsServerModuleTypes } from './components.server'; /** - * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to - * your .env file. No Clerk account or login required and the command is non-interactive. See the - * [Clerk CLI docs](https://clerk.com/docs/cli). + * Need Clerk keys? In your terminal run `npx -y clerk@latest init`. It creates a Clerk application and writes the keys + * to your .env.local file. No Clerk account required to get started — it can provision temporary development keys. + * See the [Clerk CLI docs](https://clerk.com/docs/cli). */ export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsServerModuleTypes['ClerkProvider']; export const Show = ComponentsModule.Show as ServerComponentsServerModuleTypes['Show']; diff --git a/packages/nextjs/src/server/clerkMiddleware.ts b/packages/nextjs/src/server/clerkMiddleware.ts index 87bcbd252a7..9a990c61adf 100644 --- a/packages/nextjs/src/server/clerkMiddleware.ts +++ b/packages/nextjs/src/server/clerkMiddleware.ts @@ -137,9 +137,9 @@ interface ClerkMiddleware { /** * The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through Middleware. `clerkMiddleware()` is compatible with both the App and Pages routers. * - * Need Clerk keys? In your terminal run `npx clerk@latest init`. It creates a Clerk application and writes the keys to - * your .env file. No Clerk account or login required and the command is non-interactive. See the - * [Clerk CLI docs](https://clerk.com/docs/cli). + * Need Clerk keys? In your terminal run `npx -y clerk@latest init`. It creates a Clerk application and writes the keys + * to your .env.local file. No Clerk account required to get started — it can provision temporary development keys. + * See the [Clerk CLI docs](https://clerk.com/docs/cli). */ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddlewareReturn => { const [request, event] = parseRequestAndEvent(args); From c90a62ce97e544810cf054df5b5d269c4c2931f1 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Mon, 7 Sep 2026 13:01:13 -0600 Subject: [PATCH 4/5] docs review --- packages/nextjs/src/app-router/server/auth.ts | 6 +++--- packages/nextjs/src/index.ts | 6 +++--- packages/nextjs/src/server/clerkMiddleware.ts | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/nextjs/src/app-router/server/auth.ts b/packages/nextjs/src/app-router/server/auth.ts index 050831b5d02..ad9b576ed72 100644 --- a/packages/nextjs/src/app-router/server/auth.ts +++ b/packages/nextjs/src/app-router/server/auth.ts @@ -74,9 +74,9 @@ export type AuthFn = GetAuthFnNoRequest & { * - Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions. * - Requires [`clerkMiddleware()`](https://clerk.com/docs/reference/nextjs/clerk-middleware) to be configured. * - * Need Clerk keys? In your terminal run `npx -y clerk@latest init`. It creates a Clerk application and writes the keys - * to your .env.local file. No Clerk account required to get started — it can provision temporary development keys. - * See the [Clerk CLI docs](https://clerk.com/docs/cli). + * To set up Clerk in your project, run `npx --yes clerk@latest init -y` from your project's root directory. + * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See + * the [Clerk CLI docs](https://clerk.com/docs/cli). */ export const auth: AuthFn = (async (options?: AuthOptions) => { // eslint-disable-next-line @typescript-eslint/no-require-imports diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts index ffcf345b765..c2b35de8734 100644 --- a/packages/nextjs/src/index.ts +++ b/packages/nextjs/src/index.ts @@ -85,9 +85,9 @@ import * as ComponentsModule from '#components'; import type { ServerComponentsServerModuleTypes } from './components.server'; /** - * Need Clerk keys? In your terminal run `npx -y clerk@latest init`. It creates a Clerk application and writes the keys - * to your .env.local file. No Clerk account required to get started — it can provision temporary development keys. - * See the [Clerk CLI docs](https://clerk.com/docs/cli). + * To set up Clerk in your project, run `npx --yes clerk@latest init -y` from your project's root directory. + * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See + * the [Clerk CLI docs](https://clerk.com/docs/cli). */ export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsServerModuleTypes['ClerkProvider']; export const Show = ComponentsModule.Show as ServerComponentsServerModuleTypes['Show']; diff --git a/packages/nextjs/src/server/clerkMiddleware.ts b/packages/nextjs/src/server/clerkMiddleware.ts index 9a990c61adf..d201fdde8a2 100644 --- a/packages/nextjs/src/server/clerkMiddleware.ts +++ b/packages/nextjs/src/server/clerkMiddleware.ts @@ -137,9 +137,9 @@ interface ClerkMiddleware { /** * The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through Middleware. `clerkMiddleware()` is compatible with both the App and Pages routers. * - * Need Clerk keys? In your terminal run `npx -y clerk@latest init`. It creates a Clerk application and writes the keys - * to your .env.local file. No Clerk account required to get started — it can provision temporary development keys. - * See the [Clerk CLI docs](https://clerk.com/docs/cli). + * To set up Clerk in your project, run `npx --yes clerk@latest init -y` from your project's root directory. + * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See + * the [Clerk CLI docs](https://clerk.com/docs/cli). */ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddlewareReturn => { const [request, event] = parseRequestAndEvent(args); From 28bd7aa5746f38f37592e1b1831ddaf6f0bc0119 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Mon, 7 Sep 2026 13:45:56 -0600 Subject: [PATCH 5/5] docs(nextjs): Restore original CLI command --- packages/nextjs/src/app-router/server/auth.ts | 2 +- packages/nextjs/src/index.ts | 2 +- packages/nextjs/src/server/clerkMiddleware.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/nextjs/src/app-router/server/auth.ts b/packages/nextjs/src/app-router/server/auth.ts index ad9b576ed72..7cd26dca683 100644 --- a/packages/nextjs/src/app-router/server/auth.ts +++ b/packages/nextjs/src/app-router/server/auth.ts @@ -74,7 +74,7 @@ export type AuthFn = GetAuthFnNoRequest & { * - Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions. * - Requires [`clerkMiddleware()`](https://clerk.com/docs/reference/nextjs/clerk-middleware) to be configured. * - * To set up Clerk in your project, run `npx --yes clerk@latest init -y` from your project's root directory. + * To set up Clerk in your project, run `npx -y clerk@latest init` from your project's root directory. * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See * the [Clerk CLI docs](https://clerk.com/docs/cli). */ diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts index c2b35de8734..585129c82d7 100644 --- a/packages/nextjs/src/index.ts +++ b/packages/nextjs/src/index.ts @@ -85,7 +85,7 @@ import * as ComponentsModule from '#components'; import type { ServerComponentsServerModuleTypes } from './components.server'; /** - * To set up Clerk in your project, run `npx --yes clerk@latest init -y` from your project's root directory. + * To set up Clerk in your project, run `npx -y clerk@latest init` from your project's root directory. * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See * the [Clerk CLI docs](https://clerk.com/docs/cli). */ diff --git a/packages/nextjs/src/server/clerkMiddleware.ts b/packages/nextjs/src/server/clerkMiddleware.ts index d201fdde8a2..2da7b688428 100644 --- a/packages/nextjs/src/server/clerkMiddleware.ts +++ b/packages/nextjs/src/server/clerkMiddleware.ts @@ -137,7 +137,7 @@ interface ClerkMiddleware { /** * The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through Middleware. `clerkMiddleware()` is compatible with both the App and Pages routers. * - * To set up Clerk in your project, run `npx --yes clerk@latest init -y` from your project's root directory. + * To set up Clerk in your project, run `npx -y clerk@latest init` from your project's root directory. * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See * the [Clerk CLI docs](https://clerk.com/docs/cli). */