Algunos de los proyectos en los que trabajo son de clientes. Otros tienen código que no tiene sentido publicar porque es parte del propio producto. En casi todos, lo que hice queda cerrado, y desde afuera solo queda una landing page o una línea en un CV. Lo que quiero guardar aquí es lo que nada de eso muestra: por qué tomé cada decisión, con qué problemas me encontré y qué consideré antes de elegir un camino.
Por eso construí How I Build. El primer proyecto que decidí documentar fue el propio sitio, porque quería probar la idea en algo que pudiera mostrar completo, incluido el código. El repositorio contiene el template que le da estructura al sitio junto con el contenido que escribo sobre los proyectos. Mantuve las dos partes separadas para que el template nunca necesite saber nada sobre mí ni sobre el contenido publicado en él. La mayoría de las decisiones de abajo parten de esa separación.
Un repositorio, dos ramas
El template y el contenido del sitio tienen que evolucionar juntos, pero no deberían mezclarse. Quería usar el mismo repositorio para desarrollar el template sin poner mi contenido dentro de él y, al mismo tiempo, mantener el sitio que publico aquí al día con esos cambios.
Decisión
Mantuve un repositorio y dos ramas. main contiene el template y site
contiene el contenido. Un workflow hace merge de main → site en cada push,
manteniendo el sitio al día sin repetir los cambios a mano.
Compromisos
- Cada cambio del template pasa por dos merges antes de llegar a producción.
- Los archivos que ambas ramas necesitan cambiar, como la configuración y el índice de contenido, pueden entrar en conflicto. En esos casos
sitesiempre gana. - Quien clona el template también se lleva una segunda rama que tal vez no necesite. Por eso el workflow simplemente no hace nada cuando esa rama no existe.
El idioma por defecto no tiene prefijo
Quería que el inglés fuera el idioma por defecto del sitio, pero sin poner /en
en cada URL. Al mismo tiempo, el portugués tenía que seguir disponible en una
ruta propia. Eso dejaba dos alternativas: poner prefijo a ambos idiomas, o no
distinguirlos en la URL. La primera descartaba usar / para el inglés; la
segunda creaba problemas de indexación, de compartir enlaces y de generación de
páginas estáticas.
Decisión
El inglés responde en /projects, el portugués en /pt/projects. /en/*
redirige a la ruta sin prefijo, así que cada página tiene exactamente una
dirección. Publicado en v0.4.0.
Compromisos
- El proxy es más complejo que un redirect simple: rewrite, redirect canónico y lectura de la preferencia solo en la raíz
- Construir un enlace necesita un helper en lugar de concatenar un string
- La preferencia del lector solo se aplica en
/. Un enlace profundo compartido se abre en el idioma en que se compartió; eso es deliberado, pero puede sorprender
El tema se aplica antes de que la página se pinte
El tema tenía que ser el correcto antes del primer pintado de la página. Leer la cookie en el servidor parecía la solución natural, pero creaba dos problemas: la primera visita no tiene cookie, así que un lector que prefiere el tema oscuro podía ver un destello blanco, y leer la cookie además sacaba las rutas del renderizado estático.
Decisión
Un script síncrono en <head>, antes de que se renderice cualquier cosa. Sin cookie en el servidor y sin estado de React. La clase en <html> ya es la correcta antes de la hidratación, así que el control no necesita empezar con un estado y corregirlo después. Publicado en v0.5.0 y ampliado a tres opciones en v0.8.0.
Compromisos
- Un script inline en el documento, más
suppressHydrationWarningen<html> next/scriptno sirve aquí: difiere el contenido inline hasta después del primer pintado, que es exactamente lo que esta solución necesita evitararia-pressedsolo queda correcto durante la hidratación, porque el servidor realmente no conoce la preferencia del lector
Sin banner de cookies
El sitio guarda dos cosas: una cookie con el idioma elegido y una entrada en localStorage con el tema elegido. Ambas se escriben solo cuando el lector usa el control que las define.
Eso me llevó a una pregunta simple: ¿qué estaría rechazando exactamente el lector? Si elige portugués, por ejemplo, necesito guardar esa elección para recordarla después. Si rechaza ese almacenamiento, la función que acaba de pedir deja de funcionar.
Decisión
Sin banner. En su lugar, una página de privacidad: qué se guarda, por qué y cómo borrarlo. Publicado en v0.16.0.
Compromisos
- Agregar analytics más adelante significa agregar el banner y reescribir esa página
- Alguien que espera un banner puede leer su ausencia como un descuido y no como una decisión
Un workflow que nunca corrió
El workflow que hace merge de main en site se escribió para dispararse con release: published. No corrió ni una vez. No falló — nunca arrancó. No hubo ninguna ejecución en rojo ni ninguna notificación; la rama de contenido simplemente se quedó atrás.
GitHub no inicia workflows a partir de eventos creados por GITHUB_TOKEN, y release-please publica los releases usando ese token.
Lo incómodo es que yo ya había usado esta misma propiedad a propósito, un issue antes, para evitar que el workflow de release entrara en bucle con su propio commit. El mecanismo me era conocido; simplemente lo apliqué al revés.
Decisión
Disparar con push a main, que es una acción humana. Corregido en v0.17.1.
Compromisos
- La sincronización ahora corre en cada merge, no en cada release. Eso pasa más seguido de lo que se diseñó originalmente, pero mantiene las ramas más cerca.
- El propio commit de release-please sigue sin disparar el workflow, así que un cambio de versión espera al siguiente merge.
El blog vive dentro del mismo sitio
No todo lo que quiero escribir es un caso de estudio. Hay opiniones, hay algo nuevo que probé y quise registrar, y hay notas cortas que no pueden cargar todo un registro de decisiones. Quería un lugar propio para eso, y la salida obvia era abrir un blog aparte en alguna plataforma lista, dejando este sitio solo para los proyectos.
Decisión
Compromisos
- Un post solo llega al sitio cuando existe en portugués y en inglés. El build rechaza un texto que tiene un solo idioma, lo que protege los casos de estudio y genera fricción justo en la nota corta.
- Los tags se escriben por idioma, así que
/blog/tags/processoy/blog/tags/processson páginas distintas. Cambiar de idioma solo encuentra la contraparte porque está en el mismo índice en ambos archivos, y es el build el que mantiene eso cierto. - Siete releases seguidos fueron para el blog antes de que tuviera algún texto mío. Lo que sostiene esta decisión de aquí en adelante es escribir, y esa parte no depende del código.