ShipKit Next.js Development Rules
Expert guidance for building production-ready Next.js applications using TypeScript, App Router, React Server Components, Shadcn UI, and modern best practices.
Instructions
You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI and Tailwind.
Project Context Awareness
1. **Check for ai.mdx file** at the start of every session
2. **If ai.mdx exists**: Read it, review completed checkboxes, and continue from where previous work left off
3. **Document your plan** in ai.mdx before starting work
4. **Update ai.mdx continuously** as you complete steps so another AI can seamlessly continue
5. **Mark completed steps** with checkboxes in ai.mdx
Code Architecture Principles
**Key Principles:**
Write concise, technical TypeScript code with accurate examplesUse 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: exported component, subcomponents, helpers, static content, types**Naming Conventions:**
Use lowercase with dashes for directories (e.g., `components/auth-wizard`)Favor named exports for componentsPrefer `hyphen-case.ext` over `CamelCase.ext` for file names**TypeScript Standards:**
Use TypeScript for all code; prefer interfaces over typesAvoid enums; use maps insteadUse functional components with TypeScript interfacesPre-emptively add types to all functions and variablesFix all TypeScript errors and warnings before completingReact Patterns
**Component Structure:**
Use arrow functions for React components: `export const Component = () => { ... }`Use functional components and hooks for state managementEnsure components are reusable and maintainableMaintain separation of concerns between client and server components**Syntax:**
Use the "function" keyword for pure functionsAvoid unnecessary curly braces in conditionalsUse declarative JSXNext.js App Router Best Practices
**Server Components First:**
Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC)Wrap client components in Suspense with fallbackUse dynamic loading for non-critical componentsDon't nest server components in client components unless passed through propsAdd `use client` to the top of the file only when using client-side code like hooks**Data Fetching:**
**CRITICAL**: Don't use server actions to fetch data; use Server Components insteadServer code belongs in `@/server/services`Server action code belongs in `@/server/actions`If an action needs server-side code, it should call servicesServer components load data using services, then manipulate data using server actions which call services**URL State Management:**
Use 'nuqs' for URL search parameter state managementUI and Styling
**Component Libraries:**
Use Shadcn UI, Radix, and Tailwind for components and stylingUse Shadcn/UI components for consistencyFollow Tailwind CSS conventions**Responsive Design:**
Implement responsive design with Tailwind CSSUse a mobile-first approachEnsure responsive design for all componentsPrioritize accessibility in UI designPerformance Optimization
**Images:**
Use WebP formatInclude size dataImplement lazy loadingOptimize all images and assets for faster load times**Code Optimization:**
Optimize Web Vitals (LCP, CLS, FID)Minimize the use of heavy libraries and dependenciesRegularly audit and improve performance metricsPre-emptively optimize code for productionDatabase Interactions
When working with databases:
1. Ensure all required fields are provided
2. Check for potential undefined values and handle them appropriately
3. Use TypeScript's type system to enforce correct data structures
4. Implement error handling for database operations
5. Validate input data to prevent runtime errors
6. Use `db.transaction` method to ensure atomicity for multiple operations
7. **Use dates instead of booleans** (e.g., `activeAt: Date` instead of `isActive: boolean`)
API Integration
Use environment variables for sensitive data like API keysHandle API errors gracefully and provide user feedbackUse async/await for asynchronous operationsDocument API interactions and expected responsesPrefer server actions for internal API requestsCode Quality Standards
**Comments:**
Pre-emptively add comments to explain "why" behind the codeDo not modify comments or functionality unrelated to the prompt unless necessaryPreserve all existing comments unless specifically asked to modify themUse comments like `// ...` to indicate unchanged sections of codeAdd callouts and examples:```typescript
/*
* Logging configuration
* @see https://nextjs.org/docs/app/api-reference/next-config-js/logging
*/
```
**Best Practices:**
Pre-emptively ask questions if unsure about requirementsUse open-source libraries when they enhance user/developer experienceWrite production-ready code using best practicesFix bugs and improve performanceComment any complex or hard-to-read codeRegularly review and test code to catch errors earlyCritical Don'ts
❌ Don't delete environment variables❌ Don't nest server components in client components unless passed through props❌ Don't forget to add `use client` when using client-side code❌ Don't use `use client` in server components❌ Don't fetch data with server actions (use Server Components instead)File Structure
```
@/server/actions # All server actions
@/server/services # All internal services
components/ # Reusable components (hyphen-case)
```
Examples
**Component Structure:**
```typescript
// ✅ Correct
export const UserProfile = ({ userId }: { userId: string }) => {
return <div>{/* component content */}</div>
}
// ❌ Avoid
export default function UserProfile() { ... }
export function UserProfile() { ... }
```
**Data Fetching Pattern:**
```typescript
// ✅ Server Component loads data
import { getUserData } from '@/server/services/user-service'
export const UserPage = async () => {
const user = await getUserData()
return <UserClient user={user} />
}
// ✅ Server Action manipulates data
'use server'
import { updateUserService } from '@/server/services/user-service'
export async function updateUserAction(data: UserData) {
return await updateUserService(data)
}
```
**Date Instead of Boolean:**
```typescript
// ✅ Use dates
interface User {
activeAt: Date | null
deletedAt: Date | null
}
// ❌ Avoid booleans
interface User {
isActive: boolean
isDeleted: boolean
}
```
Constraints
Always be aware of the latest versions of all librariesFollow Next.js documentation for Data Fetching, Rendering, and RoutingPNPM is the package manager for this stackThis skill is specifically designed for Next.js App Router projects with Shadcn/UI, Tailwind, Resend, Builder.io, Payload CMS 3, and NextAuth/AuthJS@v5