- Modules
- Testing
- Descargar el proyecto
- Deploys
- Buenas prácticas y código limpio
- Librerías de terceros
- Plugins para VS Code
- Prittier (esbenp.prettier-vscode)
- ESLint (dbaeumer.vscode-eslint)
- Code Spell Checker (streetsidesoftware.code-spell-checker)
- Code Spell Checker Español (streetsidesoftware.code-spell-checker-spanish)
- Jasmine Test Explorer (hbenl.vscode-jasmine-test-adapter)
- Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
Este módulo sirve mayormente para declarar todos los servicios y en menor medida componentes u otros artefactos que se utilicen en TODA la aplicación, la idea es que en el app.module.ts solo estén importados los módulos necesarios para que la aplicación de angular pueda arrancar.
Los guards son un tipo de middleware que controla el acceso a las rutas. Una buena práctica de los guards es que tengan una única responsabilidad. Ejemplo de guard: SuccessOtpGuard, este es el guard encargado de proteger todas las rutas que necesitan una verificación exitosa de un token OTP.
ng g guard core/guards/NUEVO-GUARD
Los interceptors también son otro tipo de middlewares, pero estos se ejecutan antes y/o después de cada llamada HTTP. Cada interceptor tiene que ser declarado en el provider del core.module.ts. Algunas de las buenas prácticas para los interceptors son que cada uno tenga una única responsabilidad y que cada interceptor tenga sus arreglos de excepciones. Ejemplo de interceptor: SpinnerInterceptor
ng g interceptor core/interceptor/NUEVO-INTERCEPTOR
Los servicios son funciones para compartir información entre clases, ya que cada componente no debería de guardar información. Mayormente los servicios se utilizan para realizar llamadas HTTP, pero también son una buena solución si se desea guardar información de manera sencilla y compartirla a lo largo de la aplicación. Buenas prácticas para los servicios, cada servicio debe de ser de un solo tema, por ejemplo UserService, AutenticationService, ProductService, etc. Si un método trae información por HTTP, es utilizado más de una vez y no tiene parámetros, como por ejemplo getAllProducts, es buena idea guardar la información que esta llamada devuelve y que el método solo llame una vez al endPoint, si se va a guardar información se debe de encapsular los parámetros.
ng g service core/services/NUEVO-SERVICIO
Dentro de esta carpeta estarán todos los componentes, pipes, directives, models y mocks reutilizables en la aplicación, los components, directives y pipes deben de ser pensados para poder ser compartidos hacia otras aplicaciones dentro de la incubadora. Esta deberá de ser el área de pruebas y refinamiento para luego ser trasladados hacia la librería compartida.
Estos son componentes reutilizables, por ejemplo podría ser un, custom input, una tarjeta, etc. Cada componente deberá de tener su propio módulo y el componente deberá de ser importado y exportado para poderse utilizar dentro de otros módulos. Buenas prácticas, es recomendable crear de primero el módulo y después el componente para que el CLI de Angular importe el componente dentro del nuevo módulo y no dentro del AppModule, el componente debe de ser configurable por medio de Inputs y debe de emitir información por medio de Outputs, Los componentes no debes de hacer llamadas a los servicios, todo lo que necesiten para funcionar deben de ser manejado por Inputs
ng m component shared/components/NUEVO-COMPONENTE
ng c component shared/components/NUEVO-COMPONENTE
Las directivas extienden las funcionalidades del HTML y son muy útiles para modificar el aspecto gráfico de los componentes de las librerías externas como PrimeNg, esta práctica es muy recomendable y para estos casos siempre se debería de hacer así, esto mejora la reutilización ya que al llamar a esa directiva dentro del componente de PrimeNg se modificará únicamente en ese componente, y si se necesita una variante se debe de crear una directiva para esa nueva variante, con eso se logra reutilizar el código y ser flexible.
ng g directive shared/directives/NUEVA-DIRECTIVA
Los pipes son funciones muy simples para transformar data en el template. Pueden ser máscaras para dar formato con puntos desimales, formato de monedas, etc.
ng g pipe shared/pipes/NUEVO-SERVICIO
Los modelos son interfaces de objetos, es muy importante no utilizar tipos any, en vez de eso hay que crear modelos. Buenas prácticas: si necesitamos crear una lista
ng g pipe shared/pipes/NUEVO-SERVICIO
Los mocks son representaciones de los servicios del backend. Utilizamos la librería fakerJS para generar instancias con información falsa y de esta manera siempre que se quiera componentes que hagan uso de servicios del backend utilizaremos estos mocks. La creación de cada mock debe de ser manual dentro de la ruta /app/shared/mocks/NUEVO-MOCK
Únicamente realizamos test unitarios, los realizamos con Karma y Jasmine.
Para testear componentes que dependan de servicios debemos de mockear los servicios con la librería fake-js y para reutilizar estos mocks debemos de guardarlos en la carpeta /src/app/shared/moks/, en esta carpeta ya se encuentra un ejemplo de como se debe de crear un mock
Al descargar este repositorio para dar inicio a un proyecto nuevo se deban de hacer los siguientes pasos:
- Clonar el proyecto
$ git clone https://github.com/BancoIndustrial-Incubadora/BI-Skeleton-FrontEnd-New.git
-
Crear en github un nuevo repositorio para alojar el nuevo proyecto
-
Cambiar el origen del repositorio para que apunte al nuevo repositorio recién creado
$ git remote set-url origin new.git.url
- Realizar un pull y un push a la rama dev
$ git pull origin dev
$ git push origin dev
- Configurar las variables de ambiente, para ello hay que duplicar el archivo .env.example que se encuentra en la raíz del proyecto y cambiarle de nombre a .env y agregarle las variables de ambiente que se deseen, así mismo agregar las variables de ambiente a la los archivos /enviroments/enviroment.prod.ts y /enviroments/enviroment.ts de la siguiente manera
enviromentExapleKey: process.env.NG_APP_ENVIROMENT_KEY_IN_ENV_FILE || ''
- Instalar de forma global la librería commitizen
npm install -g commitizen
- Instalar todas las dependencias del proyecto
npm install
- Correr la aplicación
ng serve
Para realizar deploys utilizamos la herramienta de Husky para automatizar el flujo. El flujo de Husky es el siguiente:
- Corrige los estilos con el linter
- Realiza los test unitarios.
- Agrega al área de staging los cambios realizados
- Realiza un commit utilizando la herramienta commitizen para estandarizar los comentarios y nombres del commit.
- Realiza un pull a la rama dev para actualizar todos los cambios
Si algún paso falla, el flujo se corta y no se realiza el commit.
Luego que se termine el flujo del commit se debe de realizar un push a la feature branch y pedir un pull request a la rama dev.
Los siguientes son los comandos para realizar un push:
npm run commit:dev
git push origin feature-branch
Comitizen es una herramienta para estandarización de commits a nivel de nombramiento y comentarios por medio de un proceso guiado en consola. Esto sirve para que sea más fácil encontrar qué cambios se realizaron dentro de cada commit. El proceso es el siguiente:
- Seleccionar el tipo de cambio, exiten 8 tipos distintos de cambios
- Feat: Si se realizó una nueva funcionalidad
- Fix: Si se corriguió un bug
- Docs: Si se modificó la documentación
- Style: Si se modificó el estilo del código, por ejemplo si se agregó un punto y coma, si se quitaron a agregaron comentarios, si se cambió la indentación. Esta no es una modificación de estilo de gráfico de CSS o HTML
- Refactor: Si se hace una refactorización de código, la refactorización es un cambio a nivel de legibilidad, pero no de funcionalidad, la entrada y la salida de un código refactorizado siempre tiene que ser la misma
- Perf: Mejora de performance
- Test: si se agrega o modifica algún test.
- Chore: Son cambios que mofican la manera en que se compila el proyecto o el agregar una nueva librería.
Nombramiento de variables
- Utilizar nombres significativos y pronunciables.
- Las variables deben estar en inglés.
- Usar lowerCamelCase.
- No usar caracteres especiales y tampoco numéricos.
- Crear variable constante para valores inmutables. (Variables que no cambian de valor)
- Para variables tipo lista, utilizar plural.
- Variable tipo numérico, escoger palabras que describan números como prefijoMax, prefijoMin o prefijoTotal.
Nota: lowerCamelCase, cuando la primera letra de cada una de las palabras es mayúscula, con la excepción de que la primera letra es minúscula.
Ejemplo: ejemploDeLowerCamelCase
// Incorrecto
let salary_monetario: number = 123.21;
let usernombre: string = 'Pedro';
let mascota: string[] = ['Toby', 'Perry'];
// Correcto
let moneyBalance: number = 245.76;
let userName: string = 'Pedro';
let pets: string[] = ['Toby', 'Perry'];- No hacer uso de var para declaración de variables.
- Usar let cuando se va modificar el contenido.
- Usar const cuando nunca se modifica el contenido.
- Evitar utilizar los "Magic Numbers", en vez de eso se debe de crear una constante con un nombre explicativo en mayusculas en las declaraciones de los parámetros
// Incorrecto
if( value < 150 ){
...
}
// Correcto
const MIN_ALLOWED_CREDIT_SCORE = 150;
if( value < MIN_ALLOWED_CREDIT_SCORE ){
...
}Las clases y los objetos deben tener nombres formados por un sustantivo o frases de sustantivo como User, UserProfile, Account o AdressParser. Debemos evitar nombres genéricos como Manager, Processor, Data o Info.
Hay que ser cuidadosos a la hora de escoger estos nombres, ya que son el paso previo a la hora de definir la responsabilidad de la clase. Si escogemos nombres demasiado genéricos tendemos a crear clases con múltiples responsabilidades.
Requisitos de funciones:
- Las funciones y métodos deben de realizar una sola acción.
- Si los argumentos son más de 3, se deberá enviar objeto serializado.
- No duplicar acciones y código.
- Utilizar una descripción corta del método.
- Utilizar un prefijo con base a la acción.
- Las funciones deben de tener un tamaño de líneas reducido.
- No hacer referencia al mismo concepto.
// Correcto
getUser();
updateUser();- Se recomientda no escribir comentarios, aún que algunas veces son útiles.
- Los comentarios no deben de explicar lo que el código hace, el código debe de ser autoexplicativo utilizando un código ordenado y un buen nombramiento de variables.
- Los comentarios deben de explicar por qué se utilizó esa implementación del código cuando se crea que no sea tan clara.
No deberíamos de instalar librerías de terceros sin analizar
Es una librería de componentes gráficos, como por ejemplo, calendario, inputs, acordiones, etc.
Es un framework CSS enfocado a utilidades, la definición de la utilidades se hace por medio de clases en el html, pero para que el html se vea más limpio nosotros recomendamos utilizar la metodología BEM y utilizar las utilidades de tailwind con @apply en el archivo scss.
Esta librería tiene pipes para agregarle máscaras a al template.
Librería para el manejo de Google Analytics
Librería para el manejo de Google Tag Manager
Librería para el manejo de Google Recaptcha
Esta librería no está incluída en el proyecto por que no siempre será necesario su uso ya que con los servicios de Angular se puede compartir información entre componentes, pero si queremos que esta información se actualice de manera reactiva Redux es la opción para ello.
Todas las configuraciones necesarias están dentro de la carpeta .vscode de ser necesario realizar más configuraciones buscar la manera de realizarlas dentro de esta carpeta o a nivel del proyecto y no de usuario, ya que esta configuración viaja por repositorio y a así todo el quipo se beneficiará de las configuraciones realizadas.
Formatea el código para que cumpla con los estándares
Plugin para poder visualizar en tiempo real si el código no cumple con el estándar
Verifica si existen faltas de ortografía en inglés, muy útil al momento de nombrar variables, métodos y clases
Add on de Code Spell Checker, verifica si hay faltas de ortografía en español
Este plugin nos ahorra mucho tiempo a la hora de escribir tests unitarios ya que con él podemos seleccionar el test que estamos corriendo y correrlo sin necesidad de ejecutar todos los test del proyecto.
Mejora la experiencia de desarrollo de Tailwind al agregarle snippets, autocompletador y linter.