Next.js TypeScript Rules: Expert React, Shadcn UI, Tailwind & App Router Best Practices

## Code Style and Structure

Craft compact, precise TypeScript code backed by precise examples. Embrace functional and declarative approaches while skipping classes entirely. Prioritize loops and modular breakdowns to eliminate redundancy. Select clear variable names with helper verbs, such as `isVisible` or `hasData`.

Organize files logically: primary exported component first, followed by child components, utilities, constants, and type definitions.

**Example File Structure (`components/user-profile.tsx`):**
```tsx
export interface UserProfileProps { ... }

const UserProfile = ({ user }: UserProfileProps) => { ... };

const UserAvatar = ({ src }: { src: string }) => <img ... />;

const formatUserName = (name: string) => name.toUpperCase();

const USER_PROFILE_CONSTANTS = { maxLength: 50 };

export { UserAvatar, formatUserName };
export default UserProfile;
```

## Naming Conventions

Adopt kebab-case for directories (e.g., `components/login-form`). Stick to named exports for all components to enhance tree-shaking and readability.

**Practical Example:**
```tsx
// ✅ Good: components/dashboard-overview/
export const DashboardOverview = () => { ... };

// ❌ Avoid: Default exports only for tiny utils
export default function tinyUtil() { ... } // Use named instead
```

## TypeScript Best Practices

Mandate TypeScript across every file; opt for interfaces rather than type aliases for better extensibility. Ditch enums in favor of const assertion maps for runtime safety.

Build functional components with interface props.

**Example:**
```tsx
interface ButtonProps {
  variant?: 'primary' | 'secondary';
  onClick: () => void;
}

const Button = ({ variant = 'primary', onClick }: ButtonProps) => (
  <button className={variant === 'primary' ? 'bg-blue-500' : 'bg-gray-500'} onClick={onClick}>
    Click me
  </button>
);

const VARIANT_MAP = {
  primary: 'bg-blue-500',
  secondary: 'bg-gray-500',
} as const;
```

## Syntax and Formatting

Declare pure functions with the `function` keyword. Skip braces for single-line conditionals and leverage terse syntax. Favor declarative JSX patterns.

**Example:**
```tsx
function computeTotal(items: number[]) {
  return items.reduce((sum, item) => sum + item, 0);
}

const ListItem = ({ item }) => item ? <li>{item}</li> : null; // Concise conditional
```

## UI and Styling Guidelines

Leverage Shadcn UI components, Radix primitives, and Tailwind classes exclusively. Apply mobile-first responsive utilities from Tailwind.

**Example with Shadcn Button:**
```tsx
import { Button } from '@/components/ui/button';

const ResponsiveAction = () => (
  <Button className="md:text-lg sm:px-4 px-2 w-full md:w-auto">
    Submit
  </Button>
);
```

## Performance Optimization

Restrict `'use client'` to essentials; prioritize React Server Components. Encase client-side elements in Suspense boundaries. Dynamically import heavy components and lazy-load images in WebP with dimensions.

**Example:**
```tsx
import { Suspense } from 'react';
const HeavyChart = dynamic(() => import('./HeavyChart'), { ssr: false });

export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <HeavyChart />
    </Suspense>
  );
}
<img src="/image.webp" width={400} height={300} loading="lazy" alt="Optimized" />
```

## Essential Next.js Conventions

Manage URL params with `nuqs`. Target top Web Vitals (LCP, CLS, INP). Limit `'use client'` to browser APIs in minimal scopes; handle data and state server-side. Adhere to official docs for fetching, rendering, and routing.