Organización de proyectos y colocación de archivos

Además de las convenciones de carpetas y archivos para enrutamiento, Next.js es flexible respecto a cómo organiza y coloca los archivos de su proyecto.

Esta página comparte el comportamiento predeterminado y las características que puede utilizar para organizar su proyecto.

Colocación segura por defecto
Características de organización de proyectos
Estrategias de organización de proyectos

Colocación segura por defecto

En el directorio app, la jerarquía de carpetas anidadas define 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 es 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 manera segura dentro de segmentos de ruta en el directorio app sin que accidentalmente sean accesibles como rutas.

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

Nota importante:

Esto es diferente del directorio pages, donde cualquier archivo en pages se considera una ruta.

Aunque puede colocar sus archivos de proyecto en app, no tiene que hacerlo. Si lo prefiere, puede mantenerlos fuera del directorio app.

Características de organización de proyectos

Next.js proporciona varias características para ayudarle a organizar su proyecto.

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.

Ejemplo de estructura de carpetas usando carpetas privadas

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

Separar la lógica de UI de la lógica de enrutamiento.
Organizar consistentemente 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.

Nota importante

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

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

Si no usa 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 propósitos organizativos y no debe incluirse en la ruta URL.

Ejemplo de estructura de carpetas usando grupos de rutas

Los grupos de rutas son útiles para:

Organizar rutas en grupos p.ej. por sección del sitio, intención o equipo.
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 un directorio 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.

Ejemplo de estructura de carpetas con el directorio `src`

Alias de módulos

Next.js admite Alias de módulos que facilitan la lectura y mantenimiento de importaciones entre archivos de proyecto profundamente anidados.

app/dashboard/settings/analytics/page.js

// antes
import { Button } from '../../../components/button'

// después
import { Button } from '@/components/button'

Estrategias de organización de proyectos

No hay una forma "correcta" o "incorrecta" cuando se trata de organizar sus propios archivos y carpetas en un proyecto de Next.js.

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

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