What is add-protected-page?

This Claude skill automates the creation of secure, authenticated pages in Next.js applications using the App Router. It streamlines development by generating standardized boilerplate for protected routes, integrating Clerk authentication with the React Suspense loading pattern to ensure robust data fetching and a seamless user experience.

When should I use add-protected-page?

add-protected-page is useful in the following scenarios: • Case 1: Rapidly scaffolding a user dashboard or admin panel that requires mandatory authentication and specific loading states. • Case 2: Adding new private feature routes to a SaaS application while ensuring consistent architecture between UI components and data fetching hooks. • Case 3: Implementing secure 'Settings' or 'Profile' pages that need to handle user context safely without causing build-time errors in Next.js. • Case 4: Standardizing the Suspense-based loading pattern across a development team to eliminate manual 'isLoading' state management.

name	add-protected-page
description	Creates a protected page with Suspense loading pattern. Use when adding new pages that require authentication, creating dashboard pages, or setting up new routes.
allowed-tools	Read, Write, Edit, Glob, Grep

Add Protected Page

Creates a protected page following the Suspense loading pattern with Clerk authentication.

Structure

For a new route /my-feature:

front/
├── app/my-feature/
│   ├── page.tsx        # Auth only - wraps content in Suspense
│   └── loading.tsx     # Automatic Suspense fallback
└── components/my-feature/
    └── MyFeatureContent.tsx  # Data fetching + UI

Workflow

1. Create Page Component

// app/my-feature/page.tsx
'use client';

import { Suspense } from 'react';
import { useUser } from '@clerk/nextjs';
import { MyFeatureContent } from '@/components/my-feature/MyFeatureContent';

export default function MyFeaturePage() {
  const { user } = useUser();
  if (!user) return null; // REQUIRED for SSG

  return (
    <Suspense>
      <MyFeatureContent userId={user.id} />
    </Suspense>
  );
}

Key Points:

'use client' directive required
if (!user) return null is MANDATORY - prevents build errors
Page only handles auth, wraps content in Suspense
No data fetching here

2. Create Loading Fallback

// app/my-feature/loading.tsx
import { LoadingSpinner } from '@/components/_shared/loading-spinner';

export default function Loading() {
  return <LoadingSpinner message="Loading..." />;
}

3. Create Content Component

// components/my-feature/MyFeatureContent.tsx
'use client';

import { useMyFeatureSuspense } from '@/lib/hooks/use-my-feature';

interface MyFeatureContentProps {
  userId: string;
}

export function MyFeatureContent({ userId }: MyFeatureContentProps) {
  const { data } = useMyFeatureSuspense(userId);

  return (
    <div className="container mx-auto p-4">
      {/* Render data - no isLoading check needed! */}
      {data.map((item) => (
        <div key={item.id}>{item.name}</div>
      ))}
    </div>
  );
}

Key Points:

Uses useSuspenseQuery - no loading states needed
Receives userId as prop from page
Pure UI rendering

4. Update Middleware (if new route pattern)

// middleware.ts
const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/items(.*)',
  '/paid-feature(.*)',
  '/my-feature(.*)', // Add new route
]);

Important Rules

DO:

Add if (!user) return null in page components
Use Suspense to wrap content
Put data fetching in content component
Use useSuspenseQuery for automatic loading states

DO NOT:

Fetch data in page component
Add manual loading states (isLoading)
Forget the null check (causes build errors)
Use dynamic = 'force-dynamic' (middleware handles auth)

Creating the Feature Hook

See the add-feature-hook skill for creating the hook used in the content component.

add-protected-page

When & Why to Use This Skill

Use Cases