# How to structure a Next.js project for Cursor

- Tool: Cursor
- Difficulty: Beginner
- Time required: 10-15 min
- Compatibility: Cursor Free+, Next.js 14+ with App Router
- Last updated: March 2026

## TL;DR

Cursor can scaffold a complete Next.js project structure when given clear conventions about the App Router, file-based routing, and component organization. By adding Next.js-specific rules to .cursorrules and prompting Cursor to follow the official App Router patterns, you get a well-organized project that Cursor can navigate and generate code for efficiently.

## Structuring a Next.js project for optimal Cursor usage

Next.js App Router uses file-based routing with special files (page.tsx, layout.tsx, loading.tsx). Cursor needs to understand these conventions to generate routes, layouts, and server components correctly. This tutorial establishes a project structure that maximizes Cursor's ability to navigate and generate Next.js code.

## Before you start

- Cursor installed with a Next.js project (App Router)
- Next.js 14+ with TypeScript
- Basic understanding of the App Router file conventions
- Familiarity with Cursor Chat (Cmd+L) and Composer (Cmd+I)

## Step-by-step guide

### 1. Add Next.js conventions to .cursor/rules

Create rules that define your Next.js project structure and file conventions. This ensures Cursor generates code in the right locations with the correct patterns.

```
---
description: Next.js App Router conventions
globs: "app/**/*.tsx,app/**/*.ts"
alwaysApply: true
---

## Next.js App Router Rules
- Use the app/ directory for all routes (NOT pages/)
- page.tsx = route page component (default export)
- layout.tsx = shared layout (wraps child routes)
- loading.tsx = loading UI (Suspense boundary)
- error.tsx = error boundary (must be 'use client')
- not-found.tsx = 404 page
- route.ts = API route handler (GET, POST, etc.)

## Component Rules
- Server Components by default (NO 'use client' unless needed)
- Add 'use client' ONLY for: useState, useEffect, event handlers, browser APIs
- Data fetching in Server Components using async/await (not useEffect)
- Place shared components in src/components/
- Place page-specific components in app/[route]/_components/

## File Organization
- app/ — routes and layouts
- src/components/ — shared UI components
- src/hooks/ — custom React hooks
- src/lib/ — utility functions and API clients
- src/types/ — TypeScript type definitions
- public/ — static assets
```

**Expected result:** Cursor follows Next.js App Router conventions for file placement and component types.

### 2. Scaffold the project structure with Composer

Use Composer Agent mode to create the initial folder structure with placeholder files. This gives Cursor a map of your project to reference in future prompts.

```
// Composer prompt (Cmd+I):
// Create the following Next.js App Router project structure:
//
// app/
//   layout.tsx (root layout with html, body, Providers)
//   page.tsx (home page)
//   loading.tsx (global loading spinner)
//   not-found.tsx (404 page)
//   (auth)/
//     login/page.tsx
//     register/page.tsx
//     layout.tsx (auth layout, no navbar)
//   (dashboard)/
//     dashboard/page.tsx
//     settings/page.tsx
//     layout.tsx (dashboard layout with sidebar)
//   api/
//     users/route.ts
//     auth/route.ts
//
// src/
//   components/ui/ (Button, Input, Modal)
//   components/layout/ (Navbar, Sidebar, Footer)
//   hooks/ (useAuth, useMediaQuery)
//   lib/ (fetcher, auth, utils)
//   types/ (user, api)
//
// Generate minimal placeholder content for each file.
```

**Expected result:** A complete Next.js project structure with placeholder files for Cursor to reference.

### 3. Generate a route with proper patterns

Test the setup by asking Cursor to generate a new route. It should create the correct files in the right locations following App Router conventions.

```
// Cursor Chat prompt (Cmd+L):
// @.cursor/rules/nextjs.mdc Create a new /products route with:
// - Server Component page that fetches products from /api/products
// - Loading state with loading.tsx
// - Error boundary with error.tsx
// - Product card component in app/products/_components/
// Use Server Component data fetching (async page, not useEffect).

// Expected file structure:
// app/products/
//   page.tsx (async Server Component)
//   loading.tsx
//   error.tsx ('use client')
//   _components/ProductCard.tsx
```

> Pro tip: Use the _components/ convention (underscore prefix) for route-specific components. The underscore prevents Next.js from treating the folder as a route segment.

**Expected result:** A complete route with Server Component page, loading state, error boundary, and local components.

### 4. Organize route groups for different layouts

Use route groups (parenthesized folders) to share layouts between routes without affecting the URL structure. Ask Cursor to set these up correctly.

```
// Cursor Chat prompt (Cmd+L):
// @app/layout.tsx Create route groups:
// (marketing) — public pages with marketing navbar
//   /pricing, /about, /blog
// (app) — authenticated pages with app sidebar
//   /dashboard, /settings, /profile
// (auth) — auth pages with minimal layout
//   /login, /register
// Each group should have its own layout.tsx.
// The root layout has only Providers and html/body.
```

