En el artículo de Instalando Angular, creando un proyecto y arrancándolo en local ya vimos cómo crear y arrancar un proyecto en Angular.

En este artículo, nos basaremos en el estado en el que dejemos el artículo anterior. Cuando hemos creado el proyecto desde el Terminal con la instrucción ng install -g @angular/cli, hemos visto, que como nos iba generando la estructura de Angular:

El proceso de creación/construcción de una estructura de un proyecto se conoce bajo el término de scaffolding (andamienando), que se trata de explicar que se está (auto construyendo o auto montando) la estructura de nuestro proyecto.

Estructura de un proyecto de Angular

Si abrimos el proyecto con VSC, podemos ver su estructura:

  • e2e (e2e de “end to end”): contiene una serie de ficheros cuyo objetivo es realizar test automáticos, que simularán que un usuario real interactúa con nuestra app de Angular.

Para ejecutar los test e2e, ejecutamos el comando ng e2e, vamos a ver un ejemplo:

Vemos que el test ha finalizado en SUCESS, lo que significa que se ha ejecutado correctamente.

  • Node_modules tiene los paquetes (también conocidos como dependencias) instaladas en nuestro proyecto con el instalador de paquetes (npm) de node.

Un ejemplo puede ser la dependencia de @angular/cli que hemos instalado. Que tengamos muchas librerías en este directorio es bastante normal, y no nos debe de preocupar. Es más, son muchas las librerías que internamente requieren otras librerías para poder funcionar/trabajar por lo que si lo desplegamos es normal, que nos salga una lista sin fin de archivos.

  • src (src de Source): es el directorio sobre el que trabajaremos nosotros y que contiene los distintos módulos que dan forma a nuestra aplicación. Por el momento, solamente mostrarnos su directorio, pero no abrimos el melón de su estructura. Ya que tiene muchos conceptos a explicar y es mejor primero finalizar de explicar la estructura principal y, posteriormente, en otro artículo, nos detendremos a explicar cada uno de sus elementos más detenidamente.

Aunque todos los directorios/archivos son importantes, SRC es sin duda alguna uno de que más importancia tienen ya que, será el directorio sobre el que nos permitirá desarrollar nuestra aplicación de Angular. SRC, contendrá la mayoría de nuestro código. Si nos fijamos en el resto de archivos que hemos explicado y que aún nos queda por explicar, son archivos de configuración, testing, etc.

  •  .browserslistrc: es un listado sobre la que podemos definir la compatiblidad de los navegadores con nuestro proyecto de Angular.

De hecho, si nos adentramos en el propio archivo, podemos observar que podemos ver que nos aparece de forma predeterminada listado de compatibilidad de nuestra aplicación de Angular, realmente este listado surge de ejecutar el comando: npx browserlist que nos aparece dentro del archivo browserlistrc:

Si ejecutamos el comando nosotros desde nuestra terminal, podemos ver la lista esa lista de otra forma con el conjunto de navegadores que compatibles son compatibles en nuestro app de Angular:

¿Porque y para que se utiliza esto? Anteriormente, Angular transpilaba (traducía/compilaba) los archivos de TypeScript a la versión ES5 de JavaScript.

Como estamos viendo en las imágenes, la versión ES5 de JavaScript, es la versión de 2009. Y por tanto, era compatible con la inmensa mayoría de versiones de los distintos navegadores.

En la actualidad, Angular, por defecto ya no trabaja con ES5, y aunque lo podemos editar, ha empezado a dejar de trabajar con esta versión y, por tanto, de tener compatibilidad con algunas versiones prehistóricas de los navegadores. Para pasar a trabajar con ES6, renunciar a la compatibilidad de algunos navegadores es el precio que tiene que asumir a cambiar de mejorar su rendimiento subiendo un escalón en la versión de EcmaScript sobre la que trabaja.

De hecho, lo todo esto, lo podemos corroborar si vamos al archivo tsconfig.json y nos situamos sobre la key target que tiene un valor de ES2015 que es nada más y nada menos que el escalón del que hablábamos que acabábamos de subir, la versión ES6 de EmcaScript:

