Protect Client Components

What you'll cover

• Protect a Client Component with protectClientPage()
• Customize where users return after signing in
• Restrict access based on group membership
• Render custom UI for unauthenticated users or users without required permissions

Before you begin

This guide assumes you’ve completed the Next.js App Router quickstart.

You should already have:

• A Next.js App Router project
• Environment variables configured in .env.local
• Authentication middleware registered
• Any unprotected routes explicitly configured (matched routes are protected by default)

Protect a Client Component

Create a Client Component and wrap it with protectClientPage().

"use client";

import { MonoCloudUser } from "@monocloud/auth-nextjs";
import { protectClientPage } from "@monocloud/auth-nextjs/client";

type Props = {
  user: MonoCloudUser;
};

const Home = ({ user }: Props) => {
  return (
    <div>Hi {user.email}</div>
  );
};

export default protectClientPage(Home);

How it works:

• The component runs in the browser
• Authentication state is resolved client-side
• Unauthenticated users are redirected to sign in
• After authentication, the user object is injected as a prop

Client-side behavior

protectClientPage() runs entirely in the browser.

This means:

• Authentication checks happen on the client after the page loads
• The component may briefly render while authentication state is being resolved
• Redirects and access control occur client-side
• This helper is intended for UI protection, not backend security

For protecting sensitive data or enforcing authorization on the server, use protectPage() or protectApi() instead.

Customize the return URL

By default, users are returned to the page they attempted to access.

To redirect users to a specific route after authentication, pass a returnUrl.

export default protectClientPage(Home, {
  returnUrl: "/dashboard",
});

After authentication, users are redirected to http://localhost:3000/dashboard

Restrict access by group

You can restrict access to users belonging to specific groups.

Handle access denied (Unauthenticated)

Use onAccessDenied to render custom UI when the user is not authenticated.

export default protectClientPage(Home, {
  onAccessDenied: () => (
    <div>
      <h1>Access Denied</h1>
      <p>Please sign in to continue.</p>
    </div>
  )
});

How it works:

• Runs when no authenticated session exists.
• If onAccessDenied is not provided, the user is automatically redirected to the sign-in flow.

Handle access denied (Group authorization)

Use onGroupAccessDenied to render custom UI when the user is authenticated but does not belong to the required group. This callback receives the authenticated user.

export default protectClientPage(Home, {
  groups: ["admin"],
  onGroupAccessDenied: (user) => (
    <div>
      <h1>Unauthorized</h1>
      <p>User {user.email}, does not have access to this page.</p>
    </div>
  )
});

How it works:

• Runs when a valid session exists but the group check fails.
• If onGroupAccessDenied is not provided, a default Access Denied message is rendered.

Handle authentication errors

protectClientPage() supports an onError callback to render fallback UI when authentication fails (for example, due to network issues).

export default protectClientPage(Home, {
  onError: (error: Error) => (
    <div>
      Error: {error.message}
    </div>
  ),
});

With this configuration:

• If authentication succeeds, the component renders normally
• If authentication fails, the fallback UI is rendered instead

You can customize this to show retry actions, support messaging, or integrate with observability tools.

Next steps

Protect other parts of your application:

• Protect server components
• Protect API routes
• Protect server actions