Estructura de archivos

Estructura de carpetas y archivos de un proyecto


Ahora que ya conocemos las bases de los Custom Elements (la parte de WebComponents que permite crear nuestras propias etiquetas), toca comenzar a crear componentes básicos para ir viendo la estructura que podemos seguir para dotarle de funcionalidad.

Estructura de componentes

En este artículo vamos a ver como preparar una estructura de carpetas y archivos utilizando WebComponents, como crear nuestro primer componente y las diferentes formas de enlazarlo, tanto desde HTML como desde Javascript.

Estructura inicial de carpetas

Quizás, lo primero que deberíamos tener claro es la estructura de carpetas y archivos que vamos a tener para crear nuestros componentes.

En principio, esta «arquitectura de archivos y carpetas» depende mucho de cada programador y es muy variable dependiendo de nuestros objetivos. Vamos a partir de un ejemplo sencillo de base, donde src es la carpeta que contiene nuestro código fuente:

- src
   +-- components/
   |     +-- AppElement.js
   +-- index.html
   +-- index.css
   +-- index.js
  • 1️⃣ Partimos de index.html (punto de entrada): el fichero que abre inicialmente el navegador.
  • 2️⃣ De este punto de entrada, cargaremos un archivo index.js que hará de nexo central donde importaremos todos los componentes de nuestra página.
  • 3️⃣ En la carpeta src/components/ colocaremos todos los componentes, separados en un fichero independiente con el nombre en PascalCase del componente.

En definitiva, index.html => index.js => components/AppElement.js. Vamos a repasar toda la estructura para entenderla correctamente, paso por paso.

Estructura HTML inicial

Como hemos mencionado, lo primero sería crear nuestro fichero index.html donde tendremos nuestra página inicial. Ahí enlazaremos a nuestro archivo index.js central y al archivo index.css:

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>Página principal</title>
  <link rel="stylesheet" href="./index.css">
  <script type="module" src="./index.js"></script>
</head>
<body>

  <app-element></app-element>

</body>
</html>

Nuestro archivo index.css podemos mantenerlo vacío de momento. Pero centrémonos en el archivo index.js, que no estará vacío. Este archivo servirá de punto central donde importaremos todos los componentes. Por último, observa que en el <body> del index.html hemos añadido el componente <app-element>, aunque aún no lo hemos importado y no funcionará todavía.

Estructura Javascript inicial

Por su parte, en el fichero index.js podremos ir añadiendo los componentes que queramos cargar en nuestra página. El index.js enlazado desde nuestro index.html tendrá el siguiente contenido:

import "./components/AppElement.js";

Recuerda que este index.js debe ser enlazado mediante una etiqueta <script type="module"> como vimos en el fragmento anterior. Sin el type="module" no sería posible utilizar un import en este fichero, ya que nos daría el siguiente error en la consola Javascript:

Uncaught SyntaxError: Cannot use import statement outside a module

Si obtienes dicho error, simplemente revisa que no te hayas olvidado del type="module" en el <script> del index.html.

Usando HTML para importar

Otra opción alternativa interesante podría ser no utilizar un archivo index.js central, sino cargarlo todo desde un index.html. Observa este <head> alternativo del index.html:

<head>
  <meta charset="utf-8">
  <title>Página principal</title>
  <link rel="stylesheet" href="./index.css">
  <script type="module" src="./components/AppElement.js"></script>
</head>

En este caso, el nexo central sería el index.html en lugar del index.js.

Una segunda forma alternativa podría ser hacerlo desde un <script type="module"> incrustado también en el index.html. A efectos prácticos son muy similares las tres formas:

<head>
  <meta charset="utf-8">
  <title>Página principal</title>
  <link rel="stylesheet" href="./index.css">
  <script type="module">
    import "./components/AppElement.js";
  </script>
</head>

La decisión depende del programador. Quizás, utilizar un fichero Javascript como nexo central pueda ser más flexible, pero son opciones muy similares que normalmente dependen de los hábitos y costumbres del programador.

Estructura del componente

Una vez hemos llegado a este punto, hay que empezar a crear los componentes. Por defecto, los componentes se incluyen en la carpeta components/, dentro de src/. Los componentes deben estar siempre separados en archivos independientes, con el nombre de la clase en PascalCase. Si nuestro componente HTML se llama base-element, la clase y el archivo se llamarán BaseElement.

Veamos el contenido de nuestro archivo src/components/AppElement.js:

class AppElement extends HTMLElement {

  constructor() {
    super();
  }

}

customElements.define("app-element", AppElement);

Este sería el contenido mínimo para crear un componente. No olvides nunca escribir el customElements.define(), ya que es el que realiza la asociación de la etiqueta HTML con la clase que hemos definido.

Usar componente desde HTML

Una vez tengamos nuestro componente cargado y enlazado, la primera forma y más sencilla de utilizarlo, simplemente requiere escribir el nombre de nuestra etiqueta HTML personalizada en el HTML:

<app-element></app-element>

Esta es la forma más básica y común. Pero no es la única.

Usar componente desde Javascript

Puede interesarnos crear el componente desde Javascript, útil para hacerlo dinámico, usarlo en bucles, condicionales y/o aprovecharnos de toda la potencia de Javascript.

A través del DOM

En ese caso, tendríamos que hacer lo siguiente:

// Utilizando el DOM
const appElement = document.createElement("app-element");
document.body.append(appElement);

Hemos hecho lo siguiente:

  • 1️⃣ Creamos el elemento HTML <app-element> en memoria, en la variable appElement.
  • 2️⃣ Insertamos el elemento en el DOM del documento HTML, concretamente al final del <body>.

A través de instancias

Existe una variación de la anterior. Para hacerlo de esta otra forma, en nuestro fichero AppElement.js, tendríamos que exportar la clase, para así poder importarla desde otro archivo.

Haríamos la siguiente modificación en components/AppElement.js:

export class AppElement extends HTMLElement {
  /* ... */
}

Ahora, desde nuestro archivo index.js, en lugar de hacer una importación directa, la haríamos importando la clase AppElement para luego crear una instancia utilizando el new:

import { AppElement } from "./components/AppElement.js";

const appElement = new AppElement();
document.body.append(appElement);

Obsérvese que en el fichero index.js hemos importado la clase AppElement que exportamos en el punto anterior. En el resto del código del fichero podríamos ahora trabajar con ella de forma análoga a como lo hicimos más atrás con .createElement().

Ahora que ya tenemos la estructura clara, debemos ver ejemplos y aprender que cosas podríamos hacer para crear componentes realmente útiles, que trabajen con el HTML y el CSS de nuestros componentes. Lo veremos en los siguientes capítulos.

¿Quién soy yo?

Soy Manz, vivo en Tenerife (España) y soy streamer partner en Twitch y profesor. Me apasiona el universo de la programación web, el diseño y desarrollo web y la tecnología en general. Aunque soy full-stack, mi pasión es el front-end, la terminal y crear cosas divertidas y locas.

Puedes encontrar más sobre mi en Manz.dev