Programé una cosa divertida

Si, ni yo lo puedo creer

Sin Códigos es un espacio de reflexión sobre el mercado tecnológico y el impacto que la tecnología tiene en nuestras vidas. Lo escribe Bel Rey ✨ y sale una vez por semana ¡Suscribite y no te pierdas ninguna edición!

Hola internautas, lamento comunicar que esta semana no tuve tiempo de investigar para escribir. Las razones son múltiples y dramáticas: Trámites. Más trámites. Médicos. Substack que decidió romper mi dominio y quedé sin acceso al news por varios días.

Y además tuve que trabajar. A esta altura del año que no coordino dos palabras y quieren que trabaje. Por suerte esta vez me tocó hacer algo divertido. Así que por primera vez en mucho tiempo vamos a hacer algo que en este news no se hace: ver código.

Bienvenidos a la primera edición Con Código de Sin Códigos.

El problema

Antes de empezar es importante que les cuente que desde hace ya tiempo estoy dando una mano a los muchachos de Amplify con todo lo que es comunicación, diseño y documentación. Amplify es, a grandes rasgos, una pasarela de pago que recibe crypto y entrega fiat. La documentación es fundamental en este proyecto porque uno de los pilares de la integración es un SDK (Software developer kit) que otros programadores tienen que poder acceder y utilizar sin depender de que alguien del equipo les responda.

La documentación actual vive en Gitbook, esto le da algunos pros y contras

Pros ✔️

• Capacidad de editar archivos de markup online

• Publicar sin necesidad de un nuevo deploy

• Relativa facilidad para agregar nuevos colaboradores

Contras❌

• Pago por colaborador

• No respeta las convenciones del sistema de diseño

• Se complejiza mantener la documentación en más de un idioma.

Considerando que la cantidad de actualizaciones que tiene el contenido no son tantas en este caso en particular nos pareció que los pro no pudieron superar a las contras y decidimos encarar por otro camino.

La solución

Para plantear la solución me apalanqué en dos pilares, el primero solucionar la mayor cantidad de contras del proyecto original. La segunda era utilizar, dentro de lo posible, herramientas que ya sean parte de nuestro flujo de trabajo.

En Amplify tenemos otro proyecto que requiere actualizar contenido regularmente: el blog. Es un blog corporativo pensado para informar a posibles clientes y stakeholders y que se utiliza entre otras cosas para comunicar noticias regularmente a inversores.

Este blog está construido con NextJS y la API de Notion. Consume la información directamente desde una base de datos (un tipo de estructura en Notion similar a una tabla de Excel) y la muestra dentro de un contenedor MDX donde cada bloque de contenido es interpretado en su formato apto web.

El blog / la base de datos

Considerando que el equipo ya utiliza Notion me pareció ideal mantener el mismo flujo de trabajo: NextJS para renderizar, tablas para guardar el contenido. Pim pam pum.

La implementación

Para la implementación del proyecto investigué varias alternativas con NextJS, ya que todo el stack de Amplify web utiliza el mismo framework y decanté por un proyecto existente que se llama Nextra y me daba algo muy parecido a lo que yo quería: Una página de documentación con navegación lateral autogenerada según el contenido y la capacidad de mantener varios idiomas en paralelo.

El problema es que Nextra está programado para armar su estructura alrededor de archivos MDX locales, lo que rompe mi idea original de traer los datos de forma dinámica desde Notion.

Probé armar una integración entre Nextra y Notion que funcionó para mostrar MDX remotos dentro de Nextra, pero en el proceso descubrí que se volvía un problema generar la barra lateral, ya que si o si depende del sistema de archivos locales. Intenté generar una versión dinámica de la barra trayendo datos desde Notion… y funcionó… pero me empezó a molestar la cantidad de llamadas a un API externa que tenía que hacer para mostrar un simple sitio de documentación.

Básicamente cada vez que navegabamos a un link pasaba esto:

Que a nivel performance me parece un delirio innecesario.

Además que me generaba otra consideración importante: ¿Qué pasa con los límites de la API de Notion? ¿Qué pasa si mi sitio escala en usuarios? ¿Me cobran millones de dólares? ¿Se cae y deja de estar disponible? Ninguno de esos escenarios me parecía esperanzador.

La idea de tener archivos locales era cada vez más tentadora, pero se desviaba de la intención original de mantener las mismas herramientas. Además implica que solamente personas con acceso al código del proyecto puedan agregar documentación o que dependan de alguien que tenga acceso para poder subirlo. Se pierde el dinamismo de poder hacer todo en una plataforma que está pensada para escribir contenido.

Pensando soluciones me encontré con un repositorio público de un programador que recorrió el mismo camino que yo. No estaba documentado porque era un proyecto personal pero leyendo el código entendí su propuesta. Era un intermedio: escribía el contenido en Notion y lo copiaba de forma dinámica a la estructura de archivos de Nextra.

Me encantó. Esto abría varias posibilidades, por ejemplo que si por algún motivo se cae la integracióncon la API los estáticos siguen en el servidor y el sitio de documentación funciona. También implica muchas menos llamadas y la capacidad de utilizar las funcionalidades nativas de Nextra para armado de i18n y menues. No más scripts recursivos custom.

El flujo inicial del proyecto, que solo ocurre cuando hay una nueva build o un deploy a producción quedó así:

Y la interacción entre el usuario y el frontend:

Bien simple, cómo si fuera un sitio estático de fines de 2003. Sin APIs, sin llamadas en el cliente, sin complicaciones.

El proyecto todavía no está publicado, me falta limar asperezas y terminar de migrar contenido, pero quedé muy feliz con el resultado. Aguante la web estática.

Les dejo el script pre-build para chusmear si tienen ganas. Cuando termine de trabajar en este proyecto posiblemente libere un template para que puedan usar sin culpa.

¡Feliz viernes y nos vemos la semana próxima!

---

Hola, seamos amigos ☕️

• ¿Qué te pareció esta edición? Contame en los comentarios:

• Si te gusta lo que escribo podés recomendarlo con quien quieras <3

• Y si querés apoyar la escritura independiente Regalame un Cafecito o sumate a un plan mensual

¡Gracias por leerme!