Next.js Component Generator Dispatcher

Generate complete Next.js component scaffolds with TypeScript types, CSS modules, unit tests, Storybook stories, and barrel exports following your project's existing patterns.

When to Use This Command

Run this command when you need to create a new React component with all supporting files in your Next.js project.

• You need a new component with consistent file structure matching your project's conventions
• You want auto-detection of Server vs. Client component based on interactivity requirements
• You need TypeScript interfaces, CSS modules, tests, and optional Storybook stories generated together
• You want to scaffold page-level or layout-level components for the App Router

Use it also when:

• You need to generate multiple related components in a single operation
• You want the generator to match your existing Tailwind, CSS Modules, or styled-components setup

Quick Start

Copy
# .claude/commands/nextjs-component-generator-dispatcher.md
name: nextjs-component-generator-dispatcher
description: Generate Next.js components with full scaffolding
arguments:
  name: Component name (PascalCase)

Copy
# Generate a new component with all supporting files
claude nextjs-component-generator-dispatcher "UserProfile --client"

Expected output:
Generated component: UserProfile
  components/UserProfile/
    index.ts                    (barrel export)
    UserProfile.tsx             (client component)
    UserProfile.module.css      (scoped styles)
    UserProfile.test.tsx        (unit tests)
    types.ts                    (TypeScript interfaces)

  Component type: Client (interactive)
  Styling: CSS Modules (detected from project)

Core Concepts

Concept	Description
Server Component	Default in Next.js 13+; renders on the server, no client JS
Client Component	Uses "use client" directive; supports state, effects, events
Barrel Export	index.ts re-exports for clean import paths
CSS Module	Scoped stylesheet preventing class name collisions
Component Type	Auto-detected or specified: --client, --server, --page, --layout

Generated File Structure:
  components/UserProfile/
       │
       ├── index.ts ───────────> export { UserProfile } from './UserProfile'
       ├── UserProfile.tsx ────> Main component implementation
       ├── UserProfile.module.css > Scoped styles
       ├── UserProfile.test.tsx -> Jest/Vitest test suite
       ├── types.ts ───────────> Props interface and related types
       └── UserProfile.stories.tsx > Storybook story (if detected)

Configuration

Parameter	Default	Description
name	required	Component name in PascalCase
type	auto-detect	--client, --server, --page, --layout
styling	auto-detect	css-modules, tailwind, styled-components
tests	true	Generate test file alongside component
stories	auto-detect	Generate Storybook story if Storybook is configured

Best Practices

1. Use PascalCase for component names -- React conventions require PascalCase for component names. The generator enforces this and converts if needed.

2. Let the generator detect Server vs. Client -- Unless you know the component needs client-side interactivity, let the generator default to Server Component for better performance.

3. Review the generated types.ts -- The auto-generated TypeScript interfaces are starting points. Refine prop types to match your actual data model.

4. Keep components colocated -- The generator creates a directory per component. This colocation pattern keeps related files together and simplifies imports.

5. Use barrel exports consistently -- The index.ts file enables clean imports like import { UserProfile } from '@/components/UserProfile' without referencing the internal file.

Common Issues

1. Component directory already exists -- The generator will not overwrite existing components. Delete or rename the existing directory first, or use a different component name.

2. Styling detection fails -- If the generator cannot detect your styling approach, it defaults to CSS Modules. Override with --styling tailwind if needed.

3. Tests reference wrong testing library -- The generator checks for Jest or Vitest configuration. If neither is found, it generates Jest tests by default. Install your preferred framework first.