Estructura y organización del proyecto

Esta página proporciona una visión general de todas las convenciones de carpetas y archivos en Next.js, así como recomendaciones para organizar tu proyecto.

Convenciones de carpetas y archivos

Carpetas de nivel superior

Las carpetas de nivel superior se utilizan para organizar el código y los recursos estáticos de tu aplicación.


`app`	Enrutador de la aplicación (App Router)
`pages`	Enrutador de páginas (Pages Router)
`public`	Recursos estáticos para servir
`src`	Carpeta opcional de código fuente

Archivos de nivel superior

Los archivos de nivel superior se utilizan para configurar tu aplicación, gestionar dependencias, ejecutar middleware, integrar herramientas de monitoreo y definir variables de entorno.


Next.js
`next.config.js`	Archivo de configuración para Next.js
`package.json`	Dependencias y scripts del proyecto
`instrumentation.ts`	Archivo de OpenTelemetry e Instrumentación
`middleware.ts`	Middleware de solicitudes en Next.js
`.env`	Variables de entorno
`.env.local`	Variables de entorno locales
`.env.production`	Variables de entorno de producción
`.env.development`	Variables de entorno de desarrollo
`.eslintrc.json`	Archivo de configuración para ESLint
`.gitignore`	Archivos y carpetas ignorados por Git
`next-env.d.ts`	Archivo de declaración TypeScript para Next.js
`tsconfig.json`	Archivo de configuración para TypeScript
`jsconfig.json`	Archivo de configuración para JavaScript

Archivos de enrutamiento


`layout`	`.js` `.jsx` `.tsx`	Diseño (Layout)
`page`	`.js` `.jsx` `.tsx`	Página
`loading`	`.js` `.jsx` `.tsx`	Interfaz de carga
`not-found`	`.js` `.jsx` `.tsx`	Interfaz de no encontrado
`error`	`.js` `.jsx` `.tsx`	Interfaz de error
`global-error`	`.js` `.jsx` `.tsx`	Interfaz de error global
`route`	`.js` `.ts`	Endpoint API
`template`	`.js` `.jsx` `.tsx`	Diseño re-renderizado
`default`	`.js` `.jsx` `.tsx`	Página de respaldo para rutas paralelas

Rutas anidadas


`carpeta`	Segmento de ruta
`carpeta/carpeta`	Segmento de ruta anidado

Rutas dinámicas


`[carpeta]`	Segmento de ruta dinámica
`[...carpeta]`	Segmento de ruta catch-all
`[[...carpeta]]`	Segmento de ruta catch-all opcional

Grupos de rutas y carpetas privadas


`(carpeta)`	Agrupar rutas sin afectar el enrutamiento
`_carpeta`	Excluir carpeta y segmentos hijos del enrutamiento

Rutas paralelas e interceptadas


`@carpeta`	Ranura nombrada
`(.)carpeta`	Interceptar mismo nivel
`(..)carpeta`	Interceptar un nivel arriba
`(..)(..)carpeta`	Interceptar dos niveles arriba
`(...)carpeta`	Interceptar desde la raíz

Convenciones de archivos de metadatos

Iconos de la aplicación


`favicon`	`.ico`	Archivo favicon
`icon`	`.ico` `.jpg` `.jpeg` `.png` `.svg`	Archivo de icono de app
`icon`	`.js` `.ts` `.tsx`	Icono de app generado
`apple-icon`	`.jpg` `.jpeg`, `.png`	Archivo de icono Apple
`apple-icon`	`.js` `.ts` `.tsx`	Icono Apple generado

Imágenes Open Graph y Twitter


`opengraph-image`	`.jpg` `.jpeg` `.png` `.gif`	Archivo imagen Open Graph
`opengraph-image`	`.js` `.ts` `.tsx`	Imagen Open Graph generada
`twitter-image`	`.jpg` `.jpeg` `.png` `.gif`	Archivo imagen Twitter
`twitter-image`	`.js` `.ts` `.tsx`	Imagen Twitter generada

