feat(repo): Protect -> Show - WIP

packages/astro/src/react/controlComponents.tsx

@@ -1,13 +1,10 @@
-import type { HandleOAuthCallbackParams, PendingSessionOptions } from '@clerk/shared/types';
+import type { HandleOAuthCallbackParams, PendingSessionOptions, ProtectParams } from '@clerk/shared/types';
 import { computed } from 'nanostores';
-import type { PropsWithChildren } from 'react';
-import React, { useEffect, useState } from 'react';
+import React, { type PropsWithChildren, useEffect, useState } from 'react';
 
 import { $csrState } from '../stores/internal';
-import type { ProtectProps as _ProtectProps } from '../types';
 import { useAuth } from './hooks';
-import type { WithClerkProp } from './utils';
-import { withClerk } from './utils';
+import { withClerk, type WithClerkProp } from './utils';
 
 export function SignedOut({ children, treatPendingAsSignedOut }: PropsWithChildren<PendingSessionOptions>) {
   const { userId } = useAuth({ treatPendingAsSignedOut });
@@ -70,7 +67,7 @@ export const ClerkLoading = ({ children }: React.PropsWithChildren): JSX.Element
 };
 
 export type ProtectProps = React.PropsWithChildren<
-  _ProtectProps & { fallback?: React.ReactNode } & PendingSessionOptions
+  ProtectParams & { fallback?: React.ReactNode } & PendingSessionOptions
 >;
 
 /**
@@ -140,7 +137,7 @@ export const Protect = ({ children, fallback, treatPendingAsSignedOut, ...restAu
  */
 export const AuthenticateWithRedirectCallback = withClerk(
   ({ clerk, ...handleRedirectCallbackParams }: WithClerkProp<HandleOAuthCallbackParams>) => {
-    React.useEffect(() => {
+    useEffect(() => {
       void clerk?.handleRedirectCallback(handleRedirectCallbackParams);
     }, []);
 

packages/chrome-extension/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -15,12 +15,12 @@ exports[`public exports > should not include a breaking change 1`] = `
   "OrganizationProfile",
   "OrganizationSwitcher",
   "PricingTable",
-  "Protect",
   "RedirectToCreateOrganization",
   "RedirectToOrganizationProfile",
   "RedirectToSignIn",
   "RedirectToSignUp",
   "RedirectToUserProfile",
+  "Show",
   "SignIn",
   "SignInButton",
   "SignInWithMetamaskButton",

packages/chrome-extension/src/react/re-exports.ts

@@ -10,12 +10,12 @@ export {
   OrganizationProfile,
   OrganizationSwitcher,
   PricingTable,
-  Protect,
   RedirectToCreateOrganization,
   RedirectToOrganizationProfile,
   RedirectToSignIn,
   RedirectToSignUp,
   RedirectToUserProfile,
+  Show,
   SignIn,
   SignInButton,
   SignInWithMetamaskButton,

packages/expo/src/components/controlComponents.tsx

@@ -1 +1 @@
-export { ClerkLoaded, ClerkLoading, SignedIn, SignedOut, Protect } from '@clerk/react';
+export { ClerkLoaded, ClerkLoading, Show, SignedIn, SignedOut } from '@clerk/react';

packages/nextjs/src/app-router/server/__tests__/controlComponents.test.tsx

@@ -0,0 +1,118 @@
+import type { ShowWhenCondition } from '@clerk/shared/types';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { auth } from '../auth';
+import { Show } from '../controlComponents';
+
+vi.mock('../auth', () => ({
+  auth: vi.fn(),
+}));
+
+const mockAuth = auth as unknown as ReturnType<typeof vi.fn>;
+
+const render = async (element: Promise<React.JSX.Element | null>) => {
+  const resolved = await element;
+  if (!resolved) {
+    return '';
+  }
+  return renderToStaticMarkup(resolved);
+};
+
+const setAuthReturn = (value: { has?: (params: unknown) => boolean; userId: string | null }) => {
+  mockAuth.mockResolvedValue(value);
+};
+
+const signedInWhen: ShowWhenCondition = 'signedIn';
+const signedOutWhen: ShowWhenCondition = 'signedOut';
+
+describe('Show (App Router server)', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders children when signed in', async () => {
+    const has = vi.fn();
+    setAuthReturn({ has, userId: 'user_123' });
+
+    const html = await render(
+      Show({
+        children: <div>signed-in</div>,
+        fallback: <div>fallback</div>,
+        treatPendingAsSignedOut: false,
+        when: signedInWhen,
+      }),
+    );
+
+    expect(mockAuth).toHaveBeenCalledWith({ treatPendingAsSignedOut: false });
+    expect(html).toContain('signed-in');
+  });
+
+  it('renders children when signed out', async () => {
+    const has = vi.fn();
+    setAuthReturn({ has, userId: null });
+
+    const html = await render(
+      Show({
+        children: <div>signed-out</div>,
+        fallback: <div>fallback</div>,
+        treatPendingAsSignedOut: false,
+        when: signedOutWhen,
+      }),
+    );
+
+    expect(html).toContain('signed-out');
+  });
+
+  it('renders fallback when signed out but user is present', async () => {
+    const has = vi.fn();
+    setAuthReturn({ has, userId: 'user_123' });
+
+    const html = await render(
+      Show({
+        children: <div>signed-out</div>,
+        fallback: <div>fallback</div>,
+        treatPendingAsSignedOut: false,
+        when: signedOutWhen,
+      }),
+    );
+
+    expect(html).toContain('fallback');
+  });
+
+  it('uses has() when when is an authorization object', async () => {
+    const has = vi.fn().mockReturnValue(true);
+    setAuthReturn({ has, userId: 'user_123' });
+
+    const html = await render(
+      Show({
+        children: <div>authorized</div>,
+        fallback: <div>fallback</div>,
+        treatPendingAsSignedOut: false,
+        when: { role: 'admin' },
+      }),
+    );
+
+    expect(has).toHaveBeenCalledWith({ role: 'admin' });
+    expect(html).toContain('authorized');
+  });
+
+  it('uses predicate when when is a function', async () => {
+    const has = vi.fn().mockReturnValue(true);
+    const predicate = vi.fn().mockReturnValue(true);
+    setAuthReturn({ has, userId: 'user_123' });
+
+    const html = await render(
+      Show({
+        children: <div>predicate-pass</div>,
+        fallback: <div>fallback</div>,
+        treatPendingAsSignedOut: false,
+        when: predicate,
+      }),
+    );
+
+    expect(predicate).toHaveBeenCalledWith(has);
+    expect(html).toContain('predicate-pass');
+  });
+});

packages/nextjs/src/app-router/server/controlComponents.tsx

@@ -1,9 +1,21 @@
-import type { ProtectProps } from '@clerk/react';
-import type { PendingSessionOptions } from '@clerk/shared/types';
+import type { PendingSessionOptions, ProtectParams, ShowWhenCondition } from '@clerk/shared/types';
 import React from 'react';
 
 import { auth } from './auth';
 
+export type AppRouterProtectProps = React.PropsWithChildren<
+  ProtectParams & {
+    fallback?: React.ReactNode;
+  } & PendingSessionOptions
+>;
+
+export type AppRouterShowProps = React.PropsWithChildren<
+  PendingSessionOptions & {
+    fallback?: React.ReactNode;
+    when: ShowWhenCondition;
+  }
+>;
+
 export async function SignedIn(
   props: React.PropsWithChildren<PendingSessionOptions>,
 ): Promise<React.JSX.Element | null> {
@@ -32,7 +44,7 @@ export async function SignedOut(
  * <Protect fallback={<p>Unauthorized</p>} />
  * ```
  */
-export async function Protect(props: ProtectProps): Promise<React.JSX.Element | null> {
+export async function Protect(props: AppRouterProtectProps): Promise<React.JSX.Element | null> {
   const { children, fallback, ...restAuthorizedParams } = props;
   const { has, userId } = await auth({ treatPendingAsSignedOut: props.treatPendingAsSignedOut });
 
@@ -69,3 +81,59 @@ export async function Protect(props: ProtectProps): Promise<React.JSX.Element |
    */
   return authorized;
 }
+
+/**
+ * Use `<Show/>` to render children when an authorization or sign-in condition passes.
+ *
+ * @param props.when Condition that controls rendering. Accepts:
+ * - authorization objects such as `{ permission: "..." }`, `{ role: "..." }`, `{ feature: "..." }`, or `{ plan: "..." }`
+ * - the string `"signedIn"` to render when a user is present
+ * - the string `"signedOut"` to render when no user is present
+ * - predicate functions `(has) => boolean` that receive the `has` helper
+ * @param props.fallback Optional content rendered when the condition fails.
+ * @param props.children Content rendered when the condition passes.
+ *
+ * @example
+ * ```tsx
+ * <Show when={{ permission: "org:billing:manage" }} fallback={<p>Unauthorized</p>}>
+ *   <BillingSettings />
+ * </Show>
+ *
+ * <Show when={{ role: "admin" }}>
+ *   <AdminPanel />
+ * </Show>
+ *
+ * <Show when={(has) => has({ permission: "org:read" }) && isFeatureEnabled}>
+ *   <ProtectedFeature />
+ * </Show>
+ *
+ * <Show when="signedIn">
+ *   <Dashboard />
+ * </Show>
+ * ```
+ */
+export async function Show(props: AppRouterShowProps): Promise<React.JSX.Element | null> {
+  const { children, fallback, treatPendingAsSignedOut, when } = props;
+  const { has, userId } = await auth({ treatPendingAsSignedOut });
+
+  const resolvedWhen = when;
+  const authorized = <>{children}</>;
+  const unauthorized = fallback ? <>{fallback}</> : null;
+
+  if (typeof resolvedWhen === 'string') {
+    if (resolvedWhen === 'signedOut') {
+      return userId ? unauthorized : authorized;
+    }
+    return userId ? authorized : unauthorized;
+  }
+
+  if (!userId) {
+    return unauthorized;
+  }
+
+  if (typeof resolvedWhen === 'function') {
+    return resolvedWhen(has) ? authorized : unauthorized;
+  }
+
+  return has(resolvedWhen) ? authorized : unauthorized;
+}

packages/nextjs/src/client-boundary/controlComponents.ts

@@ -1,20 +1,20 @@
 'use client';
 
 export {
-  ClerkLoaded,
-  ClerkLoading,
+  AuthenticateWithRedirectCallback,
   ClerkDegraded,
   ClerkFailed,
-  SignedOut,
-  SignedIn,
-  Protect,
+  ClerkLoaded,
+  ClerkLoading,
+  RedirectToCreateOrganization,
+  RedirectToOrganizationProfile,
   RedirectToSignIn,
   RedirectToSignUp,
   RedirectToTasks,
   RedirectToUserProfile,
-  AuthenticateWithRedirectCallback,
-  RedirectToCreateOrganization,
-  RedirectToOrganizationProfile,
+  Show,
+  SignedIn,
+  SignedOut,
 } from '@clerk/react';
 
 export { MultisessionAppSupport } from '@clerk/react/internal';

packages/nextjs/src/components.client.ts

@@ -1,2 +1,21 @@
 export { ClerkProvider } from './client-boundary/ClerkProvider';
-export { SignedIn, SignedOut, Protect } from './client-boundary/controlComponents';
+export { Show, SignedIn, SignedOut } from './client-boundary/controlComponents';
+
+/**
+ * `<Protect>` is only available as a React Server Component in the App Router.
+ * For client-side conditional rendering, use `<Show when={...} />` instead.
+ *
+ * @example
+ * ```tsx
+ * // Server Component (App Router)
+ * <Protect permission="org:read">...</Protect>
+ *
+ * // Client Component
+ * <Show when={{ permission: "org:read" }}>...</Show>
+ * ```
+ */
+export const Protect = () => {
+  throw new Error(
+    '`<Protect>` is only available as a React Server Component. For client components, use `<Show when={...} />` instead.',
+  );
+};

packages/nextjs/src/components.server.ts

@@ -1,11 +1,12 @@
 import { ClerkProvider } from './app-router/server/ClerkProvider';
-import { Protect, SignedIn, SignedOut } from './app-router/server/controlComponents';
+import { Protect, Show, SignedIn, SignedOut } from './app-router/server/controlComponents';
 
-export { ClerkProvider, SignedOut, SignedIn, Protect };
+export { ClerkProvider, Protect, Show, SignedIn, SignedOut };
 
 export type ServerComponentsServerModuleTypes = {
   ClerkProvider: typeof ClerkProvider;
+  Protect: typeof Protect;
+  Show: typeof Show;
   SignedIn: typeof SignedIn;
   SignedOut: typeof SignedOut;
-  Protect: typeof Protect;
 };

packages/nextjs/src/index.ts

@@ -14,6 +14,7 @@ export {
   RedirectToSignUp,
   RedirectToTasks,
   RedirectToUserProfile,
+  Show,
 } from './client-boundary/controlComponents';
 
 /**
@@ -73,6 +74,10 @@ import * as ComponentsModule from '#components';
 import type { ServerComponentsServerModuleTypes } from './components.server';
 
 export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsServerModuleTypes['ClerkProvider'];
+/**
+ * Use `<Protect/>` in RSC (App Router) to restrict access based on authentication and authorization.
+ * For client components, use `<Show when={...} />` instead.
+ */
+export const Protect = ComponentsModule.Protect as ServerComponentsServerModuleTypes['Protect'];
 export const SignedIn = ComponentsModule.SignedIn as ServerComponentsServerModuleTypes['SignedIn'];
 export const SignedOut = ComponentsModule.SignedOut as ServerComponentsServerModuleTypes['SignedOut'];
-export const Protect = ComponentsModule.Protect as ServerComponentsServerModuleTypes['Protect'];

packages/react-router/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -29,13 +29,13 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "OrganizationProfile",
   "OrganizationSwitcher",
   "PricingTable",
-  "Protect",
   "RedirectToCreateOrganization",
   "RedirectToOrganizationProfile",
   "RedirectToSignIn",
   "RedirectToSignUp",
   "RedirectToTasks",
   "RedirectToUserProfile",
+  "Show",
   "SignIn",
   "SignInButton",
   "SignInWithMetamaskButton",