Si queréis indagar más en el tema os dejo varias fuentes:

  • .editorconfig: nos permite definir normas tanto genéricas como especificas:

    • [*] → genéricas para todos los archivos: Como el tipo de codificación que usaremos en el proyecto, el tamaño de la identación que usaremos, etc.
    • [*.ts] → particulares para los archivos con extensión .ts y, por tanto, archivos de TypeScript: Como por ejemplo que usaremos comillas simples en ese caso y se podría modificar por dobles, etc.
    • [*.md] → particulares para los archivos con extensión .md y, por tanto, archivos de MarkDown: como por ejemplo si existe longitud máxima de la línea, si se quitan los espacios en blanco finales, etc.

Nosotros podríamos configurar nuestras propias normas o modificar las existentes. Con el fin de que todos los programadores del proyecto utilicen las mismas convenciones a la hora de escribir.

  • .gitignore: contiene un listado de ficheros y directorios que no queremos que se suban al repositorio de git (como contraseñas, o el paquete de node_modules, etc.)

Así que, ya sabéis, si alguna vez te aparecen 5425 cambios en gitHub, posiblemente hayas subido el node_modules a vuestro repositorio de Git.

  • angular.json: este archivo contiene la configuración de Angular. Si nos metemos en el podemos ver que asocia y define muchos valores tales como: el nombre del proyecto, el HTML inicial que cargaremos, etc.

  • karma.conf.js: es el archivo de configuración para realizar testing con Karma. Karma, ha sido desarrollado por el equipo de Angular, y viene preinstalada en Angular junto a Jasmine, con el fin de que nos centremos en realizar los test y para que sea lo más sencillo posible ya viene autoconfigurada para que nosotros nos centremos solamente en nuestros tests.

La herramienta de testeo para realizar testing en Angular por defecto es Jasmine. Karma, se encarga de informarnos/mostrarnos los resultados de los test (que hemos realizado en Jasmine) en el navegador y, además, nos permite depurar el código.

Vamos a ver un ejemplo. Si vamos a la Terminal y ejecutamos:

Podemos ver que se nos abrirá una pestaña donde se muestran los test que se han realizado, y los resultados (que también podemos ver desde la ventana de terminal aunque de una forma menos específica).

Si queréis investigar más al respecto, os dejo un enlace a la web oficial de Karma

  • package.json y package-lock.json: el archivo package.json es un manifiesto (declaración pública) que nos informa sobre todas las dependencias que necesita nuestra aplicación de Angular para funcionar.

El package.json , tiene 3 secciones a destacar:

  1. Scripts: contiene un listado de métodos asociados a npm como start con el que ya hemos visto como arrancar una aplicación. También podemos añadir los nuestros.
  2. Dependencies: contiene las dependencias necesarias para la ejecución de nuestra aplicación. Como, por ejemplo: angular/router, angular/core, angular/forms, etc.
  3. DevDependencies: contiene las dependencias que vamos a usar durante el desarrollo de nuestra aplicación.

En cambio, el archivo package-lock.json nos muestra la versión específica que estamos usando actualmente en nuestro proyecto.

Como ya sabemos, el directorio node_modules, no se sube a Git. Y, por tanto, si alguien descarga nuestro proyecto, tendrá que descargar una a una todas las dependencias.

Por tanto, si no subimos las dependencias del proyecto ¿Como sabemos las dependencias que necesitamos? ¿Descargará la versión del package.json o la versión de package-lock.json? La respuesta que utilizar npm para responder a esa pregunta es ir al package.json y descargar sus versiones.

¿Y qué hará npm? En el inicio de cada una de las dependencias, del fichero de package.json, podemos ver que en su inicio empieza por ^o ~
esto quiere indicarle a npm que versión (version range) debe descargar.

“nombre-de-la-dependencia”: “(^|~|version)|url”