SEO


`sitemap`	`.xml`	Archivo sitemap
`sitemap`	`.js` `.ts`	Sitemap generado
`robots`	`.txt`	Archivo robots
`robots`	`.js` `.ts`	Archivo robots generado

Organizando tu proyecto

Next.js es no-opinionado sobre cómo organizas y colocas los archivos de tu proyecto. Pero sí proporciona varias características para ayudarte a organizarlo.

Jerarquía de componentes

Los componentes definidos en archivos especiales se renderizan en una jerarquía específica:

layout.js
template.js
error.js (límite de error de React)
loading.js (límite de suspense de React)
not-found.js (límite de error de React)
page.js o layout.js anidado

Jerarquía de Componentes para Convenciones de Archivos

Los componentes se renderizan recursivamente en rutas anidadas, lo que significa que los componentes de un segmento de ruta estarán anidados dentro de los componentes de su segmento padre.

Jerarquía de Componentes Anidados para Convenciones de Archivos

Colocación

En el directorio app, las carpetas anidadas definen la estructura de rutas. Cada carpeta representa un segmento de ruta que se mapea a un segmento correspondiente en una ruta URL.

Sin embargo, aunque la estructura de rutas se define mediante carpetas, una ruta no es accesible públicamente hasta que se agrega un archivo page.js o route.js a un segmento de ruta.

Un diagrama que muestra cómo una ruta no es accesible públicamente hasta que se agrega un archivo page.js o route.js a un segmento de ruta.

Y, incluso cuando una ruta se hace accesible públicamente, solo el contenido devuelto por page.js o route.js se envía al cliente.

Un diagrama que muestra cómo los archivos page.js y route.js hacen que las rutas sean accesibles públicamente.

Esto significa que los archivos del proyecto pueden colocarse de forma segura dentro de segmentos de ruta en el directorio app sin que accidentalmente sean accesibles como rutas.

Un diagrama que muestra que los archivos del proyecto colocados no son accesibles como rutas, incluso cuando un segmento contiene un archivo page.js o route.js.

Es bueno saberlo: Aunque puedes colocar tus archivos de proyecto en app, no tienes que hacerlo. Si lo prefieres, puedes mantenerlos fuera del directorio app.

Carpetas privadas

Las carpetas privadas se pueden crear anteponiendo un guión bajo al nombre de la carpeta: _nombreDeCarpeta.

Esto indica que la carpeta es un detalle de implementación privado y no debe ser considerado por el sistema de enrutamiento, excluyendo la carpeta y todas sus subcarpetas del enrutamiento.

Un ejemplo de estructura de carpetas usando carpetas privadas

Dado que los archivos en el directorio app pueden colocarse de forma segura por defecto, las carpetas privadas no son necesarias para la colocación. Sin embargo, pueden ser útiles para:

Separar la lógica de la interfaz de usuario de la lógica de enrutamiento.
Organizar de manera consistente los archivos internos en un proyecto y en el ecosistema de Next.js.
Clasificar y agrupar archivos en editores de código.
Evitar posibles conflictos de nombres con futuras convenciones de archivos de Next.js.

Es bueno saberlo:

Aunque no es una convención del framework, también podrías considerar marcar archivos fuera de carpetas privadas como "privados" usando el mismo patrón de guión bajo.

Puedes crear segmentos URL que comiencen con un guión bajo anteponiendo %5F (la forma codificada en URL de un guión bajo) al nombre de la carpeta: %5FnombreDeCarpeta.

Si no usas carpetas privadas, sería útil conocer las convenciones de archivos especiales de Next.js para evitar conflictos de nombres inesperados.

Grupos de rutas

Los grupos de rutas se pueden crear envolviendo una carpeta entre paréntesis: (nombreDeCarpeta)