**Expected result:** Three route groups with distinct layouts sharing the same root layout.

### 5. Configure .cursorignore for Next.js

Exclude Next.js build artifacts and cache from Cursor's indexing to improve performance and avoid stale suggestions.

```
# .cursorignore
.next/
node_modules/
out/
.vercel/
coverage/
*.tsbuildinfo
```

**Expected result:** Cursor indexing skips build artifacts, improving performance and suggestion quality.

## Complete code example

File: `.cursor/rules/nextjs.mdc`

```markdown
---
description: Next.js App Router project conventions
globs: "app/**/*.{ts,tsx},src/**/*.{ts,tsx}"
alwaysApply: true
---

## Route Files (app/ directory)
- `page.tsx` — page component (default export, async for server data)
- `layout.tsx` — shared layout wrapping child routes
- `loading.tsx` — loading UI (automatic Suspense boundary)
- `error.tsx` — error boundary (MUST have 'use client')
- `not-found.tsx` — 404 not found page
- `route.ts` — API route handler (named exports: GET, POST, PUT, DELETE)
- `_components/` — page-specific components (underscore = not a route)

## Component Types
- Default: Server Component (no 'use client')
- Add 'use client' ONLY when component uses:
  - useState, useEffect, useRef, or other hooks
  - Event handlers (onClick, onChange, etc.)
  - Browser APIs (window, document, localStorage)
  - Third-party client libraries

## Data Fetching
- Server Components: use async/await directly in the component
- Client Components: use SWR hooks from src/hooks/
- API Routes: export async functions named GET, POST, etc.
- NEVER use getServerSideProps or getStaticProps (Pages Router)

## File Organization
```
app/                   # Routes (file-based routing)
  (marketing)/         # Route group: public pages
  (app)/               # Route group: authenticated pages
  (auth)/              # Route group: auth pages
  api/                 # API routes
src/
  components/
    ui/                # Reusable UI (Button, Input, Modal)
    layout/            # Layout parts (Navbar, Sidebar)
  hooks/               # Custom React hooks
  lib/                 # Utilities, API clients, auth
  types/               # TypeScript definitions
public/                # Static assets
```
```

## Common mistakes

- **Cursor generating pages/ directory files instead of app/** — Cursor's training data includes both Pages Router and App Router patterns. Without rules, it may mix them. Fix: Add 'Use the app/ directory for all routes, NOT pages/' to .cursorrules. Explicitly mention App Router in prompts.
- **Adding 'use client' to every component** — Cursor adds 'use client' as a safety measure, but this disables Server Component benefits like direct data fetching and smaller bundles. Fix: Add 'Server Components by default, add use client ONLY for hooks and event handlers' to your rules.
- **Using useEffect for data fetching in Server Components** — Cursor generates useEffect patterns from older React code. In App Router, Server Components should use async/await directly. Fix: Add 'Data fetching in Server Components using async/await, not useEffect' to your Next.js rules.

## Best practices

- Use App Router conventions (app/) not Pages Router (pages/)
- Default to Server Components and only add 'use client' when necessary
- Use route groups (parentheses) for layout organization without URL impact
- Place page-specific components in _components/ subdirectories
- Fetch data directly in async Server Components, not with useEffect
- Configure .cursorignore to exclude .next/ and node_modules/
- Reference @.cursor/rules/nextjs.mdc when asking Cursor to generate routes

## Frequently asked questions

### Should I use src/ or put everything in app/?

Use src/ for shared code (components, hooks, lib, types) and app/ for routes only. This keeps routes clean and makes shared code easy to reference with @src/.

### Can Cursor handle Next.js Server Actions?

Yes. Ask Cursor to generate Server Actions with 'use server' directive. Reference your form component and specify the action should be in the same file or a separate actions.ts file.

### How do I handle route params in Cursor prompts?

Specify the dynamic route: 'Create app/products/[id]/page.tsx that receives params.id as a prop.' Cursor understands Next.js dynamic route conventions.

### Does Cursor know about Next.js middleware?

Yes. Ask Cursor to generate middleware.ts at the project root for auth redirects, rate limiting, or request rewriting. Specify the matcher pattern in your prompt.

### How do I handle Cursor generating Pages Router code?

Add a strict rule: 'This project uses App Router. NEVER use getServerSideProps, getStaticProps, or the pages/ directory.' Reference this rule in every prompt about routing.

---

Source: https://www.rapidevelopers.com/cursor-tutorial/how-to-direct-cursor-ai-to-structure-folder-hierarchies-for-next-js-projects
© RapidDev — https://www.rapidevelopers.com/cursor-tutorial/how-to-direct-cursor-ai-to-structure-folder-hierarchies-for-next-js-projects