TL;DR: FastAPI + HTMX + Alpine.js + Jinja2 + CSS puro produce aplicaciones web de producción sin herramientas de compilación, sin node_modules/ y con puntuaciones perfectas en Lighthouse. Esta guía cubre el sistema completo, desde la arquitectura hasta el despliegue, usando blakecrosley.com como referencia de producción que sirve más de 100 artículos de blog, componentes interactivos de JavaScript, múltiples guías exhaustivas y traducciones en nueve idiomas, todo sin un solo bundler, compilador o transpilador.¹

El stack moderno de desarrollo web asume que necesitas React, webpack, TypeScript y un pipeline de compilación. Para una amplia categoría de aplicaciones —sitios orientados a contenido, herramientas internas, aplicaciones CRUD, portafolios, plataformas de documentación— esa suposición es incorrecta. El stack descrito en esta guía elimina por completo la cadena de herramientas de compilación del frontend, y aun así produce sitios que obtienen 100/100/100/100 en Lighthouse.²

Esto no es una defensa ideológica. Es una medición. La arquitectura aquí descrita funciona en producción, sirve a usuarios reales en diez idiomas y los números son verificables.

Conclusiones Clave

• El HTML renderizado en el servidor elimina tres categorías enteras de problemas: gestión de estado en el cliente, límites de serialización de JSON y desajustes de hidratación. HTMX convierte las respuestas del servidor en la salida final — sin paso de renderizado en el cliente.
• Cero herramientas de compilación significa cero fallos de compilación. Sin conflictos de dependencias entre pares con npm install, sin errores del compilador de TypeScript en archivos que no tocaste, sin PRs de Dependabot por dependencias transitivas que nunca importaste. El pipeline de despliegue es git push.
• Alpine.js maneja el estado exclusivo del cliente que HTMX no puede. Menús desplegables, modales, toggles de navegación móvil y cualquier estado de interfaz que existe puramente en el navegador le corresponden a Alpine.js. El límite es claro: si el estado necesita el servidor, usa HTMX. Si no, usa Alpine.js.
• CSS puro con propiedades personalizadas reemplaza a Sass y Tailwind. Las propiedades personalizadas de CSS se propagan en cascada, se heredan y responden a media queries en tiempo de ejecución. Las variables de preprocesador se compilan a valores estáticos y desaparecen. El navegador lee las propiedades personalizadas directamente — sin paso de compilación.
• Este enfoque tiene límites claros. No es adecuado para equipos grandes que comparten interfaces de componentes, productos SaaS con estado complejo en el cliente ni aplicaciones que dependen de bibliotecas del ecosistema npm. El marco de decisión en la Sección 15 identifica ese límite con precisión.
• blakecrosley.com es la prueba. Los patrones centrales de esta guía (HTMX, Alpine.js, Jinja2, CSS puro) funcionan en producción en blakecrosley.com. Las secciones de Bootstrap y SQLAlchemy cubren patrones estándar del stack que no se usan en este sitio específico. Cada afirmación tiene una ruta de archivo, un bloque de configuración o una auditoría de Lighthouse que puedes verificar en PageSpeed Insights.²

Cómo Usar Esta Guía

Esta es una referencia integral. Comienza donde se ajuste tu nivel de experiencia:

Usa Ctrl+F / Cmd+F para buscar patrones o atributos específicos. La Tarjeta de Referencia Rápida al final proporciona un resumen escaneable.

La Tesis No-Build

La tesis es acotada y específica: para sitios orientados a contenido con un desarrollador individual o un equipo pequeño, las herramientas de compilación resuelven problemas que no tienes mientras crean problemas que sí.

Estas son las métricas reales de blakecrosley.com:

Los 15 paquetes Python incluyen FastAPI, Jinja2, Pydantic, uvicorn, nh3 y 10 más. Ninguno es una herramienta de compilación. Ninguno es un compilador. Ninguno es un bundler.⁵

Lo Que Sacrificas

La honestidad exige enumerar los costos reales:

Sin TypeScript. Cada archivo .js es JavaScript puro. Los errores de tipo se detectan mediante pruebas y análisis de código, no con un compilador. Esto funciona para un desarrollador individual. No funcionaría para un equipo de 10 personas compartiendo interfaces de componentes.

Sin Hot Module Replacement. Los cambios en CSS requieren actualizar el navegador manualmente. El hx-boost de HTMX hace que la navegación sea lo suficientemente rápida como para que las actualizaciones completas sean tolerables, pero en ciclos de iteración visual ajustados, HMR ahorra tiempo.

Sin Tree Shaking. Cada byte de JavaScript que escribes se envía al navegador. La restricción impone disciplina: archivos pequeños y enfocados en lugar de módulos de utilidades grandes.

Sin bibliotecas de componentes npm. Sin Radix, sin shadcn/ui, sin Headless UI. Cada elemento interactivo se construye a mano o usa los componentes integrados de Bootstrap 5.

Sin tokens de Design System desde npm. El sistema de diseño vive en propiedades personalizadas de CSS. No se puede importar como paquete en otro proyecto.

Estas concesiones son aceptables para un sitio orientado a contenido con uno a tres desarrolladores. Serían inaceptables para un producto SaaS con un equipo de ingeniería de 15 personas. La Sección 15 proporciona el marco de decisión.

Lo Que Ganas

Cero fallos de compilación. Ningún npm install puede fallar por conflictos de dependencias entre pares. Ningún next build puede fallar por un error de TypeScript en un archivo que no tocaste.⁶

Depuración con View Source. El JavaScript que se ejecuta en el navegador es el JavaScript que escribiste. Sin necesidad de source maps.

Inicio local instantáneo. uvicorn app.main:app --reload arranca en menos de 2 segundos.

Cascada de peticiones concreta. Una primera visita carga: un documento HTML (~15KB gzipped), un archivo CSS (~8KB), HTMX (~14KB, en caché), Alpine.js (~14KB, en caché) y el JS interactivo de la página (~4-8KB). Total: 45-60KB en la primera visita.¹

Frontend a prueba de futuro. El código del lado del cliente usa HTML, CSS y JavaScript — estándares que han mantenido compatibilidad retroactiva durante 30 años.⁷ Sin migraciones de Webpack 4 → 5, sin deprecación de Create React App, sin migración al App Router de Next.js.

Comparación de Stacks

Cómo se compara el stack no-build con las alternativas comunes en dimensiones medibles:

Astro y 11ty son los competidores más cercanos para sitios de contenido. Ambos producen excelente salida estática, pero requieren un paso de compilación y un toolchain de JavaScript. El stack FastAPI+HTMX sacrifica el rendimiento de sitio estático a cambio de interactividad del lado del servidor (filtrado por categorías, manejo de formularios, búsqueda en tiempo real) sin agregar un paso de compilación. Si tu sitio es puramente estático sin interacciones con el servidor, Astro o 11ty pueden ser la mejor opción.

Descripción general de la arquitectura

Flujo de solicitudes

Cada solicitud sigue un único camino a través de cuatro capas:

Browser                FastAPI                Jinja2              HTMX/Alpine
  |                      |                     |                     |
  |--- GET /about ------>|                     |                     |
  |                      |-- render template ->|                     |
  |                      |                     |-- base.html ------->|
  |                      |                     |   + about.html      |
  |                      |<-- full HTML -------|                     |
  |<--- HTML response ---|                     |                     |
  |                                                                  |
  |--- hx-get /search ------------------------------------------------>|
  |                      |<-- HTMX request ----|                     |
  |                      |-- render partial -->|                     |
  |                      |                     |-- _results.html     |
  |                      |<-- HTML fragment ---|                     |
  |<--- HTML fragment ---|                     |                     |
  |--- DOM swap -------------------------------------------------------->|

Las cargas de página completas devuelven documentos HTML completos (plantilla base + plantilla de página). Las solicitudes HTMX devuelven fragmentos HTML (parciales). El servidor decide qué renderizar según el tipo de solicitud. Alpine.js gestiona el estado del lado del cliente que nunca llega al servidor.

Roles de los componentes

Estructura del proyecto

app/
├── main.py              # FastAPI app, middleware, templates
├── config.py            # Pydantic settings management
├── routes/
│   ├── pages.py         # Page routes (HTML responses)
│   └── api.py           # API routes (JSON/HTML fragment responses)
├── content.py           # Markdown loading, blog post parsing
├── security/
│   ├── headers.py       # CSP, HSTS, security headers middleware
│   ├── csrf.py          # HMAC-signed CSRF tokens
│   ├── rate_limit.py    # 3-tier rate limiting
│   └── logging.py       # Security event logging
├── i18n/
│   ├── config.py        # Supported locales, mappings
│   ├── middleware.py     # URL-based locale detection
│   ├── jinja.py         # Translation functions for templates
│   └── d1_client.py     # Cloudflare D1 translation storage
├── cache_assets.py      # Content-hash asset versioning
└── templates/
    ├── base.html         # Base layout with Alpine.js state
    ├── components/       # Reusable partials (_language_switcher.html, etc.)
    └── pages/            # Page templates (home.html, about.html, etc.)

content/
├── blog/                # Markdown blog posts with YAML frontmatter
└── guides/              # Multi-section guide markdown

static/
├── css/                 # Plain CSS (no preprocessors)
├── js/                  # Vanilla JavaScript (no bundlers)
│   └── vendor/          # Self-hosted HTMX, Alpine.js
└── images/              # Optimized images with WebP srcset

La estructura sigue un único principio: cada directorio contiene un solo tipo de cosa. Las rutas viven en routes/. Las plantillas viven en templates/. Los archivos estáticos viven en static/. Ningún paso de compilación transforma uno en otro.

Contraste con la arquitectura SPA

En un proyecto React + Next.js, la estructura equivalente incluiría:

src/
├── components/       # React components (JSX)
├── pages/            # Route handlers (also JSX)
├── api/              # API routes (also in pages/)
├── hooks/            # Custom React hooks
├── context/          # React context providers
├── lib/              # Utility functions
├── styles/           # CSS modules or Tailwind config
└── types/            # TypeScript type definitions

# Plus build configuration
next.config.js
tsconfig.json
postcss.config.js
tailwind.config.js
eslint.config.js
package.json
package-lock.json
node_modules/         # 187+ MB of dependencies

La arquitectura SPA requiere coordinación en tiempo de compilación entre estos directorios. TypeScript compila .tsx a JavaScript. PostCSS procesa las directivas de Tailwind y las convierte en CSS. Webpack (o Turbopack) empaqueta la salida en fragmentos. Cada paso puede fallar de manera independiente.