Son caracteres opcionales que definen como debe ser tratada esa dependencia la próxima vez que se corra npm install en el proyecto:

  • Si la versión tiene un ^: Se buscará la versión anterior a la dependencia le dice a npm que, si alguien clona el proyecto y lo ejecuta npm install, debe instalar la última versión menor. Por ejemplo:
    • “@angular/cli”: “~10.2.0” descargará la versión más reciente disponible que no superé la versión 10.X . Si por ejemplo existe una versión 10.5.3, descargará esa versión, pero no descargaría la versión 11.1.0. Algunos ejemplos más podrían ser:
      • ^1.2.3 : = >=1.2.3 <2.0.0
      • ^0.2.3 : = >=0.2.3 <0.3.0
      • ^0.0.3 : = >=0.0.3 <0.0.4
    • Si la versión tiene un ~: Se buscará una versión lo más cercana posible a la definida. Permite cambios a nivel de parche si se especifica una versión menor en el comparador. Permite cambios menores de nivel si no.
      • ~1.2.3: = >=1.2.3 <1.(2+1).0: =>=1.2.3 <1.3.0
      • ~1.2: = >=1.2.0 <1.(2+1).0: = >=1.2.0 <1.3.0(Igual que 1.2.x)
      • ~1: = >=1.0.0 <(1+1).0.0: = >=1.0.0 <2.0.0(Igual que 1.x)
      • ~0.2.3: = >=0.2.3 <0.(2+1).0: =>=0.2.3 <0.3.0
  • Si no tiene ningún símbolo: Se instalará la misma versión. Por ejemplo:
    • “@angular/cli”: “10.2.0” descargará especificamente la versión 10.2.0.

Aunque existen muchas más. Algunos ejemplos son:

  • < Menos que
  • <= Menos que o igual a
  • > Mas grande que
  • >= Mayor qué o igual a
  • =Igual. Si no se especifica ningún operador, se asume la igualdad, por lo que este operador es opcional, pero PUEDE incluirse.

Es posible que, en ocasiones, tantas versiones y tantas versiones nos puedan causar algún que otro problema, ya que los colaboradores del mismo proyecto pueden estar todos en diferentes versiones de dependencia.

Por ello, es package-lock.json el que cada vez que se descarga una versión almacena la versión actual sobre la que se está trabajando. Por si en caso de conflicto, esto, nos ayudará mejor a detectar cual puede ser el problema.

  • README.md es el archivo que suele visualizar en el repositorio a la hora de descargarlo. Suele ser una especie de guía que contiene los pasos o instrucciones de configuración de rutas, comandos de instalación, etc.

De hecho, si abrimos el fichero y le damos a Open Preview to the Side:

Podemos ver la vista previa del fichero:

  • tsconfig.app.json, tsconfig.json y tsconfig.spec.json: estos 3 ficheros nos permiten definir configuraciones para cuando realicemos la transpilación (traducción) de nuestro código. Este código no puede ser leído por el navegador por el momento ya que está en TypeScript (con extensión .TS) y una vez transpilado a JavaScript (con extensión .JS) y que ahora sí que puede ser leído por el browser.

El archivo tsconfig.json contiene la configuración general de escritura del código de TypeScript y principalmente destaca:

    • BaseUrl: nos sirve para indicarle la ruta raíz de nuestro proyecto
    • Modul: es la versión de EcmaScript sobre la que vamos a desarrollar nuestro TypeScript.
    • Target: es la versión a la que vamos a transpilar nuestro TypeScript, en este caso, ES2015 = EscmaScript 6 (se podría modificar como ya hemos visto anteriormente).

Los otros dos ficheros, vemos en ambos casos extienden del fichero anterior (tsconfig.json).

En el caso de tsconfig.app.json se relaciona con la aplicación de Angular (en modo normal), cargando sus clases y estableciendo el directorio de salida de la aplicación:

En cambio, tsconfig.spec.json, es la configuración de TypeScript para las pruebas de la aplicación.

  • tslint.json: dentro del fichero tslint.json, definimos una serie de reglas que se utilizaran durante el desarrollo de software para comprobar si el código fuente de TypeScript cumple con las reglas de codificación.

Por ejemplo, cuando escribimos código en TypeScript y el IDE se detecta un error, nos marca dicho error con una especie de subrayado en la parte inferior. Y si nos situamos encima, nos muestra más detalle sobre dicho error.

Espero que os haya quedado un poco más clara la estructura de Angular. Al principio suele ser bastante liosa y posiblemente tendréis que leer este artículo varias veces ya que es bastante duro de explicar. No quiero amargaros el momento, pero aún no hemos acabado con toda la estructura. Aun nos falta por explicar el directorio SRC, que como ya habíamos dicho anteriormente, lo explicaremos en la próxima lección. ¡Saludos y hasta pronto!