Subdirecci贸n de las Tecnolog铆as de la Informaci贸n y Comunicaciones

脕rea de Gobernanza y Calidad

Versi贸n


Normativa front guia implementacion Scaffolding Vigente

Versión: 1.0.0
Estado: ACTIVO
Entrada en vigor desde:  
Obligado cumplimiento desde:  Sept-2023



Normativa front guia implementacion Scaffolding PRE-RELEASE

Versión: 1.0.0
Estado: RELEASE
Entrada en vigor desde:  
Obligado cumplimiento desde: -


Tabla de Contenido


Cumplimiento Normativo


Las normas expuestas son de obligado cumplimiento. La STIC podrá estudiar los casos excepcionales los cuales serán gestionados a través de los responsables del proyecto correspondiente y autorizados por el Área de Gobernanza de la STIC. Asimismo cualquier aspecto no recogido en estas normas deberá regirse en primera instancia por las guías técnicas correspondientes al esquema nacional de seguridad y esquema nacional de interoperabilidad según correspondencia y en su defecto a los marcos normativos y de desarrollo software establecidos por la Junta de Andalucía, debiendo ser puesto de manifiesto ante la STIC.

La STIC se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata según la planificación de cada proyecto.

En el caso de que algún actor considere conveniente y/o necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehaciente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida por la STIC para proceder a su validación técnica.

Contacto Arquitectura: l-arquitectura.stic@juntadeandalucia.es

Hist贸rico de cambios


Los cambios en la normativa vendr谩n acompa帽ados de un registro de las modificaciones. De este modo se podr谩 realizar un seguimiento y consultar su evoluci贸n. Orden谩ndose de mas recientes a menos recientes, prestando especial cuidado a las cabeceras de la tablas d贸nde se indican las fechas de entrada en vigor y versi贸n.

VersiónPre-release AdopciónActivaRetiroAlcance
v01r00

 




  • Versión inicial del documento

1. Introducci贸n

Este proyecto es un command line interface (cli) para node que pretende facilitar la creaci贸n de proyectos para el uso de web components con Lit y TypeScript. La estructura del proyecto, as铆 como la de sus elementos, son acordes a la normativa arquitect贸nica definida por las STIC.

2. Uso

Una vez descargado el proyecto, desde la ra铆z del mismo ejecutamos por consola:

foo@bar:~$ sas-cli <comando> [opción]
ContextoAcci贸nComandoOpci贸nDescripci贸n
app


Todas las acciones relativas a un proyecto de tipo aplicaci贸n

createapp:create
creaci贸n de un proyecto de tipo aplicaci贸n

cleanapp:clean
limpia elementos temporales de la construcci贸n de la aplicaci贸n (out-ts, dist,back-up y coverage )



-a --alllimpia todo elemento que no sea parte del c贸digo fuente (elementos temporales, node_modules, package-lock.json)
monorepo


Todas las acciones relativas a un proyecto de tipo monorepo. Este tipo de proyecto es el ideal para el desarrollo de componentes reutilizables y publicables (web-componentes, librer铆as)

createmonorepo:create
Creaci贸n de un proyecto de tipo monorepo

initmonorepo:init
Inicializa un monorepo existente creando los enlaces y las carpetas necesarias para los componentes existentes

cleanmonorepo:clean
Limpia elementos temporales de la generaci贸n del monorepo (types, dist,back-up y coverage ). Tambi茅n elimina los elementos temporales para los componentes creados en el proyecto



-a --allLimpia todo elemento que no sea parte del c贸digo fuente (elementos temporales, node_modules, package-lock.json). Tambi茅n elimina todo elemento que no sea parte del c贸digo fuente para los componentes creados en el proyecto
WebComponent


Todas las acciones relativas a un componente de tipo webcomponent

createwc:create
Creaci贸n de un componente tipo webcomponent



-d --dirCrea el web componente en una carpeta concreta dentro de la carpeta package del monorepo. Admite profundidad (carpeta1/carpeta2/carpeta3 ... )
Librer铆a


Todas las acciones relativas a un componente de tipo librer铆a

createlib:create
Creaci贸n de un componente tipo librer铆a