La arquitectura sin compilación no requiere coordinación. La plantilla referencia un archivo CSS. El archivo CSS existe en static/css/. El navegador lo carga directamente. Si renombras un archivo, la referencia en la plantilla se rompe en tiempo de ejecución, no en tiempo de compilación. Esto traslada los errores del tiempo de compilación al tiempo de ejecución, lo cual es una compensación genuina. Para un desarrollador individual ejecutando uvicorn --reload durante el desarrollo, los errores en tiempo de ejecución aparecen inmediatamente en el navegador. Para un equipo grande, los errores en tiempo de compilación detectados por TypeScript previenen una categoría de bugs que los errores en tiempo de ejecución no pueden.

Patrones de FastAPI

Configuración de la aplicación

La aplicación se inicializa en main.py con un orden explícito de middleware:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates
from starlette.middleware.gzip import GZipMiddleware

app = FastAPI(
    title="Blake Crosley",
    docs_url=None,     # Disable docs in production
    redoc_url=None,
    openapi_url=None,  # Prevent /openapi.json exposure
)

# Middleware order matters: last added = first executed
app.add_middleware(SecurityHeadersMiddleware)
app.add_middleware(GZipMiddleware, minimum_size=500)
app.add_middleware(LocaleMiddleware)
app.add_middleware(RateLimitMiddleware)
app.add_middleware(SecurityLogMiddleware, site_name="blakecrosley.com")

# Static files
app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")

# Templates
templates = Jinja2Templates(directory=TEMPLATES_DIR)

Tres decisiones de diseño son importantes aquí. Primero, docs_url=None y openapi_url=None desactivan los endpoints de documentación automática de API. Un sitio de contenido público no necesita exponer /docs ni /openapi.json a internet.⁸ Segundo, el orden del middleware importa: el registro de seguridad se ejecuta primero (se agrega último) para capturar cada solicitud, incluyendo las rechazadas por el limitador de tasa. Tercero, GZipMiddleware comprime todas las respuestas superiores a 500 bytes, lo que normalmente reduce el tamaño de transferencia de HTML entre un 70-80%.

Enrutamiento

Las rutas se separan en dos categorías: las rutas de página devuelven documentos HTML completos, y las rutas API devuelven JSON o fragmentos HTML.

# routes/pages.py — full HTML responses
from fastapi import APIRouter, Request

router = APIRouter()

@router.get("/about")
async def about(request: Request):
    templates = request.app.state.templates
    return templates.TemplateResponse("pages/about.html", {
        "request": request,
        "page_title": "About — Blake Crosley",
        "page_description": "Designer, developer, dad.",
    })

# routes/api.py — JSON or HTML fragment responses
@router.get("/api/quiz/{quiz_id}/step")
async def quiz_step(request: Request, quiz_id: str, answers: str = ""):
    # Parse answers, compute next question or result
    question = get_next_question(quiz_id, answers)
    templates = request.app.state.templates
    return templates.TemplateResponse("components/_quiz_step.html", {
        "request": request,
        "question": question,
        "answers": answers,
        "step": len(answers.split(",")) if answers else 0,
    })

La distinción importa para HTMX. Las rutas de página completa devuelven documentos que extienden base.html. Las rutas API devuelven fragmentos HTML que HTMX intercambia en elementos DOM existentes. El mismo motor de plantillas Jinja2 renderiza ambos, sin necesidad de una capa API separada.

Inyección de dependencias

El sistema Depends() de FastAPI proporciona una separación limpia entre los manejadores de rutas y la lógica compartida:

from fastapi import Depends, Request

def get_templates(request: Request):
    """Get templates from app state."""
    return request.app.state.templates

def get_current_locale(request: Request) -> str:
    """Get locale from middleware-set request state."""
    return getattr(request.state, "locale", "en")

@router.get("/blog/{slug}")
async def blog_post(
    request: Request,
    slug: str,
    templates=Depends(get_templates),
    locale: str = Depends(get_current_locale),
):
    post = load_post_by_slug(slug)
    if not post:
        raise HTTPException(404, "Post not found")
    return templates.TemplateResponse("pages/blog/post.html", {
        "request": request,
        "post": post,
        "locale": locale,
    })

Las dependencias se componen entre sí. Una dependencia get_db puede depender de get_current_locale, que a su vez depende del request. FastAPI resuelve la cadena automáticamente.

Configuración con Pydantic

La configuración utiliza BaseSettings de Pydantic con precedencia de variables de entorno:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    D1_WORKER_URL: str = ""
    D1_AUTH_SECRET: str = ""
    CLOUDFLARE_ACCOUNT_ID: str = ""
    CLOUDFLARE_API_TOKEN: str = ""
    ANALYTICS_PASSKEY: str = ""

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

Las variables de entorno tienen prioridad sobre los valores del archivo .env. En producción (Railway), los secretos se configuran como variables de entorno. En local, un archivo .env proporciona valores por defecto. La clase Settings valida los tipos al iniciar; un campo requerido faltante falla inmediatamente en lugar de fallar en tiempo de ejecución.

Patrones async

Las rutas de FastAPI son async por defecto. Para operaciones de entrada/salida (consultas a base de datos, solicitudes HTTP, lectura de archivos), async evita bloquear el event loop:

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Load translations into memory cache at startup
    async with httpx.AsyncClient() as client:
        for locale in SUPPORTED_LOCALES:
            resp = await client.post(f"{D1_URL}/query", ...)
            TRANSLATIONS[locale] = resp.json()["results"]
    yield
    # Cleanup on shutdown (if needed)

app = FastAPI(lifespan=lifespan)

Las operaciones de uso intensivo de CPU (renderizado de Markdown, extracción de CSS) pueden usar funciones síncronas. FastAPI las ejecuta en un pool de hilos automáticamente cuando el manejador de ruta no se declara como async:

# Sync function — FastAPI runs it in a thread pool
@router.get("/blog/{slug}")
def blog_post(slug: str):
    post = load_post_by_slug(slug)  # CPU-bound Markdown parsing
    return templates.TemplateResponse(...)

La regla es simple: si la función espera operaciones de entrada/salida, declárala como async. Si realiza trabajo de CPU, déjala síncrona. No mezcles await con llamadas bloqueantes en la misma función.⁹

Plantillas Jinja2

Herencia de plantillas

El sistema de herencia de Jinja2 reemplaza la composición de componentes de React con un modelo más simple. Una plantilla base define el esqueleto de la página. Las plantillas hijas rellenan bloques con nombre:

<!-- base.html — the skeleton -->
<!DOCTYPE html>
<html lang="{{ lang_attr() }}">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ page_title | default("Blake Crosley") }}</title>
  <meta name="description" content="{{ page_description | default('...') }}">

  <!-- CSS — single file, no preprocessor -->
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">

  <!-- JSON-LD structured data -->
  <script type="application/ld+json">
  { "@context": "https://schema.org", "@graph": [...] }
  </script>

  {% block head %}{% endblock %}
</head>
<body>
  <header class="header">...</header>

  <main id="main" role="main">
    {% block content %}{% endblock %}
  </main>

  <footer class="footer">...</footer>

  <!-- Scripts deferred for performance -->
  <script defer src="{{ asset('js/vendor/alpine.min.js') }}"></script>
  <script defer src="{{ asset('js/vendor/htmx.min.js') }}"></script>
  <script defer src="{{ asset('js/main.js') }}"></script>

  {% block scripts %}{% endblock %}
</body>
</html>

<!-- pages/about.html — fills the blocks -->
{% extends "base.html" %}

{% block head %}
<script type="application/ld+json">
{ "@type": "AboutPage", "name": "About Blake Crosley", ... }
</script>
{% endblock %}

{% block content %}
<section class="hero">
  <h1>About</h1>
  <p>Designer, developer, dad.</p>
</section>
{% endblock %}

La directiva {% extends %} establece una relación padre-hijo. La plantilla hija solo define los bloques que necesita sobreescribir. Todo lo demás — el <head>, el header, el footer, las etiquetas de script — proviene de la base. Esto es composición por sustracción en lugar de construcción.

El global asset()

Los archivos estáticos utilizan versionado por hash de contenido para invalidar la caché:

# cache_assets.py
def build_asset_map(static_dir: Path) -> dict[str, str]:
    """Compute MD5 hashes of all static files at startup."""
    asset_map = {}
    for filepath in static_dir.rglob("*"):
        if filepath.is_file():
            rel_path = str(filepath.relative_to(static_dir))
            content_hash = hashlib.md5(filepath.read_bytes()).hexdigest()[:10]
            asset_map[rel_path] = content_hash
    return asset_map

def make_asset_url(asset_map: dict, path: str) -> str:
    """Generate versioned URL: /static/css/styles.css?v=a3f8b2c1d0"""
    clean_path = path.lstrip("/")
    version = asset_map.get(clean_path, "0")
    return f"/static/{clean_path}?v={version}"

En la plantilla: {{ asset('css/styles.css') }} se renderiza como /static/css/styles.css?v=a3f8b2c1d0. El hash cambia cuando el archivo cambia, invalidando la caché del CDN. Esto reemplaza la estrategia de nombres de archivo [contenthash] de webpack con 30 líneas de Python calculadas al inicio.

Include para parciales reutilizables

Los componentes que se repiten en distintas páginas usan {% include %}:

<!-- base.html -->
{% include "components/_language_switcher.html" %}

<!-- components/_language_switcher.html -->
{%- set current = current_locale() -%}
{%- set locales = all_locales() -%}

<div class="language-switcher"
     x-data="{ open: false }"
     @click.away="open = false">
  <button @click="open = !open" :aria-expanded="open">
    {{ current_locale_native() }}
  </button>
  <ul class="language-switcher-menu"
      :class="{ 'is-open': open }"
      x-cloak>
    {% for locale in locales %}
    <li>
      <a href="{{ locale_url(request.url.path, locale.code) }}"
         hreflang="{{ locale.code }}">
        {{ locale.native }}
      </a>
    </li>
    {% endfor %}
  </ul>
</div>

El prefijo de guion bajo (_language_switcher.html) es una convención que indica un parcial — un fragmento de plantilla que no está pensado para renderizarse de forma independiente. Este componente usa tanto Alpine.js (para el toggle del desplegable) como Jinja2 (para la lista de idiomas). La frontera es clara: Alpine.js gestiona el estado de abrir/cerrar, Jinja2 gestiona los datos.

