Next.js + TypeScript + Shadcn UI Stack
Expert guidance for building modern Next.js applications using TypeScript, React Server Components, Shadcn UI, Radix UI, and Tailwind CSS with emphasis on performance optimization and clean code architecture.
Code Style and Structure
Write concise, technical TypeScript code with accurate examples. Follow these principles:
Use functional and declarative programming patterns; avoid classesPrefer iteration and modularization over code duplicationUse descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`)Structure files in this order: exported component, subcomponents, helpers, static content, typesNaming Conventions
Use lowercase with dashes for directories (e.g., `components/auth-wizard`)Favor named exports for componentsUse clear, semantic names that describe component purposeTypeScript Usage
Use TypeScript for all code; prefer interfaces over typesAvoid enums; use maps insteadUse functional components with TypeScript interfacesEnsure proper type safety throughout the applicationSyntax and Formatting
Use the `function` keyword for pure functionsAvoid unnecessary curly braces in conditionals; use concise syntax for simple statementsUse declarative JSXKeep code readable and maintainableUI and Styling
Use Shadcn UI, Radix UI, and Tailwind CSS for components and stylingImplement responsive design with Tailwind CSS using a mobile-first approachLeverage Tailwind's utility classes for consistent stylingFollow Shadcn UI component patterns for accessible, well-structured UIPerformance Optimization
Prioritize performance with these strategies:
**Minimize client-side code**: Reduce use of `'use client'`, `useEffect`, and `setState`**Favor React Server Components (RSC)**: Use server components by defaultWrap client components in `Suspense` with appropriate fallback UIUse dynamic loading for non-critical componentsOptimize images: use WebP format, include size data, implement lazy loadingClient Component Guidelines
Limit `'use client'` usage:
Favor server components and Next.js SSR featuresUse only for Web API access in small, isolated componentsAvoid for data fetching or state management (handle server-side instead)Key Conventions
Use `nuqs` for URL search parameter state managementOptimize Core Web Vitals (LCP, CLS, FID)Follow Next.js documentation for Data Fetching, Rendering, and Routing patternsCheck project-specific `INSTRUCTIONS.md` file for additional conventionsNext.js App Router Best Practices
Leverage App Router features: layouts, loading states, error boundariesUse server actions for mutations when appropriateImplement proper metadata for SEOUtilize route handlers for API endpointsFollow Next.js caching and revalidation strategiesExample Component Structure
```tsx
// Exported component
export function MyComponent({ title }: MyComponentProps) {
return (
<div className="container mx-auto px-4">
<ComponentHeader title={title} />
<ComponentContent />
</div>
);
}
// Subcomponents
function ComponentHeader({ title }: { title: string }) {
return <h1 className="text-2xl font-bold">{title}</h1>;
}
function ComponentContent() {
return <div className="mt-4">Content here</div>;
}
// Types
interface MyComponentProps {
title: string;
}
```
Constraints
Always prioritize server components over client componentsEnsure all code is properly typed with TypeScriptFollow accessibility best practices with Radix UI primitivesMaintain performance budgets for Core Web VitalsRefer to project-specific instructions when available