-d --dirCrea la librer铆a en una carpeta concreta dentro de la carpeta package del monorepo. Admite profundidad (carpeta1/carpeta2/carpeta3 ... )

3. Proyectos

En esta secci贸n se van a abordar los siguientes tipos de proyectos que actualmente se proporcionan por sas-cli: monorepo y aplicaci贸n

3.1 Monorepo

El proyecto est谩 configurado para ser ejecutado como un monorepo, haciendo uso de la opci贸n workspace de npm a partir de la versi贸n 7.X. Puede albergar un cat谩logo de componentes reutilizables (WebComponents, librer铆as)

foo@bar:~$ sas-cli monorepo:<acción> [options]

3.1.1 Generaci贸n del monorepo

foo@bar:~$ sas-cli monorepo:create
  • Este comando crear谩 un proyecto de tipo monorepo sobre una carpeta que no contenga un proyecto creado con anterioridad.
  • Se crear谩 la estructura esqueleto del proyecto
  • Se pedir谩 informaci贸n b谩sica para la construcci贸n del monorepo
  • Se generar谩n los ficheros con la informaci贸n recopilada

Esta opci贸n generar谩 un fichero (.sas-project.config) donde se almacenar谩 dicha informaci贸n de configuraci贸n

3.1.2 Inicializaci贸n del monorepo

foo@bar:~$ sas-cli monorepo:init
  • Inicializa el proyecto creando los links necesarios con los componentes existentes.

3.1.3 Acciones del monorepo

Una vez creado el monorepo se proporciona los siguientes scripts:

Generaci贸n de un distribuible

Esta opci贸n es la que ejecutar谩 el ALM del SAS por defecto en la entrega del proyecto. Incluye los transpilados (.js), los types (d.ts) y los mappers (.js.map)

foo@bar:~$ npm run build
Generaci贸n del proyecto para entornos de desarrollo

Opci贸n ideal para la versi贸n de desarrollo y al incluir un nuevo elemento en el proyecto (ej. un nuevo componente). Excluye los types de la carpeta de dist permitiendo hacer un hot-reload.

foo@bar:~$ npm run build:dev
Limpieza y generaci贸n del proyecto de entornos de desarrollo

Opci贸n ideal para cuando se quiera realizar una reconfiguraci贸n del proyecto en desarrollo. Se recomienda su ejecuci贸n antes de hacer el entregable para asegurarse que no hay ning煤n problema con una construcci贸n limpia (como se realizar谩 en el ALM del SAS)

foo@bar:~$ npm run build:clean:dev
Lanzar storybook del monorepo

Si se quiere consultar el cat谩logo de componentes desarrollado en el proyecto, se debe ejecutar:

foo@bar:~$ npm run storybook

Si se quiere generar un distributable para desplegar en un servidor de est谩ticos (nginx, apache), ejecutar:

foo@bar:~$ npm run storybook:build

Para m谩s detalle sobre el storybook revisar esta secci贸n

Ejecutar Test del monorepo

Si se quieren lanzar los test con su an谩lisis de cobertura de los test realizados para todo el cat谩logo de componentes desarrollado en el proyecto se debe ejecutar:

foo@bar:~$ npm run test:dev

Para m谩s detalle sobre el testing revisar esta secci贸n

Generaci贸n del proyecto con la instalaci贸n y transpilaci贸n en modo debug

Opci贸n para cuando se necesita informaci贸n m谩s detallada tanto en la compilaci贸n como en la transpilaci贸n

foo@bar:~$ npm run build:monorepo:debug
Cambio de versi贸n

Para facilitar el cambio de las versiones de todos los componentes del proyecto, y mantener la coherencia del versionado, se proporcionan dos scripts de npm (uno para windows y otro para linux) para ejecutar

  • LINUX

foo@bar:~$ npm run version:set:linux --new_version=1.0.6

  • WINDOWS

foo@bar:~$ npm run version:set:windows --new_version=1.0.6

3.2 Aplicaci贸n

El proyecto est谩 configurado para ser ejecutado a partir de la versi贸n 7.X de npm.

3.2.1 Generaci贸n de la app

La estructura de la aplicaci贸n generada mediante este CLI, siguen las directrices marcadas por el 谩rea de arquitectura de la STIC. La base tecnol贸gica es Lit (2.X) y TypeScript (4.x)