Macros para componentes reutilizables

Las macros son las funciones de Jinja2 — bloques de plantilla reutilizables con parámetros:

<!-- components/_macros.html -->
{% macro card(title, description, href, badge=None) %}
<article class="card">
  <a href="{{ href }}" class="card__link">
    {% if badge %}
    <span class="card__badge">{{ badge }}</span>
    {% endif %}
    <h3 class="card__title">{{ title }}</h3>
    {% if description %}
    <p class="card__description">{{ description }}</p>
    {% endif %}
  </a>
</article>
{% endmacro %}

{% macro optimized_image(image_config, loading="lazy") %}
{% if image_config.get("svg") %}
  <img src="{{ image_config.svg }}"
       width="{{ image_config.width }}"
       height="{{ image_config.height }}"
       alt="{{ image_config.alt }}">
{% else %}
  <picture>
    <source type="image/webp"
            srcset="{{ image_config.webp_srcset }}"
            sizes="(max-width: 768px) 100vw, 50vw">
    <img src="{{ image_config.fallback }}"
         width="{{ image_config.width }}"
         height="{{ image_config.height }}"
         alt="{{ image_config.alt }}"
         loading="{{ loading }}">
  </picture>
{% endif %}
{% endmacro %}

Importa y usa macros en plantillas de página:

{% from "components/_macros.html" import card, optimized_image %}

<section class="projects">
  {% for project in projects %}
    {{ card(
      title=project.title,
      description=project.description,
      href=project.link,
      badge="New" if project.is_new else None
    ) }}
  {% endfor %}
</section>

Las macros reemplazan a los componentes de React para patrones de presentación. Aceptan parámetros, soportan valores por defecto y se componen con otras macros. La diferencia: las macros se renderizan una vez en el servidor y producen HTML estático. Los componentes de React se renderizan en el cliente y mantienen estado. Para mostrar contenido, las macros son la herramienta adecuada.

Contexto de plantilla y globales

Los globales de Jinja2 son funciones disponibles en toda plantilla sin necesidad de pasarlas explícitamente:

# In main.py — register globals
templates.env.globals["asset"] = lambda path: make_asset_url(_asset_map, path)
templates.env.globals["csrf_token"] = generate_csrf_token
templates.env.globals["analytics_script"] = analytics.tracking_script

El global asset() genera URLs versionadas. El global csrf_token() genera tokens CSRF nuevos. El global analytics_script() inyecta el snippet de rastreo. Estas funciones se pueden invocar en cualquier plantilla sin que el handler de la ruta las pase explícitamente.

Para i18n, la configuración es más elaborada — las funciones de traducción necesitan acceso al idioma de la solicitud actual:

# i18n/jinja.py
def setup_i18n_jinja(env):
    """Register translation functions as Jinja2 globals."""
    env.globals["_"] = get_translation        # _('ui.nav.about')
    env.globals["locale_prefix"] = get_locale_prefix  # '/ja' or ''
    env.globals["current_locale"] = get_current_locale
    env.globals["all_locales"] = get_all_locales
    env.globals["alternate_urls"] = get_alternate_urls
    env.globals["lang_attr"] = get_lang_attr  # 'ja' for HTML lang
    env.globals["og_locale"] = get_og_locale  # 'ja_JP' for og:locale
    env.globals["jsonld_lang"] = get_jsonld_lang  # 'ja-JP' for JSON-LD

Cada función lee el idioma desde la variable de contexto de la solicitud, establecida por el middleware de idioma. La plantilla llama a {{ _('ui.nav.about') }} y obtiene la cadena traducida para el idioma de la solicitud actual sin necesidad de ningún parámetro de idioma explícito.

Bloques condicionales

El sistema de bloques de Jinja2 soporta sobreescrituras condicionales:

<!-- base.html -->
{% block head %}{% endblock %}

<!-- pages/blog/post.html -->
{% block head %}
<script type="application/ld+json">
{
  "@type": "Article",
  "headline": "{{ post.meta.title }}",
  "author": { "@id": "https://blakecrosley.com/#person" },
  "datePublished": "{{ post.meta.date.isoformat() }}",
  "dateModified": "{{ post.meta.updated.isoformat() if post.meta.updated else post.meta.date.isoformat() }}"
}
</script>

{% if post.meta.scripts %}
{% for script in post.meta.scripts %}
<script defer src="{{ asset(script.lstrip('/static/')) }}"></script>
{% endfor %}
{% endif %}

{% if post.meta.styles %}
{% for style in post.meta.styles %}
<link rel="stylesheet" href="{{ asset(style.lstrip('/static/')) }}">
{% endfor %}
{% endif %}
{% endblock %}

Las entradas del blog declaran sus dependencias en el frontmatter de YAML (scripts: ["/static/js/boids.js"]). La plantilla las incluye condicionalmente. Las páginas que no necesitan scripts o estilos adicionales no envían ninguno — sin código muerto, sin imports sin usar.

Filtros personalizados

Los filtros de Jinja2 transforman datos durante el renderizado. El filtro sanitize previene XSS en contenido generado por usuarios:

import nh3

ALLOWED_TAGS = {"a", "b", "blockquote", "br", "code", "em", "h1", "h2",
                "h3", "h4", "h5", "h6", "hr", "i", "img", "li", "ol",
                "p", "pre", "span", "strong", "table", "td", "th", "tr", "ul"}

def sanitize_html(value: str) -> str:
    """Sanitize HTML to prevent XSS attacks."""
    if not value:
        return ""
    return nh3.clean(
        value,
        tags=ALLOWED_TAGS,
        attributes={"a": {"href", "title"}, "img": {"src", "alt"}},
        link_rel="noopener noreferrer",
    )

templates.env.filters["sanitize"] = sanitize_html

En las plantillas: {{ user_content | sanitize }}. La biblioteca nh3 es un sanitizador de HTML basado en Rust — rápido y seguro. Elimina cualquier etiqueta o atributo que no esté en la lista permitida, previniendo XSS almacenado incluso si el contenido proviene de una fuente no confiable.¹⁰

HTMX a Fondo

HTMX permite que cualquier elemento HTML sea capaz de emitir solicitudes HTTP e intercambiar la respuesta en el DOM. La clave es arquitectónica: el HTML renderizado en el servidor es la API. El servidor devuelve la representación final. Sin renderizado del lado del cliente, sin serialización JSON, sin hidratación.

Atributos Principales

Patrón 1: Quiz Interactivo (Estado Multi-Paso en el Servidor)

blakecrosley.com incluye un quiz interactivo que guía a los usuarios en la selección de herramientas. Todo el estado del quiz reside en el servidor — sin gestión de estado del lado del cliente:

<!-- _quiz_container.html — carga inicial -->
<div hx-get="/api/quiz/claude-vs-codex/step?answers="
     hx-trigger="load"
     hx-swap="innerHTML"
     id="quiz-wrapper">
  <p>Loading quiz...</p>
</div>

<!-- _quiz_step.html — cada pregunta -->
<div class="quiz-step" id="quiz-container">
  <p>Question {{ step }} of {{ total }}</p>
  <h3>{{ question.question }}</h3>
  <div class="quiz-step__options">
    {% for opt in question.options %}
    <button class="quiz-step__btn"
            hx-get="/api/quiz/claude-vs-codex/step?answers={{ answers }},{{ opt.value }}"
            hx-target="#quiz-container"
            hx-swap="outerHTML">
      {{ opt.label }}
    </button>
    {% endfor %}
  </div>
</div>

Cada clic en un botón envía las respuestas acumuladas como parámetro de consulta. El servidor calcula la siguiente pregunta o el resultado final basándose en el historial de respuestas. El estado se acumula en la URL — sin cookies, sin sesiones, sin JavaScript del lado del cliente. El quiz avanza mediante intercambios outerHTML: cada respuesta reemplaza el elemento completo del paso del quiz.

Patrón 2: Lista de Blog Paginada

La página de escritura utiliza HTMX para una paginación fluida que actualiza la URL:

<!-- Pagination link -->
<a href="/writing?page=2&category=Engineering"
   hx-get="/writing?page=2&category=Engineering"
   hx-target="#writing-content"
   hx-swap="innerHTML"
   hx-replace-url="true"
   hx-indicator="#writing-loading"
   aria-label="Go to page 2">
  2
</a>

Cuatro atributos trabajando en conjunto:

1. hx-get emite la solicitud a la misma URL que el href (mejora progresiva — funciona sin JavaScript)
2. hx-target coloca la respuesta en el contenedor #writing-content
3. hx-replace-url="true" actualiza la URL del navegador sin agregar una entrada al historial
4. hx-indicator muestra un spinner de carga durante la solicitud

El servidor detecta las solicitudes HTMX mediante el encabezado HX-Request y devuelve únicamente el fragmento de la lista de publicaciones en lugar de la página completa. Por eso el middleware de encabezados de seguridad agrega Vary: HX-Request — para que las cachés del CDN almacenen la página completa y el fragmento por separado.¹¹

Patrón 3: Búsqueda con Debounce

<input type="search" name="q"
       hx-get="/api/search"
       hx-trigger="keyup changed delay:300ms"
       hx-target="#results"
       hx-indicator="#search-spinner" />
<div id="results"></div>

El atributo hx-trigger combina tres modificadores:

• keyup se dispara al soltar una tecla
• changed se dispara solo si el valor realmente cambió (evita solicitudes duplicadas por teclas modificadoras)
• delay:300ms aplica debounce — espera 300ms después del último keyup antes de disparar

El servidor devuelve un fragmento HTML renderizado:

@router.get("/api/search")
async def search(request: Request, q: str = ""):
    results = search_content(q)
    return templates.TemplateResponse("components/_search_results.html", {
        "request": request,
        "results": results,
        "query": q,
    })

Sin estado del lado del cliente. Sin biblioteca de debounce. Sin useEffect. La plantilla renderiza los resultados, HTMX los intercambia en el DOM, y el servidor es la única fuente de verdad.

Patrón 4: Intercambios Out-of-Band (OOB)

A veces una sola acción del servidor necesita actualizar múltiples elementos del DOM. El mecanismo de intercambio out-of-band de HTMX maneja esto sin orquestación del lado del cliente:

<!-- Server returns multiple elements in one response -->
<!-- Primary target: swapped normally via hx-target -->
<div id="cart-items">
  <ul>
    <li>Widget A — $29.99</li>
    <li>Widget B — $14.99</li>
  </ul>
</div>

