Griddo CX es un package dentro del monorepo de Griddo (packages/griddo-cx) que se encarga de ofrecer herramientas para orquestar el render de una instancia utilizando la biblioteca de componentes, un framework SSG y los datos obtenidos de la API privada de Griddo.
CX está escrito como una biblioteca en TypeScript. **Los consumidores de la misma son el *Adapter, el framework SSG y una serie de scripts en TypeScript que viven en el propio package/griddo-cx y que son utilizados por infra, normalmente invocados mediante un npm run ...
*Para los casos del Adapter y los “scripts para infra”, estos utilizarán directamente el código Typescript de la biblioteca de CX. Para el caso del SSG, este utilizará el código bundlelizado disponible en @griddo/cx y griddo/cx/react
Como ejemplo aquí vemos un snippet dentro de Gatsby (actual framework SSG) importando un componente <GriddoIntegrations> que forma parte de la biblioteca de CX, en concreto del export de react.
// src/components/template.tsx
import { GriddoIntegrations } from "@griddo/cx/react";CX tiene dos exports separados: main y react.
-
main se exporta en
@griddo/cx. Es código que se ejecuta en un entorno nodejs. -
react se exporta en
@griddo-cx/react. Es código React :)
Ejemplo de import
// React import
import { GriddoIntegrations } from "@griddo/cx/react";
// Core import
import {
IS_COMPONENT_LIBRARY,
PROJECT_ALIASES,
resolveComponentsPath,
} from "@griddo/cx";El bundle del código TypeScript se genera con esbuild. Compilando el código a CommonJS junto con las definiciones de tipos.
Se puede ejecutar el bundle de todo CX con yarn run build desde packages/griddo-cx . Esto creará los distintos exports: node, react y también los scripts para infra: reset-render, build-complete y upload-search-content junto con los archivos de definición de tipos.
Este comando, yarn run build se ejecuta en el despliegue del monorepo, npm prepare, etc. No es necesario que manualmente hagamos un build para los despliegues.
CX tiene un archivo de configuración en el raíz del package griddo-cx/cx.config.js donde se establecen ciertos valores globales para todo el package.
Los siguientes puntos están incluidos en el archivo de configuración y deben ser leídos de este, evitando hardcodear o volver a calcularlos en el resto del código.
const config = {
proDomain: "pro-", // Prefijo para los dominios "pro"
griddoVersion, // Versión de griddo obtenida del package.json
buildReportFileName: "build-report.json", // Archivo de reporte de render
// función que resuelve la ruta absoluta a los placeholders
paths: (domain) => ({
__cache: path.join(CX_CACHE_DIR, domain || ""),
__components: COMPONENTS_DIR,
__cx: CX_ROOT_DIR,
__exports: path.join(EXPORTS_DIR, domain || ""),
__root: REPO_ROOT_DIR,
__ssg: SSG_DIR,
}),
};El contenido del archivo de configuración se leerá con la función getConfig() donde sea que necesitemos acceder a la misma.
Ejemplo
const config = getConfig()
const { proDomain, ... } = configEn los renders de Griddo se diferencia cuando el render es de un dominio de producción, esto es que el dominio interno empieza por pro- , por ejemplo pro-griddo
Este pro- se especifica directamente y una sola vez en el archivo de configuración.
Si es necesario obtener la versión de CX la podemos tomar directamente del archivo de configuración
Mediante el archivo de configuración se establecen unas rutas absolutas globales a todo CX e instancia (ya sea instancia interna del monorepo o la de un cliente) que nos ayudará a orquestar los artefactos durante los LifeCycles de un render. Un uso parecido a los __dirname o __filename de javascript CommonJS.
Rutas con el dominio actual concatenado
Ya que la mayoría de las veces el uso de estas rutas son durante el render de un dominio, la ruta incluirá el dominio para así hacer operaciones más fácilmente sin tener que estar adjuntándolo (concat) constantemente. Esto es así para los placeholders __exports y __cache . Para ello a paths() hay que pasarle el dominio como único argumento cuando obtengamos las rutas con config.paths()
Ejemplo
const { __exports, __cache } = getConfig().paths("mi-dominio");
console.log(__exports); // ...export/sites/**mi-dominio**
console.log(__cache); // ...griddo-cx/.cx-cache/**mi-dominio**Esta son las rutas existentes.
-
__cxLa ruta absoluta del package de CX -
__ssgLa ruta absoluta del SGG configurado -
__exportsLa ruta donde se aloja el render final -
__cacheLa ruta del caché de CX, donde se guardan artefactos entre renders -
__componentsLa ruta de la instancia. En el monorepo la degriddo-components -
__rootEl directorio raíz siempre, en el monorepo y en la instancia. (uso residual)
Ejemplo de uso real
import { getConfig } from "./utils/config";
// Sin dominio
const config = await getConfig();
const { __cx, __ssg } = config.paths();
const storeDir = path.join(__cx, "store");
const templateFile = path.join(__ssg, "src/components/template.tsx");
// Con dominio
const { __cache } = config.paths("pre-griddo");
console.log(__exports); // /griddo/packages/griddo-cx/.cx-cache/**pre-griddo**Los LifeCycles se utilizan dentro del contexto de un Adapter. Se usa a través de la función doLifeCycle que ejecuta un batch de funciones (actions) de forma secuencial. Informando por consola del inicio, fin y tiempo invertido en ejecutar todas las funciones del actions, manejando cualquier error en las mismas. En caso de error, es posible indicar un número de attempts que hará que se ejecute de nuevo el clico de vida las veces indicadas.
En CX existen estos LifeCycles: Prepare, Restore, Data, SSG, Relocation, Meta, Archive, Clean, HealthCheck y uno de __DEBUG__ internamente son iguales (usan doLifeCycle) y se utilizan estos distintos nombres para identificarlos dentro de un render, poner distintos attempts, etc..
Ejemplo:
await doLifeCycle({
name: "SSG",
attempts: 2, // intentará hacer **todos** las actions dos veces si hay un error en alguno de ellos
actions: [func1, func2, func3],
});Como hemos visto uno de los consumidores de CX son scripts “individuales” que están alojados en griddo-cx/src/scripts Estos scripts son siempre llamados por infra, o por el desarrollador cuando se hacen render en local.
CX es una biblioteca por lo tanto no tiene nada ejecutable como tal, no hay un entry point desde el punto de vista del package. En el package.json existe un binario griddo-cx que usa infra/API para ejecutar un render, este binario apunta a griddo-cx/start-rener.js con el que se desencadena el proceso de publicación.
Lo ejecuta infra mediante yarn run reset-render . Este resetea la API en caso de que un render salga mal. De esa manera la API al ser preguntada volverá a comunicar que hay un render pendiente y comenzará con ello de nuevo.
Si no se llamase correctamente al script, la API se quedaría esperando a que finalice el render “eternamente”. Hay un time-out de X horas.
Lo ejecuta infra mediante yarn run build-complete cuando un render acaba de manera exitosa y el contenido ha sido subido al servidor, es decir, cuando se ha completado una publicación. Este script envía a la API información del render y le comunica que este ha terminado y que está disponible para un rrnuevo render.
Lo ejecuta infra mediante yarn run upload-search-content cuando un render ha acabado o con cierta frecuencia. Sube contenido de los estáticos del render a un endpoint para el uso en buscadores.
Un Adapter es una función que se ejecuta en el script start-render.js que es el que se triggea cuando API avisa de un nuevo render. Los Adapters están en el directorio griddo-cx/exporter/adapters
El Adapter es el responsable de manejar el proceso de render mediante las utilidades de la biblioteca. En el proceso puede hacer lo que estime oportuno salvando ciertas obligaciones para que un render sea Griddo-compliant.
💡 Los Adapters utilizarán el código TypeScript de CX, no el bundlelizado. Ya que el propio adapter también se bundleliza.Exports
Dist
Dejar una carpeta con los archivos estáticos finales en el path __exports , que es una carpeta exports/sites/<dominio>/dist donde dominio es cada dominio de la instancia de Griddo. Una vez terminado el render, infra tomará esa carpeta y la subirá. Infra la sube mediante sincronización por lo que siempre tiene que estar actualizada y con la totalidad de los datos. Si en la carpeta destino hay un archivo que no existe en la carpeta fuente exports/sites/<dominio>/dist se borrará.
Assets
Igualmente dejar una carpeta con los “assets” de javascript. Esto es verdad en el mundo Gatsby no sabremos qué pasará con otros frameworks.
Caches
El adapter deberá manejar manualmente la caché de Griddo utilizando las funciones moveDirsSync, copyDirsSync y removeDirsSync.
La caché de Griddo son dos directorios que se crean en griddo-cx por cada render y dominio: store y apiCache . Para facilitar el trabajo CX cuenta con placeholders para las rutas, en este caso __cache que haría referencia griddo-cx/.cx-cache/<domain>
griddo-cx
|-.cx-cache
|- store
|- apiCache¿Cómo se maneja la caché? ¿Qué hago con ella?
Los datos de la caché se generan de forma automática en griddo-cxEl manejo se basa en restaurar (Restore), archivar (Arhive) o invalidar (Clean) los directorios de la caché, tanto store como apiCache
Restaurando la caché
Cuando se inicia un render debemos mover tanto store como apiCache que estarán dentro de griddo-cx/.rendrr-cache/<dominio> al raíz de CX griddo-cx para que el proceso de render haga uso de las mismas.
Archivando la caché
Cuando el render de un dominio termina correctamente, se deben mover las carpetas store y apiCache a la carpeta de caches griddo-cx/.cx-cache/<domain> para poder restaurarlas en un próximo render.
Invalidando la caché
Si un render ha dado error pueden quedarse en el raíz de CX las carpetas store y apiCache. Estas deben ser borradas antes de la nueva fase de restauración. De hecho probablemente no exista nada que restaurar porque el render dio error. En ese caso lo que ocurre es que efectivamente no hay nada que restaurar y habrá que descargarse de nuevo todos los datos.
A su vez, en cada despliegue que exista en la instancia también se borrarán ya que de alguna manera se alojan en lo que sería el node_modules de la instancia. Y se borrará CX enteramente.
…
…
…
No, los proyectos actuales de Griddo se apoyan en imágenes alojadas en remoto, en concreto en un servicio externo “DAM” propiedad de Secuoyas. Este servicio ofrece las transformaciones necesarias. Existen un componente de React en Griddo <GriddoImage> que las instancias pueden utilizar y que se integra con el “DAM”.
Algunas de las primeras instancias utilizan la misma estrategia con cloudinary, usando un componente de React proporcionado también por Griddo: <CloudinaryImage>