foo@bar:~$ sas-cli app:create
  • Este comando crear谩 un proyecto de tipo aplicaci贸n sobre una carpeta que no contenga un proyecto creado con anterioridad.
  • Se crear谩 la estructura esqueleto del proyecto
  • Se pedir谩 informaci贸n b谩sica para la construcci贸n de la aplicaci贸n
  • Se generar谩n los ficheros con la informaci贸n recopilada

Esta opci贸n generar谩 un fichero (.sas-app.config) donde se almacenar谩 dicha informaci贸n de configuraci贸n

3.2.2 Construir la app

Para construir la app hay que a帽adir al package.json del proyecto, en la secci贸n script, lo siguiente, substituyendo <nombre_app> por su valor (app-<area_desarrollo>-<nombre_app>)

foo@bar:~$ npm run start:build

3.2.3 Lanzar la app

foo@bar:~$ npm run start
Notas t茅cnicas

  • Para m谩s informaci贸n sobre el servidor de desarrollo de la aplicaci贸n propuesto revisar esta secci贸n

  • Si se quiere que la app cargue el theme:

    • A帽adir la dependencia del theme correspondiente al package.json del componente

    • Cargar en el index.html. Se recomienda revisar la propuesta hecha por la plantilla de la aplicaci贸n. Esta plantilla est谩 basada en la forma de implementar el theme de la stic.

  • Polyfills. En caso de que la aplicaci贸n deba ser compatible con IE11 se cargar谩n los polyfills necesarios en el index.html de la aplicaci贸n

3.2.4 Limpiar la app

Limpieza de todos los elementos generados durante la construcci贸n de la aplicaci贸n (out-ts, dist,back-up y coverage )

foo@bar:~$ sas-cli app:clean

Limpieza completa de todos los elementos generados durante la construcci贸n e instalaci贸n de la aplicaci贸n (temporales, node_modules)

foo@bar:~$ sas-cli app:clean -a

4. Componentes

En esta secci贸n se van a abordar los dos tipos de proyectos que actualmente se proporcionan por sas-cli, monorepo y aplicaci贸n

4.1 WebComponent

Esta secci贸n abordar谩 las acciones que se pueden realizar sobre los componentes de tipo Web.

4.1.1 Generaci贸n de WebComponents

La estructura de los componentes generados mediante este CLI, siguen las directrices marcadas por el 谩rea de arquitectura de la STIC. La base tecnol贸gica es Lit (2.X) y TypeScript (4.x).

Se generar谩 un componente con la siguiente estructura en su nombre wc-<area_desarrollo>-<nombre_componente>.

foo@bar:~$ sas-cli wc:create <nombre_componente>

El componente se crear谩 en la carpeta packages (la determinada para almacenar el cat谩logo de componentes reutilizables).

Despu茅s de la creaci贸n de los componentes necesarios, para la correcta configuraci贸n del monorepo, se recomienda la ejecuci贸n del comando.

foo@bar:~$ npm run build:dev

4.1.2 Lanzar una demo del WebComponent

Si se quiere montar una prueba de concepto de alg煤n componente se puede hacer uso de la carpeta demo.

Para lanzarla hay que a帽adir al package.json del proyecto, en la secci贸n script, lo siguiente, sustituyendo <nombre_componente> por su valor (Wc-<area_desarrollo>-<nombre_componente>)

"start:<nombre_componente>": "concurrently --kill-others --names tsc,web-dev-server \"npm run tsc:dev:watch\" \"web-dev-server --app-index packages/<nombre_componente>demo/index.html --node-resolve --open --watch\""

Una vez a帽adido el script se debe ejecutar, sustituyendo <nombre_componente> por su valor (Wc-<area_desarrollo>-<nombre_componente>), con

foo@bar:~$ npm run start:<nombre_componente>
Notas t茅cnicas para arrancar una demo sobre web components

  • Para m谩s informaci贸n sobre el servidor de lanzamiento de la demo propuesto revisar esta secci贸n

  • Si se quiere que el componente cargue el theme durante la ejecuci贸n de la demo:

    • A帽adir la dependencia del theme correspondiente al package.json del componente

    • Cargar en el index.html. Se recomienda revisar la propuesta hecha por la plantilla de los componentes. Esta plantilla est谩 basada en la forma de implementar el theme de la stic.