<!-- OOB target: swapped independently via hx-swap-oob -->
<span id="cart-count" hx-swap-oob="true">2 items</span>
<span id="cart-total" hx-swap-oob="true">$44.98</span>

El atributo hx-swap-oob="true" le indica a HTMX que busque el elemento por id en cualquier parte del DOM y lo reemplace, independientemente del hx-target. Esto sustituye el patrón de “elevar el estado” de React — el servidor calcula todo el estado derivado y envía el HTML final para cada elemento en una sola respuesta.

Un formulario de contacto lo demuestra bien: enviar el formulario podría reemplazar el cuerpo del formulario con un mensaje de éxito y simultáneamente actualizar una insignia de notificación mediante un intercambio OOB:

Patrón 5: Enlaces Potenciados

HTMX puede “potenciar” enlaces de navegación estándar para usar AJAX en lugar de cargas completas de página:

<nav hx-boost="true">
  <a href="/about">About</a>
  <a href="/writing">Writing</a>
  <a href="/guides">Guides</a>
</nav>

Con hx-boost="true", al hacer clic en un enlace se obtiene la página vía AJAX, se intercambia el contenido del <body> y se actualiza la URL — sin una recarga completa de página. El historial del navegador funciona normalmente (botones adelante/atrás). Si JavaScript falla, los enlaces funcionan como navegación estándar.

El beneficio es el rendimiento percibido: la navegación potenciada se siente instantánea porque el navegador no necesita re-analizar CSS, re-evaluar scripts ni re-renderizar el diseño. Solo cambia el contenido del <body>. Los enlaces potenciados funcionan bien para elementos de navegación principal, lo que hace que las transiciones de página se sientan como una aplicación de página única sin la arquitectura SPA.

Patrón 6: Encabezados de Solicitud de HTMX

HTMX envía encabezados personalizados con cada solicitud:

El servidor puede usar HX-Request para devolver respuestas diferentes:

@router.get("/writing")
async def writing(request: Request, page: int = 1, category: str = None):
    posts = load_all_posts(page=page, category=category)
    context = {"request": request, "posts": posts, "current_page": page}

    # HTMX request: return only the post list fragment
    if request.headers.get("HX-Request"):
        return templates.TemplateResponse(
            "pages/writing/_post_list.html", context
        )

    # Normal request: return the full page
    return templates.TemplateResponse("pages/writing/index.html", context)

Este patrón de respuesta dual es central en la arquitectura. Una carga completa de página devuelve el documento completo (plantilla base + contenido de la página). Una navegación HTMX devuelve únicamente el contenido que cambió. El servidor decide, no el cliente.

Patrón 7: Mejora Progresiva

Cada enlace HTMX en blakecrosley.com incluye un atributo href estándar:

<a href="/writing?page=2"
   hx-get="/writing?page=2"
   hx-target="#writing-content"
   hx-swap="innerHTML">
  Next Page
</a>

Si JavaScript no se carga, el href funciona como un enlace normal. Si HTMX se carga, intercepta el clic y realiza un intercambio AJAX. Esto es mejora progresiva: el sitio funciona sin JavaScript, y HTMX mejora la experiencia cuando está disponible.

Patrón 8: Estados de Carga

<button hx-post="/api/contact"
        hx-target="#form-result"
        hx-indicator="#submit-spinner">
  <span id="submit-spinner" class="htmx-indicator">Sending...</span>
  <span>Send Message</span>
</button>

HTMX agrega la clase htmx-request al elemento que dispara la solicitud durante las peticiones. El atributo hx-indicator apunta a un elemento que se vuelve visible durante la solicitud. Dale estilo con CSS:

.htmx-indicator {
  display: none;
}
.htmx-request .htmx-indicator,
.htmx-request.htmx-indicator {
  display: inline;
}

Sin gestión de estados de carga. Sin useState(false). Sin setLoading(true). CSS maneja la visibilidad, HTMX maneja el cambio de clase.

Patrones de Alpine.js

Alpine.js llena el vacío que HTMX deja: estado que solo existe en el cliente y que nunca necesita comunicarse con el servidor. Si el usuario hace clic en un desplegable y este se abre, ese estado existe únicamente en el navegador. Alpine.js lo gestiona con atributos HTML.

La regla de límites

El límite entre HTMX y Alpine.js es preciso:

Navegación móvil

La plantilla base envuelve todo el encabezado en un componente Alpine.js:

<div x-data="{ navOpen: false, langOpen: false }"
     @keydown.escape.window="navOpen = false; langOpen = false">

  <!-- Mobile hamburger button -->
  <button @click="navOpen = !navOpen; langOpen = false"
          :aria-expanded="navOpen"
          :class="navOpen ? 'nav__toggle is-open' : 'nav__toggle'"
          aria-label="Toggle navigation">
    <span class="nav__toggle-icon">
      <span class="nav__toggle-bar"></span>
      <span class="nav__toggle-bar"></span>
      <span class="nav__toggle-bar"></span>
    </span>
  </button>

  <!-- Mobile menu panel -->
  <div class="mobile-menu" x-show="navOpen" x-cloak>
    <nav class="mobile-menu__nav">
      <a href="/about" @click="navOpen = false">About</a>
      <a href="/#work" @click="navOpen = false">Work</a>
      <a href="/writing" @click="navOpen = false">Writing</a>
    </nav>
  </div>
</div>

Patrones clave de Alpine.js:

• x-data declara el alcance del componente y su estado inicial
• x-show alterna la visibilidad según el estado (usa CSS display: none)
• x-cloak oculta el elemento hasta que Alpine.js se inicializa (evita el destello de contenido sin estilos)
• @click vincula manejadores de clic con expresiones
• :aria-expanded (abreviatura de x-bind:aria-expanded) establece atributos dinámicamente
• @keydown.escape.window escucha la tecla Escape de forma global para cerrar paneles

Componente de desplegable

El selector de idioma usa Alpine.js para el estado de alternancia con @click.away para cerrar al hacer clic fuera:

<div x-data="{ open: false }"
     @click.away="open = false"
     @keydown.escape.window="open = false">

  <button @click="open = !open"
          :aria-expanded="open"
          aria-haspopup="listbox">
    English
    <svg :class="{ 'rotated': open }">...</svg>
  </button>

  <ul :class="{ 'is-open': open }"
      :aria-hidden="!open"
      role="listbox"
      x-cloak>
    <li role="option">
      <a href="/ja/about">日本語</a>
    </li>
    <!-- more languages -->
  </ul>
</div>

El modificador @click.away cierra el desplegable al hacer clic fuera de él. Alpine.js maneja esto con un solo atributo — sin registro de event listeners, sin limpieza, sin gestión de refs.

Cuándo usar Alpine.js vs. JavaScript puro

Alpine.js es apropiado cuando:

• El estado tiene alcance limitado a un solo elemento del DOM (desplegable, modal, toggle)
• Las interacciones son binarias o simples (abrir/cerrar, mostrar/ocultar, alternar)
• Múltiples elementos necesitan reaccionar al mismo cambio de estado
• Los atributos de accesibilidad deben mantenerse sincronizados con la visibilidad

JavaScript puro es apropiado cuando:

• La interacción involucra cálculos complejos (visualizaciones, simulaciones)
• El componente tiene su propio ciclo de renderizado (canvas, animación)
• El rendimiento es crítico (Alpine.js agrega overhead por cada componente x-data)
• La lógica supera las 20-30 líneas de expresiones Alpine.js

blakecrosley.com usa Alpine.js para navegación, cambio de idioma y toggles de contenido. Los 20 componentes interactivos del blog (simulación de boids, visualizador de código Hamming, etc.) usan JavaScript puro porque requieren renderizado en canvas y máquinas de estado complejas.

Ejemplo de extremo a extremo: filtrado por categorías en /writing

Esta sección traza una función real del código en producción a través de cada capa: ruta, plantilla, interacción con HTMX, seguridad, caché y resultado renderizado. La función: pestañas de categorías en la página de escritura que filtran las publicaciones del blog sin recargar la página completa.

La ruta (app/routes/pages.py:508)