Esto indica que la carpeta es para fines organizativos y no debe incluirse en la ruta URL.

Un ejemplo de estructura de carpetas usando grupos de rutas

Los grupos de rutas son útiles para:

Organizar rutas por sección del sitio, intención o equipo. Ej: páginas de marketing, páginas de administración, etc.
Habilitar diseños anidados en el mismo nivel de segmento de ruta:
- Crear múltiples diseños anidados en el mismo segmento, incluyendo múltiples diseños raíz
- Agregar un diseño a un subconjunto de rutas en un segmento común

Next.js admite almacenar el código de la aplicación (incluyendo app) dentro de una carpeta src opcional. Esto separa el código de la aplicación de los archivos de configuración del proyecto que principalmente residen en la raíz del proyecto.

Un ejemplo de estructura de carpetas con la carpeta `src`

Ejemplos

La siguiente sección enumera un resumen de alto nivel de estrategias comunes. La conclusión más simple es elegir una estrategia que funcione para ti y tu equipo y ser consistente en todo el proyecto.

Es bueno saberlo: En nuestros ejemplos a continuación, estamos usando las carpetas components y lib como marcadores de posición generalizados, sus nombres no tienen un significado especial en el framework y tus proyectos podrían usar otras carpetas como ui, utils, hooks, styles, etc.

Almacenar archivos de proyecto fuera de `app`

Esta estrategia almacena todo el código de la aplicación en carpetas compartidas en la raíz de tu proyecto y mantiene el directorio app puramente para fines de enrutamiento.

Un ejemplo de estructura de carpetas con archivos de proyecto fuera de app

Almacenar archivos de proyecto en carpetas de nivel superior dentro de `app`

Esta estrategia almacena todo el código de la aplicación en carpetas compartidas en la raíz del directorio app.

Un ejemplo de estructura de carpetas con archivos de proyecto dentro de app

Dividir archivos de proyecto por funcionalidad o ruta

Esta estrategia almacena el código de la aplicación compartido globalmente en la raíz del directorio app y divide el código de la aplicación más específico en los segmentos de ruta que lo utilizan.

Un ejemplo de estructura de carpetas con archivos de proyecto divididos por funcionalidad o ruta

Organizar rutas sin afectar la ruta URL

Para organizar rutas sin afectar la URL, crea un grupo para mantener juntas las rutas relacionadas. Las carpetas entre paréntesis se omitirán de la URL (ej: (marketing) o (shop)).

Organización de rutas con grupos de rutas

Aunque las rutas dentro de (marketing) y (shop) comparten la misma jerarquía URL, puedes crear un diseño diferente para cada grupo agregando un archivo layout.js dentro de sus carpetas.

Optar por diseños en segmentos específicos

Para incluir rutas específicas en un diseño, crea un nuevo grupo de rutas (ej: (shop)) y mueve las rutas que comparten el mismo diseño al grupo (ej: account y cart). Las rutas fuera del grupo no compartirán el diseño (ej: checkout).

Optar por skeletons de carga en una ruta específica

Para aplicar un skeleton de carga mediante un archivo loading.js a una ruta específica, crea un nuevo grupo de rutas (ej: /(overview)) y luego mueve tu loading.tsx dentro de ese grupo de rutas.

Ahora, el archivo loading.tsx solo se aplicará a tu página dashboard → overview en lugar de a todas tus páginas dashboard, sin afectar la estructura de la ruta URL.

Crear múltiples diseños raíz

Para crear múltiples diseños raíz, elimina el archivo layout.js de nivel superior y agrega un archivo layout.js dentro de cada grupo de rutas. Esto es útil para dividir una aplicación en secciones que tienen una interfaz o experiencia completamente diferente. Las etiquetas <html> y <body> deben agregarse a cada diseño raíz.

Grupos de rutas con múltiples diseños raíz

En el ejemplo anterior, tanto (marketing) como (shop) tienen su propio diseño raíz.