4.2 Librer铆a

Esta secci贸n abordar谩 las acciones que se pueden realizar sobre los componentes de tipo Librer铆a.

4.2.1 Generaci贸n de Librer铆a

La estructura de los componentes generados mediante este CLI, siguen las directrices marcadas por el 谩rea de arquitectura de la STIC. La base tecnol贸gica es Lit (2.X) y TypeScript (4.x).

Se generar谩 una librer铆a con la siguiente estructura en su nombre lib-<area_desarrollo>-<nombre_componente>.

foo@bar:~$ sas-cli lib:create <nombre_componente>

El componente se crear谩 en la carpeta packages (la determinada para almacenar el cat谩logo de librer铆as reutilizables).

Despu茅s de la creaci贸n de los componentes necesarios, para la correcta configuraci贸n del monorepo, se recomienda la ejecuci贸n del comando.

foo@bar:~$ npm run build:dev

5. T茅cnico

5.1 Server

  • Por la t茅cnica utilizada para la construcci贸n del monorepo (a trav茅s de symlinks) la opci贸n que se elija deben tener en cuenta y activada la opci贸n preserveSymlinks

  • Los navegadores no son compatibles con "bare" modules. Para solventar esto hay dos formas:

    • Uso web-dev-server, que, entre otras cosas, permite la transpilaci贸n al vuelo y substituye para el navegador los "bare" modules por la carga de m贸dulos compatible para el navegador.
    • Uso de herramientas de transpilaci贸n y bundling como Webpack o rollup

    Nota: Por facilidad de configuraci贸n se propone y recomiendo el uso del web-dev-server

Configuraci贸n

  • El fichero web-dev-server.config.mjs es el que contiene la configuraci贸n m铆nima propuesta.

  • Para ampliar la configuraci贸n consultar la informaci贸n

5.2 Storybook

El proyecto en desarrollo se basa en el storybook de ModernWeb. Se ha elegido esta versi贸n customizada del storybook por ser m谩s ligera de cara al desarrollo. Este es un storybook basado en rollup y que limita algunas de las capacidades del storybook original.

Los componentes deben poder desplegarse en cualquiera de los dos storybook

Configuraci贸n

Las configuraciones aplicadas est谩n basadas en el storybook original para WebComponents. Dichas configuraciones se encuentran en la carpeta ra铆z_.storybook_.

Algunas de las configuraciones extras que se pueden aplicar:

  • Exclusi贸n de componentes: en el fichero main.js se pueden a帽adir al array la lista de componentes sin el wc-, tal y como se muestra en el ejemplo
const excludeWCList = [
  "stic-theme",
  "stic-button",
]
  • Carga del theming en el storybook: Si el theming de la aplicaci贸n se puede realizar de forma generalizada para todos los componentes en el fichero preview-head.html. El ejemplo muestra como se actuar铆a en caso de seguir la estructura del theming propuesto por la stic. Al crear un nuevo proyecto, se necesita descomentar el c贸digo y adaptarlo al theme del 谩rea o aplicaci贸n correspondiente
<script type="module">
    import { STICTheme } from '@sas/wc-stic-theme';
    new STICTheme().loadHeadStyles();
</script>

Por la t茅cnica utilizada para la construcci贸n del monorepo (a trav茅s de symlinks) la opci贸n que se elija debe tener en cuenta y activada la opci贸n preserveSymlinks.

Si se utiliza el storybook proporcionado por ModernWeb, se debe tener en cuenta que utiliza web-dev-server como servidor de arranque por lo que dicho servidor debe tener la configuraci贸n adecuada. Para m谩s informaci贸n revisar la secci贸n

5.3 Testing

Las plantillas del sas-cli en materia de testing est谩n adaptadas a los recursos y configuraci贸n proporcionados por ModernWeb. Es recomendable, pero no obligatorio, seguir el stack tecnol贸gico propuesto por ModernWeb. En caso de tener una propuesta alternativa se recomienda consultar con el departamento de arquitectura del sas

Cualquiera definici贸n o stack tecnol贸gico debe ser posible ejecutarlo dentro del ALM del SAS. Se recomienda validar la ejecuci贸n de pruebas en un entorno contenerizado.