async def writing_listing(request: Request, page: int = 1, category: str | None = None):
    """Writing page — blog posts and external publications."""
    templates = get_templates(request)
    markdown_posts = load_all_posts(published_only=True)
    all_posts = CUSTOM_BLOG_POSTS + markdown_posts

    # Filter by category if specified
    if category and category in CATEGORY_MAP:
        display_name = CATEGORY_MAP[category]
        all_posts = [
            p for p in all_posts
            if _get_post_category(p).lower() == display_name.lower()
        ]

    # Pagination
    total_pages = max(1, (len(all_posts) + POSTS_PER_PAGE - 1) // POSTS_PER_PAGE)
    page = max(1, min(page, total_pages))
    paginated = all_posts[(page - 1) * POSTS_PER_PAGE : page * POSTS_PER_PAGE]

    template_context = {
        "request": request,
        "posts": paginated,
        "categories": categories,
        "current_category": category,
        "current_page": page,
        "total_pages": total_pages,
        # ... SEO: canonical, prev/next URLs
    }

    # HTMX partial: return just the post list fragment
    if request.headers.get("HX-Request"):
        return templates.TemplateResponse(
            "pages/writing/_post_list.html",
            template_context,
        )

    # Full page for direct navigation
    return templates.TemplateResponse(
        "pages/writing/index.html",
        template_context,
    )

La verificación del encabezado HX-Request es el patrón central: misma ruta, mismos datos, plantilla diferente. HTMX recibe un fragmento. Los navegadores reciben la página completa.

Las pestañas de categorías (HTMX)

<!-- Category filter tabs -->
<nav class="writing-categories">
  <a href="/writing"
     hx-get="/writing"
     hx-target="#post-list"
     hx-push-url="true"
     class="category-tab {% if not current_category %}active{% endif %}">
    All ({{ total_posts }})
  </a>
  {% for cat in categories %}
  <a href="/writing?category={{ cat.slug }}"
     hx-get="/writing?category={{ cat.slug }}"
     hx-target="#post-list"
     hx-push-url="true"
     class="category-tab {% if current_category == cat.slug %}active{% endif %}">
    {{ cat.name }} ({{ cat.count }})
  </a>
  {% endfor %}
</nav>

<div id="post-list">
  {% include "pages/writing/_post_list.html" %}
</div>

Cada pestaña tiene tanto href (funciona sin JavaScript) como hx-get (intercambia solo la lista de publicaciones). hx-push-url actualiza la URL del navegador para que la vista filtrada sea compartible y se pueda guardar en marcadores.

El parcial (pages/writing/_post_list.html)

El parcial se renderiza de forma idéntica tanto cuando se incluye en la carga inicial de la página como cuando HTMX lo intercambia:

{% for post in posts %}
<article class="post-card">
  <a href="{{ locale_prefix() }}/blog/{{ post.meta.slug }}">
    <h3>{{ post.meta.title }}</h3>
    <p>{{ post.meta.description }}</p>
    <time>{{ post.meta.date }}</time> · {{ post.reading_time }}m
  </a>
</article>
{% endfor %}

Sin marcado especial de HTMX en el parcial. Sin lógica de renderizado en el cliente. La misma HTML funciona tanto para la carga inicial de la página como para cada filtro posterior.

Seguridad

Los valores de categoría se validan contra CATEGORY_MAP (un diccionario del lado del servidor) antes de filtrar. Las categorías inválidas se ignoran, no se devuelven como eco. Ninguna entrada del usuario se interpola en SQL ni en HTML. El encabezado CSP bloquea scripts inline.

Caché

Las respuestas de categorías son dinámicas (sin caché en CDN). Pero los recursos estáticos (CSS, HTMX, Alpine.js) tienen hash de contenido y se cachean indefinidamente después de la primera carga. Los cambios de categoría posteriores transfieren únicamente el parcial HTML (~3-5KB) — sin CSS, sin JS, sin imágenes que volver a descargar.

Lo que esto demuestra

Una función, código real de producción, cero herramientas de compilación. El servidor filtra y renderiza HTML. HTMX intercambia la lista de publicaciones. Alpine.js no interviene (no se necesita estado en el cliente). La URL se actualiza para poder compartirla. Mejora progresiva: las pestañas funcionan como enlaces simples sin JavaScript. Total de JavaScript personalizado para esta función: cero líneas.

Extensiones opcionales

Las siguientes secciones cubren patrones que complementan el stack principal pero que no se usan en blakecrosley.com. Se incluyen porque representan las adiciones más comunes que los equipos realizan al adoptar esta arquitectura.

Bootstrap 5 sin Sass

Nota: blakecrosley.com usa CSS plano con propiedades personalizadas — sin Bootstrap. Esta sección cubre Bootstrap 5 como opción para equipos que quieren un framework de utilidades sin un paso de compilación. El CSS compilado de Bootstrap se puede cargar desde un CDN o incluir en tu hoja de estilos. Los patrones a continuación son genéricos y funcionan junto con el enfoque de HTMX + Alpine.js descrito en secciones anteriores.

Bootstrap 5 eliminó jQuery como dependencia y admite el uso independiente de CSS. No necesitas Sass, PostCSS ni ninguna herramienta de compilación para usar el sistema de grillas y las clases de utilidad de Bootstrap.

Autoalojamiento sin CDN

blakecrosley.com autoaloja todas las bibliotecas de terceros:

<!-- base.html — no CDN, no external requests -->
<script defer src="{{ asset('js/vendor/alpine.min.js') }}"></script>
<script defer src="{{ asset('js/vendor/htmx.min.js') }}"></script>

El autoalojamiento elimina dependencias externas, evita que caídas del CDN rompan el sitio y permite caché inmutable con URLs basadas en hash de contenido. Descarga el CSS compilado de Bootstrap (no el código fuente Sass) y colócalo en static/css/vendor/.

Sistema de grillas

La grilla de Bootstrap funciona con clases HTML simples:

<div class="container">
  <div class="row">
    <div class="col-12 col-md-8">
      <article>Main content</article>
    </div>
    <div class="col-12 col-md-4">
      <aside>Sidebar</aside>
    </div>
  </div>
</div>

Sin mixins de Sass. Sin @include make-col(). El CSS compilado incluye las clases responsivas de la grilla. Para breakpoints personalizados más allá de los valores predeterminados de Bootstrap, escribe media queries de CSS plano.

Sobrescrituras con CSS plano

Sobrescribe los valores predeterminados de Bootstrap con propiedades personalizadas de CSS y selectores estándar:

/* Custom design tokens — no Sass, no Tailwind */
:root {
  --color-bg-dark:        #000000;
  --color-text-primary:   #ffffff;
  --color-text-secondary: rgba(255, 255, 255, 0.65);
  --color-text-tertiary:  rgba(255, 255, 255, 0.40);
  --spacing-sm:           1rem;
  --spacing-md:           1.5rem;
  --spacing-lg:           2rem;
  --gutter:               48px;
  --font-size-lg:         1.25rem;
}

/* Responsive override — the browser reads this at runtime */
@media (max-width: 768px) {
  :root {
    --gutter: var(--spacing-md);  /* 48px → 24px on mobile */
  }
}

/* Override Bootstrap's default body styles */
body {
  background: var(--color-bg-dark);
  color: var(--color-text-primary);
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
}

Las propiedades personalizadas de CSS se propagan a través del DOM, se heredan de los elementos padre y responden a media queries en tiempo de ejecución. Las variables de Sass se compilan a valores estáticos y desaparecen. Esta distinción importa para la tematización: un solo cambio en una propiedad personalizada puede actualizar todos los valores derivados sin recompilación.¹²

Clases de utilidad vs. CSS de componentes

Usa las clases de utilidad de Bootstrap para espaciado y diseño puntuales. Usa CSS de componentes para patrones repetidos:

<!-- Bootstrap utility for one-off spacing -->
<div class="mt-4 mb-3 px-2">One-off layout</div>

<!-- Component class for repeated patterns -->
<article class="writing__item">
  <h3 class="writing__item-title">Post Title</h3>
  <p class="writing__item-description">Description</p>
</article>

/* Component CSS — BEM naming, reusable */
.writing__item {
  padding: var(--spacing-md);
  border-bottom: 1px solid rgba(255, 255, 255, 0.1);
  transition: background 0.15s ease;
}
.writing__item:hover {
  background: rgba(255, 255, 255, 0.03);
}
.writing__item-title {
  font-size: var(--font-size-lg);
  margin-bottom: 0.5rem;
}

El principio: utilidades de Bootstrap para la mecánica del diseño (margen, relleno, flexbox). CSS personalizado para la identidad visual (colores, tipografía, animaciones). Nunca mezcles clases de utilidad con estilos de componente para la misma responsabilidad.

i18n y localización

blakecrosley.com ofrece contenido en 10 idiomas: inglés, japonés, coreano, chino simplificado, chino tradicional, alemán, francés, español, polaco y portugués (brasileño).

Enrutamiento de locale basado en URL

El locale se encuentra en la ruta de la URL: /about (inglés), /ja/about (japonés), /zh-Hans/about (chino simplificado). El inglés es el idioma predeterminado y no tiene prefijo.

# i18n/config.py
SUPPORTED_LOCALES = [
    "en", "zh-Hans", "zh-Hant", "fr", "de", "ja", "ko", "pl", "pt-BR", "es"
]
DEFAULT_LOCALE = "en"

El middleware de locale extrae el locale de la ruta de la URL:

# i18n/middleware.py
class LocaleMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        path = request.url.path
        # Check if path starts with a supported locale
        for locale in SUPPORTED_LOCALES:
            if path.startswith(f"/{locale}/") or path == f"/{locale}":
                request.state.locale = locale
                # Strip locale prefix for route matching
                request.scope["path"] = path[len(f"/{locale}"):]
                break
        else:
            request.state.locale = DEFAULT_LOCALE

        response = await call_next(request)
        return response

El middleware elimina el prefijo de locale antes de hacer coincidir las rutas. Esto significa que los manejadores de rutas no necesitan rutas específicas por locale: /about gestiona tanto el inglés (/about) como el japonés (/ja/about) porque el middleware normaliza la ruta.

Funciones de traducción en plantillas

Los globals de Jinja2 proporcionan funciones de traducción:

<!-- Template usage -->
<h3>{{ _('ui.footer.navigate') | default('Navigate') }}</h3>
<a href="{{ locale_prefix() }}/about">
  {{ _('ui.nav.about') | default('About') }}
</a>

La función _() busca una clave de traducción en la caché en memoria. El filtro | default() proporciona el texto en inglés como respaldo si falta la traducción. La función locale_prefix() devuelve el prefijo de URL para el locale actual ("" para inglés, "/ja" para japonés).

Etiquetas hreflang

Cada página incluye etiquetas hreflang para todos los locales soportados:

<!-- Generated in base.html -->
{% for alt in alternate_urls(request.url.path) %}
<link rel="alternate" hreflang="{{ alt.hreflang }}" href="{{ alt.url }}">
{% endfor %}

Esto produce:

<link rel="alternate" hreflang="en" href="https://blakecrosley.com/about">
<link rel="alternate" hreflang="ja" href="https://blakecrosley.com/ja/about">
<link rel="alternate" hreflang="zh-Hans" href="https://blakecrosley.com/zh-Hans/about">
<!-- ... all 10 locales -->
<link rel="alternate" hreflang="x-default" href="https://blakecrosley.com/about">

Los motores de búsqueda usan hreflang para mostrar la versión en el idioma correcto en los resultados de búsqueda. La entrada x-default apunta a la versión en inglés como respaldo.¹³

Almacenamiento de traducciones y caché en memoria

Las traducciones se almacenan en Cloudflare D1 (SQLite en el edge) y se cargan en una caché en memoria mediante el manejador lifespan:

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Load translations into memory at startup
    for locale in SUPPORTED_LOCALES:
        data = await fetch_translations(locale)
        TRANSLATIONS[locale] = data
    yield

app = FastAPI(lifespan=lifespan)

La caché en memoria evita consultas a la base de datos en cada renderizado de página. Las actualizaciones de traducciones requieren una recarga de la caché (activada mediante un endpoint de administración o un despliegue). Esta arquitectura sacrifica frescura por rendimiento: las traducciones cambian con poca frecuencia, pero los renderizados de página ocurren en cada solicitud.

Monitoreo de salud

blakecrosley.com incluye un endpoint de verificación de salud para i18n que monitorea la cobertura de traducción por locale:

@app.get("/health/i18n")
async def health_i18n():
    cache = get_translation_cache()
    result = {
        "status": "healthy",
        "cache_loaded": cache.is_loaded,
        "locales": {},
        "alerts": [],
    }

    # Check coverage for each locale
    for locale in SUPPORTED_LOCALES:
        coverage = await calculate_coverage(locale, en_count)
        result["locales"][locale] = {"coverage": round(coverage, 2)}

        if coverage < 99.5:
            result["alerts"].append(
                f"{locale}: {coverage:.1f}% coverage (threshold: 99.5%)"
            )
            result["status"] = "warning"

    return result

El umbral de cobertura del 99,5% detecta traducciones faltantes antes de que los usuarios encuentren cadenas sin traducir. El endpoint de salud se integra con el monitoreo de Railway para alertar cuando la cobertura baja, por ejemplo, después de agregar nuevas cadenas de interfaz que aún no se han traducido.

Renderizado de contenido según el locale

Las publicaciones del blog y las guías soportan traducciones por locale de metadatos y contenido:

# In route handler
translated = get_blog_translation(post.meta.slug, locale)
return templates.TemplateResponse("pages/blog/post.html", {
    "request": request,
    "post": post,
    "translated_title": translated.title if translated else post.meta.title,
    "translated_description": translated.description if translated else post.meta.description,
})

<!-- In template -->
<h1>{{ translated_title }}</h1>
<p class="post__description">{{ translated_description }}</p>
<!-- Body content falls back to English if translation unavailable -->
{{ post.html | sanitize | safe }}

El patrón es consistente: intentar primero con el contenido traducido, recurrir al inglés como respaldo. Esto permite la traducción parcial: un usuario japonés ve títulos y descripciones traducidos incluso si el cuerpo completo del artículo permanece en inglés. El filtro | default() de Jinja2 codifica este patrón en un solo pipe:

{{ translated.title if translated else post.meta.title }}

Traducción de datos de locale

El contenido estático como descripciones de proyectos y etiquetas de navegación se traduce mediante funciones auxiliares que mantienen la misma estructura de datos mientras intercambian las cadenas específicas del locale:

# i18n/data.py
def translate_projects(projects: list, locale: str) -> list:
    """Return projects with translated titles and descriptions."""
    if locale == "en":
        return projects
    translated = []
    for project in projects:
        t = get_translation(f"project.{project['slug']}.title", locale)
        d = get_translation(f"project.{project['slug']}.description", locale)
        translated.append({
            **project,
            "title": t or project["title"],
            "description": d or project["description"],
        })
    return translated

Este enfoque mantiene la capa de traducción separada de la capa de datos. Las rutas pasan la misma lista projects independientemente del locale. Las funciones de traducción envuelven los datos de forma transparente.

Sitemap con alternativas hreflang

El sitemap dinámico incluye todas las páginas en todos los locales con referencias cruzadas:

@app.get("/sitemap.xml")
async def sitemap():
    for page in static_pages:
        for locale in SUPPORTED_LOCALES:
            # Each URL entry includes alternates for all locales
            locale_path = f"/{locale}{path}" if locale != "en" else path
            xml_parts.append(f"<loc>{base_url}{locale_path}</loc>")
            # Add xhtml:link alternates
            for alt_locale in SUPPORTED_LOCALES:
                alt_path = f"/{alt_locale}{path}" if alt_locale != "en" else path
                hreflang = LOCALE_TO_HREFLANG[alt_locale]
                xml_parts.append(
                    f'<xhtml:link rel="alternate" hreflang="{hreflang}" '
                    f'href="{base_url}{alt_path}"/>'
                )

Esto produce 10 entradas de URL por página (una por locale), cada una con 11 enlaces alternativos (10 locales + x-default). Para un sitio con 50 páginas, el sitemap contiene 500 entradas de URL con 5.500 enlaces hreflang. El sitemap se genera dinámicamente y se almacena en caché durante una hora.

Patrones de base de datos

Nota: blakecrosley.com usa Cloudflare D1 (SQLite serverless) vía HTTP para todos los datos persistentes, no SQLAlchemy. Esta sección cubre el patrón estándar de SQLAlchemy async para proyectos FastAPI que necesitan una base de datos relacional — la configuración de producción más común para este stack.

SQLAlchemy 2.0 Async

Para aplicaciones que necesitan una base de datos relacional, el soporte async de SQLAlchemy 2.0 se integra de forma limpia con FastAPI:

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker, DeclarativeBase

engine = create_async_engine("sqlite+aiosqlite:///./data.db")
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

class Base(DeclarativeBase):
    pass

Inyección de dependencias para sesiones de base de datos

from fastapi import Depends
from sqlalchemy.ext.asyncio import AsyncSession

async def get_db() -> AsyncGenerator[AsyncSession, None]:
    async with async_session() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

@router.get("/users/{user_id}")
async def get_user(request: Request, user_id: int, db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    if not user:
        raise HTTPException(404, "User not found")
    return templates.TemplateResponse("pages/user.html", {
        "request": request, "user": user
    })

La dependencia get_db gestiona el ciclo de vida de la sesión: abre una sesión, la entrega al handler de la ruta, hace commit en caso de éxito y rollback en caso de excepción. Todas las operaciones de base de datos usan consultas parametrizadas — nunca interpolación de cadenas.

Integración con Pydantic

Los modelos Pydantic validan la entrada en el límite de API y serializan la salida para los templates:

from pydantic import BaseModel, EmailStr

class ContactForm(BaseModel):
    name: str
    email: EmailStr
    message: str

@router.post("/contact")
async def submit_contact(request: Request, form: ContactForm):
    # form.name, form.email, form.message are validated
    await send_email(form)
    return templates.TemplateResponse("components/_contact_success.html", {
        "request": request
    })

Pydantic valida tipos, formatos (email, URL) y restricciones (longitud mínima/máxima) antes de que se ejecute el handler de la ruta. La entrada inválida devuelve una respuesta 422 automáticamente. Esto reemplaza las bibliotecas de validación de formularios del lado del cliente — el servidor valida, y HTMX intercambia el mensaje de éxito o el feedback de error.

Migraciones con Alembic

Alembic gestiona los cambios en el esquema de la base de datos:

# Generate a migration from model changes
alembic revision --autogenerate -m "add user preferences table"

# Apply migrations
alembic upgrade head

# Roll back one migration
alembic downgrade -1

La función de autogeneración compara los modelos de SQLAlchemy contra el esquema actual de la base de datos y genera scripts de migración. Estos scripts son archivos Python versionados que viven en el repositorio:

# alembic/versions/001_add_user_preferences.py
def upgrade():
    op.create_table(
        "user_preferences",
        sa.Column("id", sa.Integer, primary_key=True),
        sa.Column("user_id", sa.Integer, sa.ForeignKey("users.id")),
        sa.Column("locale", sa.String(10), default="en"),
        sa.Column("theme", sa.String(20), default="dark"),
    )

def downgrade():
    op.drop_table("user_preferences")

Las migraciones se ejecutan durante el despliegue (antes de que la aplicación inicie). Esto asegura que el esquema de la base de datos coincida con el código de la aplicación. En blakecrosley.com, la mayoría de los datos viven en Cloudflare D1 (accedido vía HTTP), por lo que las migraciones de Alembic aplican a la base de datos local SQLite o PostgreSQL usada para datos de sesión y analíticas.

El patrón Cloudflare D1

blakecrosley.com usa Cloudflare D1 como base de datos remota accedida a través de un Worker proxy de Cloudflare:

class D1Client:
    """HTTP client for Cloudflare D1 via Worker proxy."""

    def __init__(self, worker_url: str, auth_secret: str):
        self.worker_url = worker_url
        self.auth_secret = auth_secret

    async def fetch_all(self, sql: str, params: list = None) -> list[dict]:
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.worker_url}/query",
                json={"sql": sql, "params": params or []},
                headers={"Authorization": f"Bearer {self.auth_secret}"},
            )
            return response.json()["results"]

