Una carpeta vacía no necesita una arquitectura sofisticada. Necesita que la próxima persona —incluido tu yo de dentro de dos semanas— pueda responder tres preguntas sin adivinar: dónde empieza la página, dónde vive cada tipo de archivo y desde qué lugar debe calcularse una ruta. La estructura correcta de un proyecto web no es la que parece más profesional en una captura; es la que reduce las dudas que el proyecto realmente produce.
La documentación de MDN sobre archivos y carpetas de un sitio web propone una organización inicial con un archivo de entrada y carpetas separadas para imágenes, estilos y scripts. También explica por qué los nombres, las extensiones y los caminos relativos importan cuando el proyecto deja de ser un solo archivo. Esa recomendación es un punto de partida, no una orden para copiar una arquitectura de producción en todos los ejercicios.
El criterio que guía este artículo es sencillo: cada decisión de organización debe pagar su propio coste. Una carpeta nueva debe hacer más evidente algo que antes era ambiguo. Un README debe responder una pregunta que otra persona tendría que resolver por ensayo y error. Una separación entre código y configuración debe evitar una mezcla que ya está causando problemas. Si no puedes explicar qué confusión elimina una decisión, probablemente todavía no necesitas tomarla.
El proyecto pequeño también tiene un flujo
Antes de crear carpetas, describe cómo se usa el proyecto. Incluso una página estática suele tener un flujo mínimo:
| Momento | Pregunta | Archivo o ubicación que suele responderla |
|---|---|---|
| Abrir el proyecto | ¿Cuál es la entrada que debo cargar primero? | index.html o un README breve. |
| Ver la presentación | ¿Dónde están las reglas visuales? | styles/ o css/. |
| Entender la interacción | ¿Qué archivo escucha los clics y modifica estados? | scripts/ o js/. |
| Revisar recursos | ¿Dónde están imágenes, iconos y fuentes? | images/, assets/ o una ubicación descrita. |
| Ejecutar el proyecto | ¿Qué comando o servidor local hace falta? | README y, si existe, package.json. |
Este mapa evita una confusión habitual: organizar por nombres de tecnologías sin pensar en el recorrido de quien abre el proyecto. Si todos los archivos están en una carpeta y son cuatro, quizá el flujo sea evidente. Cuando pasas a veinte archivos, la organización deja de ser un asunto estético: se convierte en una interfaz para trabajar con el código.
Primer estado: una entrada clara y pocas carpetas
Para una página inicial sencilla, empieza con una estructura que puedas explicar en una frase:
mi-sitio/
├── index.html
├── styles/
│ └── main.css
├── scripts/
│ └── main.js
└── images/
└── logo.svg
La decisión importante no es si llamas styles a la carpeta o css. Es que el nombre sea consistente y que una persona pueda encontrar la regla visual sin revisar todo el proyecto. Los nombres en minúscula y sin espacios reducen problemas con sistemas sensibles a mayúsculas, terminales y URLs, una consideración que MDN documenta junto con los caminos de archivos.
En ese estado, index.html puede referenciar la hoja de estilos así:
<link rel="stylesheet" href="styles/main.css" />
<script src="scripts/main.js" defer></script>
La ruta se calcula desde la ubicación de index.html. No significa “desde la carpeta donde guardaste el proyecto en tu computadora”; significa “desde el archivo que contiene esta referencia”. Esa diferencia explica una gran cantidad de errores cuando mueves una página a una subcarpeta.
¿Necesito una carpeta src/ desde el primer día?
No necesariamente. src/ suele ser útil cuando existe un proceso que toma código fuente y produce archivos para publicar, como una compilación, una transpilación o un empaquetado. Si tu proyecto consiste en HTML, CSS y JavaScript que el navegador carga directamente, añadir src/, dist/, public/ y varias configuraciones puede crear más preguntas de las que responde.
La estructura debe crecer cuando el flujo lo necesita. Si una herramienta exige una carpeta concreta, documenta qué entra allí y qué resultado sale. Si no existe esa transformación, una jerarquía más profunda no hace que el código sea más profesional automáticamente.
Segundo estado: las rutas cuentan desde dónde estás mirando
Una ruta relativa es una instrucción de navegación. Si about.html está en la raíz y la imagen está en images/profile.png, la ruta es images/profile.png. Si mueves about.html a pages/about.html, la misma imagen se referencia con ../images/profile.png porque ahora debes subir un nivel antes de entrar en images.
| Archivo que contiene la referencia | Destino | Ruta relativa |
|---|---|---|
index.html | images/logo.svg | images/logo.svg |
pages/about.html | images/logo.svg | ../images/logo.svg |
pages/team/profile.html | images/logo.svg | ../../images/logo.svg |
No conviene “arreglar” la ruta agregando barras hasta que la imagen aparezca. Primero dibuja la relación entre la carpeta del archivo y la del destino. Los navegadores usan la ubicación del documento para resolver la referencia. Una ruta absoluta puede parecer más rápida, pero también puede atar un enlace a un dominio o raíz que no existe cuando trabajas localmente.
La guía de Google sobre estructura de URLs también recuerda que las direcciones deben ser descriptivas, simples y consistentes. En un proyecto pequeño, un nombre de archivo confuso no solo dificulta abrirlo: puede terminar formando parte de una URL difícil de compartir o de mantener.
¿Por qué una ruta relativa deja de funcionar después de mover un archivo?
Porque la ruta no describe el destino de manera universal; describe cómo llegar a él desde el archivo actual. Al mover el archivo, cambias el punto de partida. Revisa cada referencia que contenga el archivo movido, carga la página desde un servidor local si es necesario y usa las herramientas del navegador para identificar el recurso que devuelve un 404.
Tercer estado: separar por responsabilidad, no por ansiedad
Separar HTML, CSS y JavaScript tiene una razón técnica: cada capa expresa una responsabilidad diferente. HTML describe estructura y significado, CSS presenta esa estructura y JavaScript coordina comportamiento. La guía de diferencias entre HTML, CSS y JavaScript explica esa relación con más detalle. En la estructura de carpetas, la separación facilita encontrar la capa que debe cambiarse.
Pero “una carpeta por cada concepto que conozco” no es una regla. Un proyecto con un solo script no necesita scripts/components/forms/validation/ si nadie sabe dónde buscar. Puedes mantener main.js hasta que tenga más de una responsabilidad difícil de distinguir; entonces extrae un módulo con un nombre que describa la función que separaste.
Un buen indicador es el tipo de pregunta que aparece durante el trabajo:
- Si preguntas “¿qué archivo cambia el aspecto de los botones?”, la separación por estilos está ayudando.
- Si preguntas “¿cuál de estas cuatro carpetas contiene el CSS que realmente se carga?”, la separación quizá esté ocultando el flujo.
- Si preguntas “¿dónde está la configuración que cambia entre mi computadora y producción?”, necesitas separar configuración de código o documentar el comando que la proporciona.
La estructura debe hacer que las respuestas sean más cortas. Si una división crea una nueva explicación que repetir a cada colaborador, todavía no ha pagado su coste.
Cuarto estado: cuando entra un gestor de paquetes
Un proyecto puede pasar de abrirse con doble clic a necesitar comandos para instalar dependencias, iniciar un servidor o construir archivos. En ese momento aparece otro centro de gravedad: package.json. La documentación de npm sobre package.json define campos como scripts, dependencies, devDependencies, engines, repository y private. Cada campo comunica una parte distinta del flujo del proyecto.
No copies un package.json enorme para una página que no utiliza npm. Si sí lo necesitas, empieza por un script que una persona pueda leer:
{
"private": true,
"scripts": {
"start": "vite",
"check": "eslint ."
}
}
La palabra private puede evitar una publicación accidental en npm cuando el proyecto no debe convertirse en un paquete público. El nombre de cada script también importa: start y check solo son útiles si el README explica qué hacen y qué resultado se espera. Automatizar un comando sin explicar su propósito no mejora la entrada; solo esconde el recorrido detrás de una palabra corta.
La guía de automatización de tareas repetitivas puede servir como siguiente paso cuando el proyecto ya tiene una repetición verificable. Primero entiende la estructura y después decide qué comando merece convertirse en hábito.
Quinto estado: un README convierte la estructura en una invitación
Un árbol de carpetas no explica por sí solo cómo empezar. Un README breve puede responder lo que el nombre de una carpeta no puede:
# Mi sitio de práctica
## Para verlo
Abre `index.html` con un servidor local.
## Estructura
- `styles/`: reglas visuales.
- `scripts/`: comportamiento de la interfaz.
- `images/`: recursos usados por las páginas.
## Decisiones
Las rutas internas son relativas al archivo que las contiene.
No necesitas documentar cada línea. Documenta la primera acción, el comando necesario, la decisión no obvia y el límite conocido. Si el proyecto requiere una versión de Node, una variable de entorno o una base de datos, esa información debe aparecer antes de que otra persona ejecute un comando que fallará sin explicación.
El README también puede registrar cuándo la estructura deliberadamente no incluye una carpeta. “Este proyecto no tiene src/ porque el navegador carga los archivos directamente” evita que alguien agregue una capa solo por pensar que falta algo.
Una revisión de estructura antes de compartir el proyecto
Antes de subir el proyecto a un repositorio o enviarlo a otra persona, recorre este diagnóstico:
- Entrada: ¿está claro qué archivo o comando inicia el recorrido?
- Rutas: ¿las referencias se resuelven desde la ubicación real de cada archivo?
- Nombres: ¿las carpetas y archivos evitan espacios, mezclas de mayúsculas y abreviaturas innecesarias?
- Responsabilidades: ¿puedes explicar qué pertenece a HTML, CSS, JavaScript y configuración?
- Dependencias: ¿el proyecto declara qué debe instalarse y qué solo se usa durante desarrollo?
- Entrada para otra persona: ¿el README permite empezar sin una conversación privada contigo?
Si una respuesta es “no”, arregla primero la ambigüedad que bloquea el trabajo. No conviertas el diagnóstico en una oportunidad para crear seis carpetas nuevas. Una estructura clara es una herramienta de orientación, no una demostración de que conoces nombres de arquitecturas.
La estructura correcta es la que deja ver el próximo cambio
Cuando un proyecto crece, su estructura debería anticipar el siguiente cambio razonable. Si vas a añadir otra página, quizá necesites una carpeta de páginas. Si vas a compartir componentes, quizá necesites módulos. Si vas a compilar, quizá necesites separar fuente y salida. Si solo vas a añadir otra imagen, no necesitas rediseñar el proyecto.
Para practicar el flujo completo, puedes repasar las etiquetas HTML esenciales, los comandos básicos de Git y las decisiones sobre funciones incorporadas de Python cuando un script empieza a automatizar el proyecto. La conexión entre esos temas no es una receta universal: es aprender a colocar cada decisión donde el proyecto pueda explicarla.
La regla final es menos espectacular que una arquitectura de moda y más útil: no organices para parecer preparado para cualquier futuro; organiza para que el presente sea legible y el próximo cambio no requiera adivinar.
¿Cuándo debo crear subcarpetas adicionales?
Cuando una carpeta ya mezcla responsabilidades o cuando encontrar un archivo exige revisar muchos elementos sin relación. Crea una subcarpeta si puedes explicar qué confusión elimina y cómo seguirá siendo fácil encontrar la entrada principal.
¿Una estructura simple es mala práctica?
No. Es mala práctica dejar que la estructura se vuelva ambigua cuando el proyecto crece. Un proyecto pequeño puede ser simple y estar bien organizado; el problema no es tener pocas carpetas, sino no poder explicar el flujo.
¿Qué debería documentar primero en un README?
La primera acción para ejecutar o visualizar el proyecto, los requisitos que no son obvios, el significado de las carpetas principales y las decisiones que otra persona podría interpretar de forma equivocada.
Martin Rojas escribe sobre tecnología, programación y desarrollo web. En Skydutz Academy comparte explicaciones prácticas sobre herramientas digitales, conceptos de programación y recursos para aprender de forma progresiva. Su objetivo es hacer que los temas técnicos sean más claros, útiles y accesibles para lectores de distintos niveles.