how-i-build

how-i-build

Este sitio es el primer proyecto documentado con el propio How I Build: un template, y un registro de las decisiones tomadas para construirlo

2026En líneaPúblicoAutor único
Next.jsNext.jsTypeScriptTypeScriptBunBun

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 site siempre 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 suppressHydrationWarning en <html>
  • next/script no sirve aquí: difiere el contenido inline hasta después del primer pintado, que es exactamente lo que esta solución necesita evitar
  • aria-pressed solo 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

El blog se quedó aquí, en el mismo repositorio y con el mismo modelo de contenido que los casos de estudio: imports estáticos, un archivo por idioma y el mismo build revisando ambos. Empezó en v0.20.0 y se asentó en v0.26.0, con un índice, portadas, tags, un archivo mensual y búsqueda.

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/processo y /blog/tags/process son 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.

Referencias