Este patrón funciona para aplicaciones que necesitan una base de datos pero no quieren administrar un servidor de base de datos. D1 es SQLite en el edge de Cloudflare, accedido vía HTTP. El Worker proxy maneja la autenticación y el rate limiting. La contrapartida es la latencia: cada consulta es una petición HTTP (~50-100ms) frente a una conexión de base de datos local (~1-5ms). La caché en memoria al inicio mitiga esto para cargas de trabajo con muchas lecturas, como las traducciones.

Seguridad

Middleware de encabezados de seguridad

blakecrosley.com implementa encabezados de seguridad reforzados mediante middleware personalizado:

class SecurityHeadersMiddleware(BaseHTTPMiddleware):
    CSP_DIRECTIVES = {
        "default-src": "'self'",
        "script-src": "'self' 'unsafe-inline' 'unsafe-eval'",
        "style-src": "'self' 'unsafe-inline'",
        "img-src": "'self' data: https:",
        "connect-src": "'self'",
        "frame-ancestors": "'self'",
        "base-uri": "'self'",
        "form-action": "'self'",
        "upgrade-insecure-requests": "",
    }

    async def dispatch(self, request, call_next):
        response = await call_next(request)
        response.headers["X-Content-Type-Options"] = "nosniff"
        response.headers["X-Frame-Options"] = "SAMEORIGIN"
        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
        response.headers["Strict-Transport-Security"] = (
            "max-age=31536000; includeSubDomains"
        )
        response.headers["Cross-Origin-Opener-Policy"] = "same-origin"
        response.headers["Content-Security-Policy"] = self.csp
        response.headers["Permissions-Policy"] = self.PERMISSIONS_POLICY
        return response

El CSP incluye 'unsafe-inline' y 'unsafe-eval' porque Alpine.js los requiere para la evaluación de expresiones. La alternativa es el build compatible con CSP de Alpine.js, que tiene limitaciones.¹⁴ Todo lo demás está bloqueado: frame-ancestors previene el clickjacking, form-action restringe los envíos de formularios al mismo origen, y upgrade-insecure-requests fuerza HTTPS.

Seguridad de caché CDN con HTMX

El middleware de encabezados de seguridad agrega Vary: HX-Request a las respuestas HTMX:

if request.headers.get("HX-Request"):
    existing_vary = response.headers.get("Vary", "")
    if "HX-Request" not in existing_vary:
        parts = [v.strip() for v in existing_vary.split(",") if v.strip()]
        parts.append("HX-Request")
        response.headers["Vary"] = ", ".join(parts)

Sin este encabezado, un CDN podría cachear una respuesta de fragmento HTMX y servirla como página completa a una petición no-HTMX (o viceversa). El encabezado Vary le indica al CDN que almacene entradas de caché separadas según el valor del encabezado HX-Request.¹¹

Protección CSRF

Los formularios HTMX usan tokens CSRF firmados con HMAC sin estado:

