feat(nextjs): throw missing-env error instead of keyless bootstrap by djgould · Pull Request #9493 · clerk/javascript

djgould · 2026-08-18T18:21:20Z

Description

Part 2 of the keyless→CLI stack (#9491 → #9493 → #9487 → #9488), stacked on #9491. This is the experiment/RFC piece: promote the CLI keyless flow over SDK keyless mode.

In development, when NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY / CLERK_SECRET_KEY are missing, @clerk/nextjs no longer provisions a keyless application. All bootstrap entry points now throw via the shared errorThrower missing-key messages, which (from #9491) direct to npx clerk@latest init and state the command is non-interactive and requires no Clerk account or login (sandbox agent trials showed agents otherwise route around the CLI or invent placeholder keys). The error surfaces in both the dev server log and the dev error page. No nextjs-specific error constants are introduced.

Since missing keys throw the same error in every environment, the keylessMiddleware wrapper reduced to baseNextMiddleware and is deleted. KeylessProvider (kept for the claimed-keys prompt) now uses read-only readKeys() instead of getOrCreateKeys(), making "the SDK never mints applications" structural. Configured keys, claimed keys, and production behavior are unchanged.

Squashed from the original four commits during the simple-first stack reorder. Supersedes #9474; #9492 was collapsed into #9491 + this PR.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

🤖 Generated with Claude Code

vercel · 2026-08-18T18:21:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 18, 2026 8:43pm
swingset	Ready	Preview	Aug 18, 2026 8:43pm

changeset-bot · 2026-08-18T18:21:29Z

🦋 Changeset detected

Latest commit: 92d8817

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/backend	Patch
@clerk/nextjs	Minor
@clerk/astro	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-08-18T18:36:13Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9493

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9493

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9493

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9493

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9493

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9493

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9493

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9493

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9493

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9493

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9493

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9493

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9493

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9493

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9493

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9493

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9493

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9493

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9493

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9493

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9493

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9493

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9493

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9493

commit: 92d8817

Squashed from the original four commits of this PR (bootstrap removal, import sort, adversarial-review findings, non-interactive CLI wording) during the simple-first stack reorder. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

djgould · 2026-08-18T21:35:05Z

!snapshot

github-actions · 2026-08-18T21:38:26Z

Hey @djgould - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	4.0.16-snapshot.v20260818213555
@clerk/backend	3.16.9-snapshot.v20260818213555
@clerk/chrome-extension	3.1.73-snapshot.v20260818213555
@clerk/clerk-js	6.29.3-snapshot.v20260818213555
@clerk/electron	0.0.34-snapshot.v20260818213555
@clerk/electron-passkeys	0.0.4-snapshot.v20260818213555
@clerk/eslint-plugin	0.2.1-snapshot.v20260818213555
@clerk/expo	4.5.1-snapshot.v20260818213555
@clerk/expo-google-signin	1.0.2-snapshot.v20260818213555
@clerk/expo-passkeys	2.0.13-snapshot.v20260818213555
@clerk/express	2.1.60-snapshot.v20260818213555
@clerk/fastify	3.1.70-snapshot.v20260818213555
@clerk/headless	0.0.27-snapshot.v20260818213555
@clerk/hono	0.1.70-snapshot.v20260818213555
@clerk/localizations	4.15.5-snapshot.v20260818213555
@clerk/msw	0.0.63-snapshot.v20260818213555
@clerk/nextjs	7.8.0-snapshot.v20260818213555
@clerk/nuxt	3.0.12-snapshot.v20260818213555
@clerk/react	6.14.5-snapshot.v20260818213555
@clerk/react-router	3.6.14-snapshot.v20260818213555
@clerk/shared	4.29.3-snapshot.v20260818213555
@clerk/swingset	0.0.37-snapshot.v20260818213555
@clerk/tanstack-react-start	1.5.5-snapshot.v20260818213555
@clerk/testing	2.2.27-snapshot.v20260818213555
@clerk/ui	1.30.5-snapshot.v20260818213555
@clerk/upgrade	2.0.6-snapshot.v20260818213555
@clerk/vue	2.4.31-snapshot.v20260818213555

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@4.0.16-snapshot.v20260818213555 --save-exact

@clerk/backend

npm i @clerk/backend@3.16.9-snapshot.v20260818213555 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.73-snapshot.v20260818213555 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.29.3-snapshot.v20260818213555 --save-exact

@clerk/electron

npm i @clerk/electron@0.0.34-snapshot.v20260818213555 --save-exact

@clerk/electron-passkeys

npm i @clerk/electron-passkeys@0.0.4-snapshot.v20260818213555 --save-exact

@clerk/eslint-plugin

npm i @clerk/eslint-plugin@0.2.1-snapshot.v20260818213555 --save-exact

@clerk/expo

npm i @clerk/expo@4.5.1-snapshot.v20260818213555 --save-exact

@clerk/expo-google-signin

npm i @clerk/expo-google-signin@1.0.2-snapshot.v20260818213555 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@2.0.13-snapshot.v20260818213555 --save-exact

@clerk/express

npm i @clerk/express@2.1.60-snapshot.v20260818213555 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.70-snapshot.v20260818213555 --save-exact

@clerk/headless

npm i @clerk/headless@0.0.27-snapshot.v20260818213555 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.70-snapshot.v20260818213555 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.15.5-snapshot.v20260818213555 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.63-snapshot.v20260818213555 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.8.0-snapshot.v20260818213555 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@3.0.12-snapshot.v20260818213555 --save-exact

@clerk/react

npm i @clerk/react@6.14.5-snapshot.v20260818213555 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.6.14-snapshot.v20260818213555 --save-exact

@clerk/shared

npm i @clerk/shared@4.29.3-snapshot.v20260818213555 --save-exact

@clerk/swingset

npm i @clerk/swingset@0.0.37-snapshot.v20260818213555 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.5.5-snapshot.v20260818213555 --save-exact

@clerk/testing

npm i @clerk/testing@2.2.27-snapshot.v20260818213555 --save-exact

@clerk/ui

npm i @clerk/ui@1.30.5-snapshot.v20260818213555 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.6-snapshot.v20260818213555 --save-exact

@clerk/vue

npm i @clerk/vue@2.4.31-snapshot.v20260818213555 --save-exact

djgould mentioned this pull request Aug 18, 2026

feat(nextjs): throw missing-env error instead of keyless bootstrap #9484

Closed

9 tasks

This was referenced Aug 18, 2026

feat(shared): point missing and invalid key errors at the Clerk CLI #9491

Open

feat(nextjs): point missing and invalid key errors at the Clerk CLI #9492

Closed

github-actions Bot added nextjs backend integration labels Aug 18, 2026

This was referenced Aug 18, 2026

feat(*): remove keyless bootstrap from astro, nuxt, react-router, and tanstack-react-start #9487

Draft

chore(*): deprecate the keyless substrate ahead of removal #9488

Draft

djgould force-pushed the dg/keyless-cli/3-invalid-keys branch from 0195511 to 3093159 Compare August 18, 2026 18:29

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from bb7e2a9 to d711cd8 Compare August 18, 2026 18:29

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 18:30 View deployment

vercel Bot deployed to Preview – swingset August 18, 2026 18:32 View deployment

djgould force-pushed the dg/keyless-cli/3-invalid-keys branch from 3093159 to 8a7793f Compare August 18, 2026 20:08

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from d711cd8 to f41f7a7 Compare August 18, 2026 20:08

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 20:09 View deployment

vercel Bot deployed to Preview – swingset August 18, 2026 20:10 View deployment

djgould force-pushed the dg/keyless-cli/3-invalid-keys branch from 8a7793f to 0cddd6d Compare August 18, 2026 20:11

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from f41f7a7 to b0ade20 Compare August 18, 2026 20:11

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 20:12 View deployment

vercel Bot deployed to Preview – swingset August 18, 2026 20:13 View deployment

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from b0ade20 to 92d8817 Compare August 18, 2026 20:40

djgould deleted the branch dg/keyless-cli/3-invalid-keys August 18, 2026 20:41

djgould closed this Aug 18, 2026

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 20:41 View deployment

djgould reopened this Aug 18, 2026

vercel Bot deployed to Preview – swingset August 18, 2026 20:43 View deployment

Navigation Menu

Uh oh!

feat(nextjs): throw missing-env error instead of keyless bootstrap - #9493

feat(nextjs): throw missing-env error instead of keyless bootstrap#9493
djgould wants to merge 1 commit into
dg/keyless-cli/3-invalid-keysfrom
dg/keyless-cli/1-remove-bootstrap

djgould commented Aug 18, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

djgould commented Aug 18, 2026

Uh oh!

github-actions Bot commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

djgould commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

vercel Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

djgould commented Aug 18, 2026

Uh oh!

github-actions Bot commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

djgould commented Aug 18, 2026 •

edited

Loading

vercel Bot commented Aug 18, 2026 •

edited

Loading

changeset-bot Bot commented Aug 18, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 18, 2026 •

edited

Loading