Estructura de un proyecto web

Un proyecto desordenado es difícil de mantener, de entregar y de retomar meses después. En esta lección aprenderás a organizar carpetas y archivos como lo hacen los profesionales, las convenciones de nombres y las buenas prácticas que hacen que un cliente (o tu yo del futuro) te lo agradezca.

Concepto

Organizar un proyecto es como organizar una cocina: los cubiertos en un cajón, las especias en otro. No importa tanto qué sistema uses, sino que sea consistente y que cualquiera encuentre las cosas sin preguntarte.

Estructura de un sitio estático

Para una landing page o un sitio informativo (HTML, CSS y JS):

mi-sitio/
├── index.html            ← página principal (siempre en minúsculas)
├── nosotros.html
├── contacto.html
├── css/
│   ├── reset.css         ← normaliza estilos del navegador
│   └── styles.css        ← tus estilos
├── js/
│   └── main.js
├── img/
│   ├── logo.svg
│   ├── hero.webp
│   └── equipo/
│       ├── ana.webp
│       └── luis.webp
├── fonts/                ← si alojas tus propias fuentes
├── favicon.ico
├── robots.txt
├── .gitignore
└── README.md

¿Por qué index.html?

Cuando alguien visita minegocio.com, el servidor busca automáticamente un archivo llamado index.html (o index.php). Si no existe, muestra un error o la lista de archivos.

Enlazar los archivos

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Café Aroma | Cafetería de especialidad</title>
  <!-- Rutas relativas a index.html -->
  <link rel="stylesheet" href="css/reset.css">
  <link rel="stylesheet" href="css/styles.css">
</head>
<body>
  <img src="img/logo.svg" alt="Logotipo de Café Aroma">

  <!-- El script al final o con defer para no bloquear la carga -->
  <script src="js/main.js" defer></script>
</body>
</html>

Estructura de un proyecto moderno (con Vite)

Cuando uses herramientas como Vite, Sass o un framework, verás algo así:

mi-app/
├── node_modules/         ← dependencias (NO se sube a Git)
├── public/               ← archivos que se copian tal cual (favicon, robots.txt)
├── src/
│   ├── assets/           ← imágenes y fuentes procesadas
│   ├── styles/
│   │   ├── base/
│   │   ├── components/
│   │   └── main.scss
│   ├── components/
│   └── main.js
├── dist/                 ← resultado final para publicar (generado)
├── index.html
├── package.json          ← dependencias y scripts
├── package-lock.json
├── vite.config.js
├── .env                  ← variables secretas (NO se sube)
├── .env.example          ← plantilla sin valores reales (sí se sube)
├── .gitignore
└── README.md

Convenciones de nombres

Regla	Bien	Mal
Minúsculas	contacto.html	Contacto.HTML
Sin espacios (usa guiones)	sobre-nosotros.html	sobre nosotros.html
Sin acentos ni ñ	disenio.css, contrasena.js	diseño.css, contraseña.js
Descriptivos	hero-cafeteria.webp	IMG_20240312.jpg
Consistentes	btn-primario, btn-secundario	btnPrimario, boton_2

Error común

En Windows Logo.png y logo.png son el mismo archivo, pero en un servidor Linux no. Tu sitio funciona en tu computadora y al subirlo las imágenes "desaparecen". Usar siempre minúsculas lo evita.

Para el código:

• HTML/CSS: clases en kebab-case → .tarjeta-producto, o con metodología BEM → .tarjeta__titulo--destacado (lo verás en Arquitectura CSS).
• JavaScript: variables y funciones en camelCase → totalCarrito, mostrarMenu(); constantes globales en MAYUSCULAS → API_URL; clases en PascalCase → Carrito.

Buenas prácticas generales

1. Separa responsabilidades: HTML para estructura, CSS para estilo, JS para comportamiento. Evita estilos en línea (style="...") y JavaScript dentro de atributos (onclick="...").
2. No repitas código (principio DRY): si copias y pegas tres veces, crea una clase o función reutilizable.
3. Indentación consistente (2 espacios es lo más común en web). Prettier lo hace por ti.
4. Comenta el porqué, no el qué:

/* Mal: pone el margen en 0 */
.hero { margin: 0; }

/* Bien: el hero debe tocar el header sticky sin hueco */
.hero { margin: 0; }

5. Optimiza imágenes antes de subirlas (WebP/AVIF, tamaño adecuado). Lo verás en el curso de HTML.
6. Usa control de versiones desde el primer día (Git).
7. Escribe un README con: descripción, cómo ejecutarlo, cómo desplegarlo y credenciales necesarias (sin valores reales).

Plantilla de README

# Café Aroma — Sitio web

Landing page de la cafetería Café Aroma.

## Tecnologías
HTML5, CSS3, JavaScript (sin dependencias).

## Ejecutar en local
Abrir index.html con Live Server.

## Despliegue
Netlify, conectado a la rama main (despliegue automático).

## Contacto
Desarrollado por Tu Nombre — tu@correo.com

Casos de uso reales: entregar a un cliente

Antes de entregar un proyecto, revisa:

• [ ] Estructura de carpetas clara y sin archivos basura (copia de styles.css, prueba.html).
• [ ] Nombres en minúsculas y sin espacios.
• [ ] Imágenes optimizadas.
• [ ] Sin console.log de depuración ni código comentado inútil.
• [ ] README actualizado.
• [ ] Repositorio en Git con historial limpio.
• [ ] Probado en móvil, tablet y escritorio, en Chrome, Firefox y Safari.

Buena práctica

Crea tu propia plantilla base (estructura de carpetas, reset.css, .gitignore, README) y cópiala al iniciar cada proyecto. Ahorrarás tiempo y tus proyectos serán consistentes.

Ejercicios

1. Crea con la terminal la estructura de un sitio estático con index.html, css/styles.css, js/main.js e img/.
2. Renombra correctamente estos archivos: Foto Equipo 1.JPG, Contáctanos.html, ESTILOS-final-v2.css.
3. Escribe el head de index.html enlazando el CSS y el JS con buenas prácticas.

Ver solución

mkdir -p mi-sitio/css mi-sitio/js mi-sitio/img
touch mi-sitio/index.html mi-sitio/css/styles.css mi-sitio/js/main.js

2. foto-equipo-1.jpg (mejor aún, convertida a foto-equipo-1.webp), contactanos.html, styles.css (Git guarda las versiones, no necesitas "final-v2").

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Mi sitio</title>
  <link rel="stylesheet" href="css/styles.css">
  <script src="js/main.js" defer></script>
</head>

Resumen

• Organiza por tipo: css/, js/, img/, con index.html en la raíz.
• Nombres en minúsculas, sin espacios ni acentos, y descriptivos.
• Separa HTML, CSS y JS; no repitas código; comenta el porqué.
• node_modules, dist y .env no se suben a Git.
• Usa un checklist antes de entregar y crea tu propia plantilla base.

Siguiente: Aprender, buscar y resolver errores.