# csrf.py
def generate_csrf_token() -> str:
    """Token format: timestamp:random:HMAC-SHA256-signature"""
    timestamp = str(int(time.time()))
    random_value = secrets.token_hex(16)
    payload = f"{timestamp}:{random_value}"
    signature = hmac.new(
        CSRF_SECRET.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return f"{payload}:{signature}"

def validate_csrf_token(token: str) -> bool:
    """Verify signature and check expiration (1 hour)."""
    timestamp, random_value, signature = token.split(":")
    if int(time.time()) - int(timestamp) > 3600:
        return False
    expected = hmac.new(
        CSRF_SECRET.encode(),
        f"{timestamp}:{random_value}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

El token se genera en el template mediante un global de Jinja2 y se incluye en las peticiones de formulario HTMX:

<form hx-post="/contact" hx-target="#form-result">
  <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
  <!-- form fields -->
</form>

Los tokens sin estado eliminan el almacenamiento de sesiones del lado del servidor. La firma HMAC asegura que el token fue generado por el servidor. El timestamp previene ataques de repetición. hmac.compare_digest previene ataques de temporización.¹⁵

Sanitización HTML

El contenido generado por usuarios pasa por nh3 antes del renderizado:

templates.env.filters["sanitize"] = sanitize_html
# In templates: {{ content | sanitize }}

La biblioteca nh3 elimina etiquetas y atributos que no están en la lista permitida. Los enlaces reciben automáticamente rel="noopener noreferrer". Esta defensa es independiente del CSP — previene XSS almacenado en la capa de renderizado, mientras que CSP previene scripts inyectados en la capa del navegador. Defensa en profundidad.

Validación de entrada

Los modelos Pydantic validan toda la entrada en el límite de API:

from pydantic import BaseModel, Field, EmailStr

class ContactRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    email: EmailStr
    message: str = Field(..., min_length=10, max_length=5000)

FastAPI devuelve 422 Unprocessable Entity para entrada inválida automáticamente. Combinado con consultas parametrizadas de base de datos (SQLAlchemy nunca interpola cadenas), esto previene la inyección SQL y asegura la seguridad de tipos en los límites.

Rendimiento

Lighthouse 100/100/100/100

blakecrosley.com obtiene 100 en las cuatro categorías de Lighthouse: Rendimiento, Accesibilidad, Mejores Prácticas y SEO. Puedes verificarlo en PageSpeed Insights.²

Las optimizaciones clave:

Estrategia de carga de CSS

blakecrosley.com carga CSS con una sola etiqueta <link> y URLs con hash de contenido para caché inmutable:

<link rel="stylesheet" href="{{ asset('css/styles.css') }}">

El helper asset() añade un hash de contenido (?v=a3b2c1d4) para que el navegador almacene el archivo en caché indefinidamente hasta que el contenido cambie. Sin extracción de CSS crítico, sin trucos de print-media, sin carga basada en JavaScript. El archivo CSS pesa ~8KB comprimido con gzip, lo suficientemente pequeño para que el enfoque de solicitud única obtenga 100 en Lighthouse Performance sin acrobacias de optimización.

Compresión GZip

app.add_middleware(GZipMiddleware, minimum_size=500)

Las respuestas de más de 500 bytes se comprimen. HTML se comprime un 70-80%, reduciendo un documento de 15KB a 3-4KB.

Caché inmutable de recursos estáticos

# In security headers middleware
if request.url.path.startswith("/static/"):
    if os.environ.get("RAILWAY_ENVIRONMENT"):
        response.headers["Cache-Control"] = "public, max-age=31536000, immutable"

Los recursos estáticos con URLs de hash de contenido (?v=a3f8b2c1d0) se almacenan en caché durante un año con immutable. El hash cambia cuando el archivo cambia, obligando a los navegadores y CDNs a obtener la nueva versión.

Carga diferida de scripts

<script defer src="{{ asset('js/vendor/alpine.min.js') }}"></script>
<script defer src="{{ asset('js/vendor/htmx.min.js') }}"></script>
<script defer src="{{ asset('js/main.js') }}"></script>

El atributo defer descarga los scripts en paralelo con el análisis de HTML, pero los ejecuta después de que el documento se haya analizado. Esto evita el bloqueo del renderizado sin la complejidad de la carga asíncrona y la gestión del orden de ejecución.

Optimización de imágenes

Las imágenes usan WebP con srcset responsivo y dimensiones explícitas:

OPTIMIZED_IMAGES = {
    "vision-sprint": {
        "webp_srcset": (
            "/static/images/optimized/vision-sprint-400w.webp 400w, "
            "/static/images/optimized/vision-sprint-800w.webp 800w, "
            "/static/images/optimized/vision-sprint-1200w.webp 1200w"
        ),
        "fallback": "/static/images/optimized/vision-sprint-fallback.jpg",
        "width": 1200,
        "height": 1045,
    },
}

<picture>
  <source type="image/webp"
          srcset="{{ image.webp_srcset }}"
          sizes="(max-width: 768px) 100vw, 50vw">
  <img src="{{ image.fallback }}"
       width="{{ image.width }}"
       height="{{ image.height }}"
       alt="{{ image.alt }}"
       loading="lazy">
</picture>

Los atributos explícitos width y height previenen el Cumulative Layout Shift (CLS). El atributo loading="lazy" difiere las imágenes fuera de pantalla. WebP proporciona archivos entre un 25-35% más pequeños que JPEG con calidad equivalente.¹⁶

Early Hints

# In main.py
app.state.preload_links = [
    f'<{make_asset_url(_asset_map, "css/styles.css")}>; rel=preload; as=style',
]

# In security headers middleware
if "text/html" in content_type:
    preload_links = getattr(request.app.state, "preload_links", [])
    if preload_links:
        response.headers["Link"] = ", ".join(preload_links)

El encabezado Link con rel=preload le indica a Cloudflare que envíe una respuesta 103 Early Hints, permitiendo al navegador comenzar a obtener el CSS antes de que el servidor termine de generar la respuesta HTML.¹⁷

JavaScript mínimo

La huella total de JavaScript:

Una aplicación típica de React envía 100-300 KB de JavaScript del framework antes del código de la aplicación.¹⁸ El enfoque sin compilación envía menos JavaScript porque hay menos JavaScript que enviar.

Despliegue

Railway

blakecrosley.com se despliega en Railway mediante git push:

# railway.toml
[build]
builder = "nixpacks"

[deploy]
startCommand = "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}"
healthcheckPath = "/health"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10

El builder Nixpacks de Railway detecta el proyecto Python a partir de requirements.txt, instala las dependencias y ejecuta el comando de inicio. No se necesita Dockerfile. El endpoint de health check asegura que la aplicación responde antes de recibir tráfico:

@app.get("/health")
async def health():
    return {"status": "healthy"}

El pipeline de despliegue

git push origin main
  → Railway detects push
  → Nixpacks installs Python + requirements.txt (cached)
  → uvicorn starts
  → Health check passes
  → Traffic routes to new deployment
  → ~40 seconds total

Sin npm install. Sin npm run build. Sin compilación de webpack. Sin compilación de TypeScript. El único paso de instalación es pip install -r requirements.txt, que se almacena en caché entre despliegues.

Procfile

web: uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}

El Procfile proporciona una alternativa compatible con Heroku. Railway soporta tanto railway.toml como Procfile. La sintaxis ${PORT:-8000} usa el puerto proporcionado por la plataforma o usa 8000 por defecto para desarrollo local.

Configuración de producción de Uvicorn

Para despliegues con mayor tráfico, usa múltiples workers:

uvicorn app.main:app \
  --host 0.0.0.0 \
  --port ${PORT:-8000} \
  --workers 4 \
  --loop uvloop \
  --http httptools

• --workers 4 ejecuta cuatro procesos worker (regla general: 2 * núcleos de CPU + 1)
• --loop uvloop usa el event loop uvloop, más rápido (reemplazo directo de asyncio)
• --http httptools usa el parser HTTP httptools, más rápido

Para desarrollo, --reload vigila los cambios en archivos:

uvicorn app.main:app --reload --port 8000

Alternativa con Docker

Para plataformas que requieren Docker:

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

La imagen base slim mantiene el contenedor pequeño. --no-cache-dir evita que pip almacene los paquetes descargados en la capa de la imagen.

CDN de Cloudflare

blakecrosley.com usa Cloudflare para caché CDN, DNS y Workers:

# Cache headers for HTML pages (set in security middleware)
response.headers["Cache-Control"] = (
    "public, max-age=300, s-maxage=3600, "
    "stale-while-revalidate=86400"
)

• max-age=300 — el navegador almacena en caché por 5 minutos
• s-maxage=3600 — el CDN almacena en caché por 1 hora
• stale-while-revalidate=86400 — sirve contenido obsoleto mientras revalida durante 24 horas

Los recursos estáticos obtienen max-age=31536000, immutable porque las URLs con hash de contenido garantizan la frescura.

Marco de decisión

¿Necesitas herramientas de compilación?

Responde cuatro preguntas:

1. ¿Más de cinco desarrolladores comparten interfaces de JavaScript? Si la respuesta es sí, la verificación de tipos en tiempo de compilación de TypeScript previene errores de integración que las pruebas en tiempo de ejecución detectan demasiado tarde. Añade un paso de compilación.

2. ¿Tu aplicación gestiona estado complejo del lado del cliente? Si arrastrar y soltar, colaboración en tiempo real o datos offline-first son funciones centrales (no solo deseables), un framework como React o Svelte justifica su complejidad. Añade un paso de compilación.

3. ¿Múltiples productos consumen una biblioteca de componentes compartida? Si la respuesta es sí, esa biblioteca necesita empaquetado npm, versionado semántico y tree shaking. Añade un paso de compilación.

4. ¿Dependes de bibliotecas del ecosistema npm que asumen un bundler? Si Radix, Framer Motion, TanStack Query o bibliotecas similares son centrales para el producto, un pipeline de compilación es obligatorio.

Si las cuatro respuestas son “no”, el enfoque sin compilación es viable. Si alguna respuesta es “sí”, las herramientas de compilación resuelven un problema real. El error es añadir herramientas de compilación cuando las cuatro respuestas son “no”: resolver problemas que no tienes mientras creas sobrecarga de gestión de dependencias que sí tendrás.¹

Comparación de stacks

Cuándo HTMX no es la opción correcta

HTMX reemplaza el estado del cliente con viajes de ida y vuelta al servidor. Esto funciona hasta que la latencia importa:

• Interfaces de arrastrar y soltar — un viaje de ida y vuelta de 200ms al servidor por cada evento de arrastre es inaceptable
• Colaboración en tiempo real — el estado impulsado por WebSocket requiere resolución de conflictos del lado del cliente
• Aplicaciones offline-first — sin servidor significa sin HTMX
• Animaciones complejas vinculadas al estado — Framer Motion y React Spring asumen un modelo de reconciliación de React
• Aplicaciones Canvas/WebGL — el bucle de renderizado es inherentemente del lado del cliente

Para estos casos de uso, un framework del lado del cliente es la herramienta correcta. El enfoque sin compilación no intenta reemplazarlos.

Tarjeta de Referencia Rápida

FastAPI

# Development
source venv/bin/activate
uvicorn app.main:app --reload --port 8000

# Production
uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}

