Estructura del Proyecto

Después de crear tu proyecto con create-next-app, encontrarás una estructura de carpetas específica que NextJS utiliza para organizar tu aplicación. Entender esta estructura es fundamental para trabajar eficientemente.

Estructura básica

Cuando creas un proyecto nuevo, obtienes esta estructura:

mi-proyecto/
├── app/                    # App Router - tus rutas y páginas
│   ├── layout.tsx         # Layout raíz de la aplicación
│   ├── page.tsx           # Página principal (/)
│   └── globals.css        # Estilos globales
├── public/                # Archivos estáticos
│   ├── next.svg
│   └── vercel.svg
├── node_modules/          # Dependencias (no tocar)
├── .next/                 # Build output (generado automáticamente)
├── next.config.ts         # Configuración de NextJS
├── package.json           # Dependencias del proyecto
├── tsconfig.json          # Configuración de TypeScript
└── tailwind.config.ts     # Configuración de Tailwind (si lo instalaste)

La carpeta app/

La carpeta app/ es el corazón de tu aplicación NextJS 15. Usa el App Router, el nuevo sistema de routing introducido en NextJS 13 y mejorado en NextJS 15.

Archivos especiales

NextJS reconoce ciertos nombres de archivo como especiales:

Ejemplo de estructura con rutas

app/
├── layout.tsx              # Layout raíz
├── page.tsx                # Ruta: /
├── about/
│   └── page.tsx           # Ruta: /about
├── blog/
│   ├── page.tsx           # Ruta: /blog
│   ├── [slug]/
│   │   └── page.tsx       # Ruta: /blog/mi-post
│   └── layout.tsx         # Layout para /blog/*
└── dashboard/
    ├── layout.tsx         # Layout para /dashboard/*
    ├── page.tsx           # Ruta: /dashboard
    ├── settings/
    │   └── page.tsx       # Ruta: /dashboard/settings
    └── analytics/
        └── page.tsx       # Ruta: /dashboard/analytics

La carpeta public/

Todo lo que pongas en public/ es accesible directamente desde la URL raíz.

public/
├── logo.png               # Accesible en /logo.png
├── favicon.ico            # Favicon del sitio
├── images/
│   └── hero.jpg          # Accesible en /images/hero.jpg
└── fonts/
    └── custom.woff2      # Accesible en /fonts/custom.woff2

Uso en código

// En cualquier componente
<img src="/logo.png" alt="Logo" />
<img src="/images/hero.jpg" alt="Hero" />

Archivos de configuración

next.config.ts

Archivo de configuración principal de NextJS:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Configuraciones aquí
  images: {
    domains: ['ejemplo.com'], // Dominios permitidos para imágenes
  },
  // más opciones...
};

export default nextConfig;

package.json

Define tus dependencias y scripts:

{
  "scripts": {
    "dev": "next dev",          // Desarrollo
    "build": "next build",      // Build para producción
    "start": "next start",      // Servidor de producción
    "lint": "eslint"           // Linter
  }
}

tsconfig.json

Configuración de TypeScript. NextJS lo configura automáticamente, pero puedes ajustarlo:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]  // Permite imports con @/
    }
  }
}

Carpetas opcionales

Puedes crear estas carpetas en la raíz para organizar tu código:

mi-proyecto/
├── app/                   # Rutas (requerido)
├── components/            # Componentes reutilizables
├── lib/                   # Utilidades y helpers
├── hooks/                 # Custom hooks
├── types/                 # Types de TypeScript
├── styles/                # Estilos adicionales
└── public/                # Estáticos (requerido)

Archivos que puedes ignorar

Estos archivos son generados automáticamente:

• .next/ - Build output (Git ignore)
• node_modules/ - Dependencias (Git ignore)
• .next.lock - Lock file de Next
• out/ - Export estático (si usas next export)

Imports con alias

NextJS configura automáticamente el alias @/ que apunta a la raíz del proyecto:

// En lugar de esto:
import Button from '../../../components/Button'

// Usa esto:
import Button from '@/components/Button'

Funciona desde cualquier nivel de profundidad en tu proyecto.

Próximos pasos

Ahora que entiendes la estructura, aprende cómo:

1. Crear rutas - Sistema de routing de NextJS
2. Usar layouts - Compartir UI entre páginas
3. Server Components - El modelo de componentes de NextJS