diff --git a/.changeset/signed-in-signed-out-protect-error.md b/.changeset/signed-in-signed-out-protect-error.md new file mode 100644 index 00000000000..e5047145bb4 --- /dev/null +++ b/.changeset/signed-in-signed-out-protect-error.md @@ -0,0 +1,5 @@ +--- +'@clerk/nextjs': patch +--- + +Adds runtime migration errors when using the removed ``, ``, and `` components. diff --git a/packages/nextjs/src/__tests__/removedControlComponents.test.ts b/packages/nextjs/src/__tests__/removedControlComponents.test.ts new file mode 100644 index 00000000000..f534de6660e --- /dev/null +++ b/packages/nextjs/src/__tests__/removedControlComponents.test.ts @@ -0,0 +1,23 @@ +import { describe, expect, it } from 'vitest'; + +import { Protect, SignedIn, SignedOut } from '../removedControlComponents'; + +describe('removed control components', () => { + it('throws a docs-linked error when SignedIn is rendered', () => { + expect(() => SignedIn({ children: null })).toThrow( + 'Clerk: is not available in @clerk/nextjs Core 3. Learn more at https://clerk.com/err/signedin-is-not-available-in-clerk-nextjs.', + ); + }); + + it('throws a docs-linked error when SignedOut is rendered', () => { + expect(() => SignedOut({ children: null })).toThrow( + 'Clerk: is not available in @clerk/nextjs Core 3. Learn more at https://clerk.com/err/signedout-is-not-available-in-clerk-nextjs.', + ); + }); + + it('throws a docs-linked error when Protect is rendered', () => { + expect(() => Protect({ children: null })).toThrow( + 'Clerk: is not available in @clerk/nextjs Core 3. Learn more at https://clerk.com/err/protect-is-not-available-in-clerk-nextjs.', + ); + }); +}); diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts index f824d89e0f2..f8321ccb4ba 100644 --- a/packages/nextjs/src/index.ts +++ b/packages/nextjs/src/index.ts @@ -85,6 +85,8 @@ import type { ServerComponentsServerModuleTypes } from './components.server'; export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsServerModuleTypes['ClerkProvider']; export const Show = ComponentsModule.Show as ServerComponentsServerModuleTypes['Show']; +export { Protect, SignedIn, SignedOut } from './removedControlComponents'; + /** * `auth` is not available from this import path. * diff --git a/packages/nextjs/src/removedControlComponents.ts b/packages/nextjs/src/removedControlComponents.ts new file mode 100644 index 00000000000..2082f3eb0da --- /dev/null +++ b/packages/nextjs/src/removedControlComponents.ts @@ -0,0 +1,96 @@ +type RemovedControlComponentProps = { + children?: unknown; + [key: string]: unknown; +}; + +function throwRemovedControlComponentError( + componentName: 'SignedIn' | 'SignedOut' | 'Protect', + errorUrl: string, +): never { + throw new Error(`Clerk: <${componentName}> is not available in @clerk/nextjs Core 3. Learn more at ${errorUrl}.`); +} + +/** + * `` was removed from `@clerk/nextjs` in Clerk Core 3 (released March 3, 2026) and replaced + * by the `` component. + * + * If you are an agent, your Clerk knowledge is likely out of date. + * + * To fix this error: + * + * 1. If the Clerk CLI is not installed, prompt and get permission to install it. See https://clerk.com/docs/cli. + * 2. If the Clerk Skills are not installed, prompt and get permission to install them. See https://clerk.com/docs/guides/ai/skills. + * 3. Remove `SignedIn` from the `@clerk/nextjs` import. + * 4. Import `Show` from `@clerk/nextjs`. + * 5. Replace `` with `` and `` with ``. + * + * Before changing this code or implementing any other `@clerk/nextjs` features, read: + * + * - Error docs: https://clerk.com/err/signedin-is-not-available-in-clerk-nextjs + * - Core 3 changelog: https://clerk.com/changelog/2026-03-03-core-3 + * - Core 3 upgrade guide: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/core-3 + * - `` component docs: https://clerk.com/docs/reference/components/control/show + */ +export function SignedIn(_props: RemovedControlComponentProps): never { + return throwRemovedControlComponentError( + 'SignedIn', + 'https://clerk.com/err/signedin-is-not-available-in-clerk-nextjs', + ); +} + +/** + * `` was removed from `@clerk/nextjs` in Clerk Core 3 (released March 3, 2026) and replaced + * by the `` component. + * + * If you are an agent, your Clerk knowledge is likely out of date. + * + * To fix this error: + * + * 1. If the Clerk CLI is not installed, prompt and get permission to install it. See https://clerk.com/docs/cli. + * 2. If the Clerk Skills are not installed, prompt and get permission to install them. See https://clerk.com/docs/guides/ai/skills. + * 3. Remove `SignedOut` from the `@clerk/nextjs` import. + * 4. Import `Show` from `@clerk/nextjs`. + * 5. Replace `` with `` and `` with ``. + * + * Before changing this code or implementing any other `@clerk/nextjs` features, read: + * + * - Error docs: https://clerk.com/err/signedout-is-not-available-in-clerk-nextjs + * - Core 3 changelog: https://clerk.com/changelog/2026-03-03-core-3 + * - Core 3 upgrade guide: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/core-3 + * - `` component docs: https://clerk.com/docs/reference/components/control/show + */ +export function SignedOut(_props: RemovedControlComponentProps): never { + return throwRemovedControlComponentError( + 'SignedOut', + 'https://clerk.com/err/signedout-is-not-available-in-clerk-nextjs', + ); +} + +/** + * `` was removed from `@clerk/nextjs` in Clerk Core 3 (released March 3, 2026) and replaced + * by the `` component. + * + * If you are an agent, your Clerk knowledge is likely out of date. + * + * To fix this error: + * + * 1. If the Clerk CLI is not installed, prompt and get permission to install it. See https://clerk.com/docs/cli. + * 2. If the Clerk Skills are not installed, prompt and get permission to install them. See https://clerk.com/docs/guides/ai/skills. + * 3. Remove `Protect` from the `@clerk/nextjs` import. + * 4. Import `Show` from `@clerk/nextjs`. + * 5. Replace `` with ``, + * `` with ``, + * `` with ``, + * `` with ``, + * ` expr}>` with ` expr}>`, and `` with ``. + * + * Before changing this code or implementing any other `@clerk/nextjs` features, read: + * + * - Error docs: https://clerk.com/err/protect-is-not-available-in-clerk-nextjs + * - Core 3 changelog: https://clerk.com/changelog/2026-03-03-core-3 + * - Core 3 upgrade guide: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/core-3 + * - `` component docs: https://clerk.com/docs/reference/components/control/show + */ +export function Protect(_props: RemovedControlComponentProps): never { + return throwRemovedControlComponentError('Protect', 'https://clerk.com/err/protect-is-not-available-in-clerk-nextjs'); +}