# Testing
python -m pytest -v --cov=app

# Database migrations
alembic upgrade head
alembic revision --autogenerate -m "description"

Atributos de HTMX

hx-get="/url"                     <!-- GET request -->
hx-post="/url"                    <!-- POST request -->
hx-target="#element"              <!-- Where to put response -->
hx-swap="innerHTML"               <!-- How to insert (innerHTML, outerHTML, beforeend) -->
hx-trigger="click"                <!-- What triggers request -->
hx-trigger="keyup changed delay:300ms"  <!-- Debounced input -->
hx-trigger="load"                 <!-- Fire on element load -->
hx-indicator="#spinner"           <!-- Show during request -->
hx-push-url="true"                <!-- Update browser URL -->
hx-replace-url="true"             <!-- Replace URL (no history) -->

Atributos de Alpine.js

x-data="{ open: false }"         <!-- Component scope + state -->
x-show="open"                    <!-- Toggle visibility -->
x-cloak                          <!-- Hide until Alpine inits -->
@click="open = !open"            <!-- Event handler -->
@click.away="open = false"       <!-- Outside click -->
@keydown.escape="open = false"   <!-- Keyboard event -->
:class="{ 'active': open }"      <!-- Dynamic class -->
:aria-expanded="open"            <!-- Dynamic attribute -->
x-text="count"                   <!-- Dynamic text content -->
x-init="fetchData()"             <!-- Run on init -->

Propiedades personalizadas de CSS

:root {
  --color-bg:     #000000;
  --color-text:   #ffffff;
  --spacing-sm:   1rem;
  --spacing-md:   1.5rem;
  --font-size-lg: 1.25rem;
}
@media (max-width: 768px) {
  :root { --gutter: 24px; }
}

Encabezados de seguridad

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-eval'
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Referrer-Policy: strict-origin-when-cross-origin
Cross-Origin-Opener-Policy: same-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()

Lista de verificación para configuración del proyecto

[ ] FastAPI app with Jinja2Templates
[ ] Security headers middleware (CSP, HSTS, X-Frame-Options)
[ ] CSRF token generation and validation
[ ] GZip middleware (minimum_size=500)
[ ] Content-hash asset versioning (cache busting)
[ ] HTMX self-hosted in /static/js/vendor/
[ ] Alpine.js self-hosted in /static/js/vendor/
[ ] CSS custom properties for design tokens
[ ] Health check endpoint (/health)
[ ] Error handlers (404, 500)
[ ] robots.txt, sitemap.xml, llms.txt
[ ] JSON-LD structured data in base template
[ ] Hreflang tags for i18n (if multi-language)
[ ] HTML sanitization filter (nh3)
[ ] Rate limiting middleware
[ ] Deferred script loading

Preguntas frecuentes

¿HTMX está listo para producción en aplicaciones web reales?

Sí. HTMX ha sido estable desde 2020 y se usa en producción en múltiples industrias. Carson Gross, su creador, mantiene la compatibilidad hacia atrás como principio fundamental de diseño — la documentación de HTMX establece que la biblioteca no romperá aplicaciones existentes dentro de una versión mayor.¹⁹ La biblioteca pesa 14KB minificada y comprimida con gzip, no tiene dependencias y sigue versionado semántico. blakecrosley.com ha ejecutado HTMX en producción durante tres años sin ningún bug relacionado con HTMX.

¿Puedo usar TypeScript sin un paso de compilación?

Parcialmente. Los archivos de TypeScript pueden verificarse con tsc --noEmit sin generar archivos de salida, lo que proporciona verificación en tiempo de compilación como un linter. No obstante, los navegadores no pueden ejecutar archivos .ts directamente, por lo que sigue siendo necesario un paso de compilación para servir TypeScript. La alternativa son las anotaciones de tipo JSDoc en archivos .js estándar, que TypeScript puede verificar sin compilación. Esto ofrece seguridad de tipos durante el desarrollo mientras se distribuye JavaScript estándar.

¿Cómo se compara este enfoque con Astro o 11ty?

Astro y 11ty son generadores de sitios estáticos que producen HTML plano con mínimo JavaScript en el cliente, pero requieren un paso de compilación (Node.js, npm install, un comando de build). El enfoque sin compilación elimina ese paso — el servidor renderiza HTML en cada solicitud. La compensación: Astro/11ty producen páginas estáticas más rápidas (sin computación en el servidor), mientras que FastAPI + HTMX maneja contenido dinámico de forma nativa (datos específicos del usuario, envíos de formularios, actualizaciones en tiempo real) sin una capa API separada.

¿Qué hay del renderizado del lado del servidor (SSR) con React?

Next.js SSR y el enfoque de FastAPI + HTMX comparten un objetivo: enviar HTML renderizado en el servidor al navegador. La diferencia está en lo que ocurre después del renderizado inicial. Next.js hidrata la página con React, enviando el runtime del framework y el código de componentes al cliente. FastAPI + HTMX no hidrata — el HTML es la salida final. HTMX maneja las interacciones posteriores solicitando nuevos fragmentos de HTML al servidor. El resultado: FastAPI + HTMX envía 30-40KB de JavaScript en total contra 100-300KB de una aplicación Next.js.¹⁸

¿Cómo manejo la validación de formularios con este stack?

Del lado del servidor. Pydantic valida la entrada cuando se envía el formulario. Si la validación falla, el servidor devuelve el formulario con mensajes de error. HTMX intercambia la respuesta en el DOM:

<form hx-post="/contact" hx-target="#form-container" hx-swap="outerHTML">
  <input type="email" name="email" required>
  <button type="submit">Send</button>
</form>

@router.post("/contact")
async def contact(request: Request, email: str = Form(...)):
    if not validate_email(email):
        return templates.TemplateResponse("components/_contact_form.html", {
            "request": request,
            "error": "Please enter a valid email address",
            "email": email,  # Preserve input
        })
    await send_email(email)
    return templates.TemplateResponse("components/_contact_success.html", {
        "request": request
    })

El servidor valida, el servidor renderiza los estados de error y HTMX intercambia el resultado. No se necesita una biblioteca de validación del lado del cliente. El atributo HTML required proporciona validación básica a nivel del navegador como primera línea de defensa.

¿Puedo agregar funciones en tiempo real (WebSockets)?

Sí. FastAPI tiene soporte integrado para WebSocket:

from fastapi import WebSocket

@app.websocket("/ws/notifications")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await get_notification()
        await websocket.send_text(render_notification_html(data))

HTMX tiene una extensión de WebSocket (hx-ws) que conecta elementos a endpoints WebSocket:

<!-- HTMX 2.x WebSocket extension syntax -->
<div hx-ext="ws" ws-connect="/ws/notifications">
  <div id="notifications" ws-send></div>
</div>

Nota: HTMX 1.x usaba la sintaxis hx-ws="connect:...". HTMX 2.x movió el soporte de WebSocket a una extensión separada (htmx-ext-ws) con los atributos ws-connect y ws-send mostrados arriba. Si usas HTMX 1.x, la sintaxis antigua hx-ws sigue funcionando.

Los mensajes del servidor se intercambian en el DOM usando los mismos mecanismos de targeting y swap que las respuestas HTTP. El servidor envía fragmentos de HTML a través del WebSocket y HTMX los inserta.

¿Cómo maneja este stack el SEO?

El HTML renderizado en el servidor es inherentemente amigable con el SEO porque los rastreadores reciben el contenido completo de la página sin ejecutar JavaScript. blakecrosley.com agrega varias capas de SEO:

• Datos estructurados JSON-LD en <head> para cada página (esquemas Person, Article, WebSite, FAQPage)
• Sitemap dinámico con alternativas hreflang para los 10 idiomas
• Feed RSS en /blog/feed.xml
• llms.txt en la raíz para la descubribilidad por rastreadores de IA
• URLs canónicas y etiquetas Open Graph en la plantilla base
• HTML semántico: <article>, <section>, <main>, jerarquía de encabezados adecuada

No se necesita configuración de SSR. No hay getStaticProps. No hay ISR. El HTML se renderiza en cada solicitud — ese es el comportamiento predeterminado, no una optimización.

¿Cuál es la curva de aprendizaje comparada con React?

Para desarrolladores de Python, la curva de aprendizaje es significativamente menor. Ya conoces el lenguaje. Los manejadores de rutas de FastAPI devuelven respuestas de plantilla — el mismo modelo mental que las vistas de Flask o Django. HTMX agrega un puñado de atributos HTML (hx-get, hx-target, hx-swap). Alpine.js agrega algunos más (x-data, x-show, @click). No hay JSX, no hay DOM virtual, no hay sistema de hooks, no hay biblioteca de gestión de estado ni configuración de herramientas de compilación que aprender.

La documentación de HTMX cabe en una sola página larga. La documentación de Alpine.js cabe en unas pocas páginas. La documentación de React abarca cientos de páginas cubriendo hooks, context, refs, effects, suspense, server components y streaming SSR.

Para desarrolladores de JavaScript/React, el cambio es conceptual más que sintáctico. La idea central es que el servidor posee el estado y el servidor renderiza el HTML. La gestión de estado del lado del cliente se convierte en manejo de rutas del lado del servidor. La obtención de datos del lado del cliente se convierte en atributos HTMX en elementos HTML. La sintaxis es más simple — el modelo mental requiere desaprender la suposición SPA de que el cliente controla el renderizado.

Registro de cambios

Referencias

Esta guía cubre el sistema completo utilizado para construir blakecrosley.com. El No-Build Manifesto proporciona el argumento filosófico. La publicación Lighthouse Perfect Score documenta el recorrido de optimización de rendimiento. La publicación Vibe Coding vs. Engineering explora dónde encaja el desarrollo asistido por IA en este flujo de trabajo.