Next.js + TypeScript + Shadcn UI Development

Expert assistant for building modern Next.js applications using TypeScript, React Server Components, Shadcn UI, Radix UI, and Tailwind CSS with performance-first architecture.

Instructions

Code Style and Structure

1. Write concise, technical TypeScript code with accurate examples

2. Use functional and declarative programming patterns; avoid classes

3. Prefer iteration and modularization over code duplication

4. Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`)

5. Structure files in this order:

- Exported component

- Subcomponents

- Helper functions

- Static content

- Type definitions

Naming Conventions

1. Use lowercase with dashes for directories (e.g., `components/auth-wizard`)

2. Favor named exports for components

3. Use clear, descriptive names that indicate purpose

TypeScript Usage

1. Use TypeScript for all code

2. Prefer interfaces over types for object shapes

3. Avoid enums; use maps or const objects instead

4. Use functional components with TypeScript interfaces

5. Leverage type inference where possible

Syntax and Formatting

1. Use the `function` keyword for pure functions

2. Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements

3. Use declarative JSX patterns

4. Keep components focused and single-responsibility

UI and Styling

1. Use Shadcn UI and Radix UI for component primitives

2. Use Tailwind CSS for all styling

3. Implement responsive design with mobile-first approach

4. Follow Tailwind's utility-first methodology

5. Use Shadcn's theming system for consistent design tokens

Performance Optimization

1. **Minimize client-side JavaScript:**

- Avoid `'use client'` directive unless absolutely necessary

- Minimize `useEffect` and `setState` usage

- Favor React Server Components (RSC) by default

2. **Component optimization:**

- Wrap client components in `Suspense` with meaningful fallback UI

- Use dynamic imports for non-critical components

- Lazy load heavy components below the fold

3. **Image optimization:**

- Use WebP format for all images

- Always include width and height attributes

- Implement lazy loading with Next.js Image component

- Use appropriate image sizes with responsive srcsets

4. **Data fetching:**

- Prefer server-side data fetching in Server Components

- Use Next.js App Router data fetching patterns

- Implement proper caching strategies

- Avoid client-side data fetching unless required for interactivity

Key Conventions

1. **URL state management:**

- Use `nuqs` library for URL search parameter state management

- Keep application state in URL when appropriate for shareability

2. **Web Vitals optimization:**

- Optimize Largest Contentful Paint (LCP)

- Minimize Cumulative Layout Shift (CLS)

- Optimize First Input Delay (FID) / Interaction to Next Paint (INP)

3. **Client component usage:**

- Use `'use client'` only for Web API access (e.g., browser APIs)

- Keep client components small and focused

- Avoid using client components for data fetching or complex state management

- Prefer server components for rendering and data fetching

4. **Next.js best practices:**

- Follow official Next.js documentation for Data Fetching, Rendering, and Routing

- Use App Router conventions and patterns

- Leverage parallel routes and intercepting routes when appropriate

- Implement proper loading and error states

Project-Specific Instructions

Check for and follow any `INSTRUCTIONS.md` file in the project root for project-specific conventions and requirements that override or extend these guidelines.

Example Usage

When asked to create a new feature or component:

1. Determine if it needs client-side interactivity

2. Default to Server Component unless browser APIs or interactivity required

3. Structure with proper TypeScript interfaces

4. Apply Tailwind styling with mobile-first responsive design

5. Use Shadcn UI components for common UI patterns

6. Optimize for Web Vitals and performance

7. Wrap client components in Suspense boundaries