Configuraci贸n

  • Por la t茅cnica utilizada para la construcci贸n del monorepo (a trav茅s de symlinks) la opci贸n que se elijan debe tener en cuenta y activada la opci贸n preserveSymlinks.

  • El fichero web-test-runner.config.mjs es el que contiene la configuraci贸n m铆nima propuesta.

  • Para ampliar la configuraci贸n consultar esta informaci贸n

6. Actualizaci贸n del proyecto

En esta secci贸n se describe una gu铆a b谩sica para actualizar el proyecto a la versi贸n actual del sas-cli.

6.1 Migraci贸n del proyecto con scaffolding a sas-cli 0.X.X

Hay que seguir los siguientes pasos para realizaci贸n de la migraci贸n:

Migraci贸n Monorepo

Se describen a continuaci贸n los pasos a dar para la migraci贸n del monorepo

Borrado de elementos del Monorepo
  • carpeta scaffolding
  • ficheros configure.sh, sas-cli.js y package-lock.json
  • Opcional: carpetas demo y playground

Web Component del Monorepo

Borrado de elementos del web component
  • en la ra铆z del componente ficheros tsconfig.json, web-dev-server.config.mjs y web-test-runner.config.mjs
  • en la ra铆z del componente un fichero con el siguiente patr贸n <wc-area-nombrecomponente.ts>. En caso de tener contenido se debe copiar al fichero index.ts localizado tambi茅n en la ra铆z del componente
  • la carpeta .storybook
  • el fichero .gitignore, .editorconfig
  • las devDependencies del package.json
  • Aquellos componentes que sean librer铆as (que no tienen componentes visuales), eliminar la carpeta stories y el fichero custom-element-json
Recomendaciones migraci贸n de web component

  • En caso de no necesitar crear ning煤n componente nuevo, se recomienda crear un ficticio que permita comprobar los cambios propuestos y adecuar los componentes actuales a dichos cambios.

  • Revisar el demo/index.html para asegurarse de que las importaciones y el c贸digo se ajusta a los cambios una vez realizada la migraci贸n. Compararlo con el fichero propuesto. Verificar la carga del theme bas谩ndose en la propuesta y modificarla acorde al theme creado para el 谩rea o aplicaci贸n correspondiente.

  • Revisar el c贸digo de las stories y adecuarlos a los cambios propuestos.

Migraci贸n de Lit 1.x a Lit 2.X
  • La plantilla est谩 construida sobre la base de Lit 2.X
  • Es recomendable, no indispensable, que antes de hacer la migraci贸n se actualicen los componentes (src, testing y story) a la versi贸n de Lit 2.x.
  • Gu铆a de actualizaci贸n.
Notas
  • Pueden convivir componentes en diferentes versiones de Lit, aunque no es lo m谩s recomendable.
  • Revisar, haciendo una b煤squeda, los import del proyecto. Puede ocurrir que se est茅 apuntando a alg煤n m贸dulo de Lit 1.x y generar alg煤n conflicto o error inesperado al compilarlo en el ALM o publicarlo en los entornos del SAS.

Aplicaci贸n del Monorepo

Borrado de elementos de la aplicaci贸n
  • La carpeta .storybook
  • El fichero custom_element.json y package-lock.json
Recomendaciones migraci贸n de la aplicaci贸n

  • En caso de disponer de una aplicaci贸n ya creada, se recomienda crear una ficticia que permita comprobar los cambios propuestos y adecuar los componentes actuales a dichos cambios.

  • Revisar el app/index.html para asegurarse de que las importaciones y el c贸digo se ajusta a los cambios una vez realizada la migraci贸n. Compararlo con el fichero propuesto.

  • Revisar la carga del theme bas谩ndose en la propuesta.

6.2 Actualizaci贸n a sas-cli

7. Lecciones aprendidas

  • Al construir el monorepo, si se genera un node modules en dentro de un componente esto significa que hay alguna versi贸n de alguno de las dependencias o devDependencies que no est谩 alineada. Es recomendable alinear las versiones para evitar posibles conflictos o errores inesperados

8. Diagrama de uso

Loading...

  • Sin etiquetas