Conocer la anatomía de un proyecto antes de escribir la primera línea de código marca la diferencia entre avanzar con seguridad y perder horas resolviendo problemas evitables. Aquí se desglosa cómo está organizado un proyecto de Next.js construido con TypeScript, qué dependencias trae listas y cómo cada carpeta cumple un rol específico para conectarse con Contentful.
¿Qué revela el package.json sobre la aplicación?
El punto de partida para inspeccionar cualquier aplicación de JavaScript o Node.js es el archivo package.json [01:15]. Este archivo concentra información esencial:
- Los scripts principales son
dev, build y start, cada uno utilizando Next.js en su variación por environment.
- Prettier ya está instalado para mantener un formato de código consistente.
- Material UI viene configurado junto con React y React DOM.
- Apollo está incluido para trabajar con GraphQL.
- Dependencias de Contentful para manejar rich text.
- Herramientas de Code Generation y Tailwind listas para usar.
Este proyecto combina Material UI y Tailwind como sistemas de estilos, lo cual ofrece flexibilidad tanto para componentes prediseñados como para utilidades CSS [02:20].
¿Cómo se configura TypeScript con alias de rutas?
El archivo TSConfig confirma que todo el proyecto está escrito en TypeScript [02:40]. Dentro de sus opciones, destacan los alias de rutas (paths), que simplifican las importaciones:
UI: apunta a las primitivas de interfaz.API: da acceso directo a la capa de datos.Components: agrupa los componentes con lógica de negocio.
Estos alias evitan rutas relativas largas y hacen el código más legible.
¿Qué contiene la carpeta API y por qué importa resources.d.ts?
La carpeta API contiene subcarpetas y archivos clave: una carpeta generada, un index, queries de GraphQL, resources y selectores [03:20]. El archivo más relevante es resources.d.ts, un archivo de tipos globales para TypeScript (los archivos .d.ts cumplen exactamente esa función).
Dentro de resources.d.ts se definen los tipos que replican la estructura de Contentful [03:40]:
- Imagen: con los mismos fields configurados en el CMS.
- Categoría y Autor: como entidades independientes.
- Rich text de Contentful: representado como un objeto JSON complejo.
- Planta: la entidad principal, con relaciones hacia categoría y autor.
Si trabajas con tu propio contenido, estos tipos deben coincidir casi uno a uno con tus modelos en Contentful para que TypeScript realmente te ayude a escribir código correcto.
¿Cómo se organizan UI y componentes?
La carpeta UI agrupa todas las primitivas de interfaz, construidas con Tailwind y Material UI [04:30]. Son elementos visuales sin lógica de negocio.
Una capa por encima está Components, donde se combinan elementos de UI con business logic [04:45]. Un ejemplo claro es PlantCollection, que importa componentes de UI y utiliza funcionalidades de Next.js para crear un componente con más responsabilidad.
Todos estos componentes son lo que se conoce como componentes tontos (dumb components): no saben de dónde vienen los datos [05:10]. La tarea será alimentarlos con información proveniente de Contentful.
¿Qué rol cumplen las páginas y archivos especiales de Next.js?
La carpeta Pages es fundamental en cualquier proyecto de Next.js [05:30]. Al inicio contiene:
- Una página
UI de prueba para verificar los elementos visuales.
- La página
index, que será la principal.
- El archivo
_app, que provee la estructura global de la interfaz.
- El archivo
_document, configurado para hacer server side rendering de Material UI y Tailwind, convirtiendo los estilos en CSS desde el servidor sin dejar esa carga al navegador [05:55].
El archivo de configuración next.config.js habilita webpack 5 y un bundle analyzer para inspeccionar el peso del proyecto [06:20].
Al ejecutar yarn dev, el proyecto corre en localhost:3000 y muestra una pantalla de bienvenida con enlaces a la documentación de Next.js, el curso básico de Platzi y la documentación para desarrolladores de Contentful [06:50].
Si algo no funciona como se describe, deja tu pregunta en los comentarios para recibir ayuda y poder continuar sin bloqueos.
