Monitor Next.js Code Quality

Enforces Next.js best practices, App Router conventions, Server/Client component patterns, and TypeScript usage with automated code reviews.

When to Use This Hook

Attach this hook when you need to:

• Automatically validate Next.js App Router conventions including page exports, layout patterns, and metadata configuration after every edit
• Detect incorrect Server/Client component boundaries where interactive features are used without the "use client" directive
• Enforce Next.js-specific best practices like using next/image, next/link, and proper data fetching patterns with real-time feedback

Consider alternatives when:

• Your project uses the Next.js Pages Router exclusively and the App Router validation rules do not apply
• You already use a comprehensive ESLint plugin like eslint-plugin-next that covers the same Next.js-specific rules

Quick Start

Configuration

Copy
name: monitor-nextjs-code-quality
type: hook
trigger: PostToolUse
category: development-tools

Example Trigger

Copy
# Claude edits app/dashboard/page.tsx
# Hook fires:
# Next.js Code Quality: Reviewing app/dashboard/page.tsx...

Example Output

Next.js Code Quality: Review of app/dashboard/page.tsx
App Router file detected: app/dashboard/page.tsx
Server Component (default)
Checks:
  - Page exports default function: PASS
  - Metadata export present: WARNING (consider adding for SEO)
  - next/image usage: PASS (optimized images used)
  - next/link usage: PASS (internal links use next/link)
  - Interactive features in Server Component: PASS (no client hooks)
  - TypeScript types: INFO (consider using React.FC for props)
Code quality check passed for app/dashboard/page.tsx

Core Concepts

Next.js Quality Rules Overview

Aspect	Details
App Router Detection	Identifies files under app/ directory for App Router rules
Page Validation	Verifies export default function exists in page components
Layout Validation	Checks that layout components accept and render children prop
Component Boundary	Detects "use client" directive and validates hook usage accordingly
Image Optimization	Flags plain <img> tags and suggests next/image for performance
Link Optimization	Flags plain <a> tags for internal links and suggests next/link

Quality Check Workflow

PostToolUse (Write/Edit/MultiEdit on .js/.jsx/.ts/.tsx)
    |
    v
[File in app/ directory?]
    |          |
   No         Yes
    |          |
    v          v
[General]  [App Router specific checks]
 checks         |
    |      +----+----+----+----+
    |      |    |    |    |    |
    |    page? layout? "use client"?
    |      |    |    |    |
    |      v    v    v    v
    |   [Validate exports, children, hooks]
    |           |
    +----------+
    |
    v
[Check next/image usage]
    |
    v
[Check next/link usage]
    |
    v
[Check TypeScript patterns]
    |
    v
[Report: errors, warnings, suggestions]

Configuration

Parameter	Type	Default	Description
matcher	string	Write|Edit|MultiEdit	Tool types that trigger the quality review
app_dir	string	app/	Path prefix for identifying App Router files
require_metadata	boolean	false	Whether missing metadata exports trigger a warning or just an info message
strict_client_boundary	boolean	true	Whether to error on interactive features in Server Components
check_deprecated_patterns	boolean	true	Whether to flag Pages Router patterns like getServerSideProps

Best Practices

1. Enable strict client boundary checking - The most common Next.js App Router mistake is using hooks like useState or useEffect in Server Components. Keep strict_client_boundary enabled to catch these errors immediately rather than discovering them at build time.

2. Add metadata exports to all page components - The monitor suggests adding metadata exports for SEO. Treat this as a required practice and set require_metadata to true for production projects. Metadata is essential for search engine visibility and social sharing.

3. Migrate from Pages Router patterns gradually - The monitor detects Pages Router data fetching methods like getServerSideProps. Use these warnings as a migration guide, converting one page at a time to App Router Server Components with direct data fetching.

4. Use next/image consistently - The monitor flags plain <img> tags because next/image provides automatic optimization, lazy loading, and responsive sizing. Convert all internal images to next/image and reserve plain <img> only for external images that cannot be optimized.

5. Review className utility suggestions - When dynamic className concatenation is detected, the monitor suggests using utilities like clsx or cn(). Adopt one utility consistently across the project to simplify conditional styling logic.

Common Issues

1. False positive on "use client" for wrapper components - Components that only pass props to client children may not need "use client" even if they appear to use interactive patterns. The monitor uses simple grep-based detection which cannot analyze component composition. Review flagged files manually.

2. Monitor triggers on non-Next.js JavaScript files - If your project has JavaScript files outside the Next.js application directory, the monitor may apply Next.js rules inappropriately. Ensure the app_dir configuration correctly identifies your Next.js source directory.

3. TypeScript suggestions conflict with project conventions - The monitor suggests using React.FC for component types, but many Next.js projects prefer explicit return type annotations. Adjust or disable the TypeScript suggestions to match your team's established conventions.