Resumen rápido: FastAPI + HTMX + Alpine.js + Jinja2 + CSS simple permite crear aplicaciones web de producción sin herramientas de compilación, sin node_modules/ y con puntuaciones perfectas en Lighthouse. Esta guía cubre todo el sistema, desde la arquitectura hasta el despliegue, usando blakecrosley.com como referencia de producción que sirve 210 publicaciones de blog, componentes interactivos de JavaScript, 11 guías principales, 48 estudios de diseño e inglés más 9 configuraciones regionales traducidas sin un solo empaquetador, compilador ni transpilador.¹

El stack moderno de desarrollo web asume que necesitas React, webpack, TypeScript y un pipeline de compilación. Para una gran categoría de aplicaciones —sitios basados en contenido, herramientas internas, aplicaciones CRUD, sitios de portafolio, plataformas de documentación— esa suposición es incorrecta. El stack descrito en esta guía elimina toda la cadena de herramientas de compilación frontend y, al mismo tiempo, produce sitios que obtienen 100/100/100/100 en Lighthouse.²

Esto no es defensa de una idea. Es una medición. La arquitectura descrita aquí se ejecuta en producción, sirve a usuarios reales en diez idiomas y los números se pueden verificar.

Puntos clave

• El HTML renderizado en el servidor elimina tres categorías completas de problemas: gestión del estado del cliente, límites de serialización JSON y desajustes de hidratación. HTMX convierte las respuestas del servidor en el resultado 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 en npm install, sin errores del compilador TypeScript en archivos que no tocaste, sin PRs de Dependabot por dependencias transitivas que nunca importaste. La canalización de despliegue es git push.
• Alpine.js gestiona el estado exclusivo del cliente que HTMX no puede manejar. Menús desplegables, modales, alternancias de navegación móvil y cualquier estado de UI que existe únicamente en el navegador pertenecen a Alpine.js. El límite es claro: si el estado necesita el servidor, usa HTMX. Si no lo necesita, usa Alpine.js.
• CSS plano 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 los preprocesadores 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. Es incorrecto para equipos grandes que comparten interfaces de componentes, productos SaaS con estado complejo del lado del cliente y aplicaciones que dependen de bibliotecas del ecosistema npm. El marco de decisión en la Sección 15 identifica el límite con precisión.
• blakecrosley.com es la prueba. Los patrones centrales de esta guía (HTMX, Alpine.js, Jinja2, CSS plano) se ejecutan en producción en blakecrosley.com. Las secciones de Bootstrap y SQLAlchemy cubren patrones estándar para el 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 tú mismo en PageSpeed Insights.²

Cómo usar esta guía

Esta es una referencia exhaustiva. Empieza donde mejor 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 ofrece un resumen escaneable.

La tesis sin build

La tesis es estrecha y específica: para sitios orientados a contenido con un desarrollador en solitario o un equipo pequeño, las herramientas de compilación resuelven problemas que no tienes y, al mismo tiempo, crean problemas que sí tendrás.

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

Los 17 paquetes de Python incluyen FastAPI, Jinja2, Pydantic, uvicorn, nh3 y otros 12. Ninguno es una herramienta de compilación. Ninguno es un compilador. Ninguno es un empaquetador.⁵

A qué renuncias

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 en solitario. No funcionaría para un equipo de 10 personas que comparten interfaces de componentes.

Sin Hot Module Replacement. Los cambios en CSS requieren una recarga manual del navegador. El hx-boost de HTMX hace que la navegación sea lo suficientemente rápida para que las recargas completas sean tolerables, pero en ciclos ajustados de iteración visual, 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 grandes módulos de utilidades.

Sin bibliotecas de componentes de 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 sistema de diseño desde npm. El sistema de diseño vive en propiedades personalizadas de CSS. No se puede importar como un 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.⁶

Depura con Ver código fuente. El JavaScript que se ejecuta en el navegador es el JavaScript que escribiste. No se requieren source maps.

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

Cascada de solicitudes concreta. Una primera visita carga: un documento HTML (~15 KB comprimido con gzip), un archivo CSS (~8 KB), HTMX (~16 KB, en caché), Alpine.js (~15 KB, en caché) y el JS interactivo de la página (~4-8 KB). Total: aproximadamente 55-65 KB 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 hacia atrás durante 30 años.⁷ Sin migración de Webpack 4 a 5, sin obsolescencia de Create React App, sin migración al App Router de Next.js.

Comparación de stacks

Cómo se compara el stack sin build con alternativas comunes en dimensiones medibles:

Astro y 11ty son los competidores más cercanos para sitios de contenido. Ambos producen una excelente salida estática, pero requieren un paso de build y una cadena de herramientas de JavaScript. El stack FastAPI+HTMX intercambia el rendimiento de los sitios estáticos por interactividad del lado del servidor (filtrado por categorías, manejo de formularios, búsqueda en tiempo real) sin añadir un paso de build. 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.

FastAPI Patterns

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)

Aquí importan 3 decisiones de diseño. Primero, docs_url=None y openapi_url=None desactivan los endpoints automáticos de documentación de API. Un sitio de contenido público no necesita exponer /docs ni /openapi.json en internet.⁸ Segundo, el orden del middleware importa: el registro de seguridad se ejecuta primero (se agrega al final), así que captura cada solicitud, incluidas las que rechaza la limitación de tasa. Tercero, GZipMiddleware comprime todas las respuestas de más de 500 bytes, lo que normalmente reduce el tamaño de transferencia de HTML en un 70-80%.

Enrutamiento

Las rutas se separan en 2 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 dentro de elementos DOM existentes. El mismo motor de plantillas Jinja2 renderiza ambos casos: no hay una capa API separada.

Inyección de dependencias

El sistema Depends() de FastAPI ofrece 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. Una dependencia get_db puede depender de get_current_locale, que a su vez depende de la solicitud. FastAPI resuelve la cadena automáticamente.

Configuración con Pydantic

La configuración usa 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 sobrescriben los valores del archivo .env. En producción (Railway), los secretos se definen como variables de entorno. En local, un archivo .env proporciona valores predeterminados. La clase Settings valida los tipos al iniciar: si falta un campo obligatorio, falla rápido en lugar de fallar en tiempo de ejecución.

Patrones async

Las rutas de FastAPI son async de forma predeterminada. Para operaciones ligadas a I/O (consultas a bases de datos, solicitudes HTTP, lecturas 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)

Lifespan ahora es la única ruta de startup/shutdown. Starlette llegó a su primera versión estable, 1.0, en marzo de 2026 (1.3.1 al 12 de junio) y eliminó los hooks on_event, on_startup y on_shutdown, obsoletos desde hacía mucho tiempo: lifespan (arriba) es el único mecanismo, y @app.route() / @app.websocket_route() dieron paso a Route / WebSocketRoute en la lista routes. FastAPI 0.137.0 (14 de junio de 2026) fija Starlette en la línea 1.x y refactoriza los elementos internos de su propio router: router.routes ya no es una lista plana de objetos APIRoute, sino un árbol de nodos intermedios, así que trátalo como un detalle interno en lugar de algo para iterar. La ventaja es que las rutas agregadas a un router después de include_router() ahora se reflejan en vivo, y un sub-router puede incluirse antes de que sus rutas estén definidas.²⁴ Nada de esto cambia los patrones de esta guía, que usa lifespan y declaración estándar de rutas en todo momento, pero si mantienes herramientas que recorren router.routes, o todavía ejecutas manejadores heredados @app.on_event, 0.137.0 / Starlette 1.0 introducen cambios incompatibles. FastAPI 0.137.2 (18 de junio de 2026) continúa con iter_route_contexts(), la forma compatible de enumerar rutas ahora que router.routes es interno. Luego, FastAPI 0.138.0 (20 de junio de 2026) agrega app.frontend("/", directory="dist") / router.frontend(...) para servir un frontend estático compilado; es útil si publicas una compilación SPA separada, pero es independiente del enfoque de esta guía, sin build y renderizado en servidor (monta un directorio dist/ en lugar de renderizar HTML en el servidor).²⁵

Las operaciones ligadas a CPU (renderizado de Markdown, extracción de CSS) pueden usar funciones síncronas. FastAPI las ejecuta automáticamente en un thread pool 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: si la función espera I/O, hazla async. Si hace 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 async estándar de SQLAlchemy 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 limpiamente 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

Nota de instalación (SQLAlchemy 2.0.50+): a partir de la versión 2.0.50, la dependencia greenlet del stack async ya no se instala de forma predeterminada. Usa el extra asyncio para que se incluya, o el primer await contra el engine fallará con un error de greenlet faltante:²³

pip install "sqlalchemy[asyncio]" aiosqlite

SQLAlchemy 2.0.50 también requiere Python 3.10+ (se eliminó el soporte para 3.7–3.9) y agrega wheels free-threaded (3.13t).²³

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 administra el ciclo de vida de la sesión: abre una sesión, la cede al route handler, confirma los cambios si todo sale bien y revierte la transacción si hay una excepción. Cada operación de base de datos usa consultas parametrizadas; nunca interpolación de strings.

Integración con Pydantic

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

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 route handler. Una entrada inválida devuelve automáticamente una respuesta 422. Esto reemplaza las bibliotecas de validación de formularios del lado del cliente: el servidor valida, y HTMX inserta el mensaje de éxito o la retroalimentación del error.

Migraciones con Alembic

Alembic administra 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 autogenerate compara los modelos de SQLAlchemy con 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 garantiza que el esquema de la base de datos coincida con el código de la aplicación. Para blakecrosley.com, la mayoría de los datos vive 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 analytics.

El patrón Cloudflare D1

blakecrosley.com usa Cloudflare D1 como una base de datos remota a la que se accede mediante un proxy de Cloudflare Worker:

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, con acceso vía HTTP. El proxy Worker maneja la autenticación y la limitación de tasa. El costo es la latencia: cada consulta es una solicitud HTTP (~50-100ms), frente a una conexión a 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

La CSP incluye 'unsafe-inline' y 'unsafe-eval' porque Alpine.js los requiere para evaluar expresiones. La alternativa es la versión compatible con CSP de Alpine.js, que tiene limitaciones.¹⁴ Todas las demás funciones quedan restringidas: frame-ancestors evita el clickjacking, form-action limita los envíos de formularios al mismo origen y upgrade-insecure-requests fuerza HTTPS.

Seguridad de caché en CDN con HTMX

El middleware de encabezados de seguridad agrega Vary: HX-Request a las respuestas de 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 almacenar en caché una respuesta de fragmento de HTMX y servirla como página completa ante una solicitud que no sea de HTMX (o al revés). El encabezado Vary le indica al CDN que guarde entradas de caché separadas según el valor del encabezado HX-Request.¹¹

Protección CSRF

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

# 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 la plantilla mediante un global de Jinja2 y se incluye en las solicitudes de formulario de 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 en el servidor. La firma HMAC garantiza que el token fue generado por el servidor. La marca de tiempo evita ataques de repetición. hmac.compare_digest evita ataques de temporización.¹⁵

Sanitización de HTML

El contenido generado por usuarios pasa por nh3 antes de renderizarse:

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 de CSP: evita XSS almacenado en la capa de renderizado, mientras que CSP evita scripts inyectados en la capa del navegador. Defensa en profundidad.

Validación de entradas

Los modelos Pydantic validan todas las entradas 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 automáticamente 422 Unprocessable Entity cuando la entrada no es válida. Combinado con consultas de base de datos parametrizadas (SQLAlchemy nunca interpola cadenas), esto evita la inyección SQL y garantiza seguridad de tipos en los límites.

Rendimiento

Lighthouse 100/100/100/100

blakecrosley.com obtiene 100 en las cuatro categorías de Lighthouse: Performance, Accessibility, Best Practices y SEO. Verifícalo 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() agrega un hash de contenido (?v=a3b2c1d4) para que el navegador almacene el archivo en caché indefinidamente hasta que el contenido cambie. Sin extracción crítica de CSS, sin truco de print-media, sin carga basada en JavaScript. El archivo de CSS pesa ~8 KB comprimido con gzip: lo bastante pequeño como para que el enfoque de una sola solicitud obtenga 100 en Lighthouse Performance sin malabares 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 entre 70 y 80%, lo que reduce un documento de 15 KB a 3-4 KB.

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 con hash de contenido (?v=a3f8b2c1d0) se almacenan en caché durante un año con immutable. El hash cambia cuando cambia el archivo, lo que obliga a los navegadores y CDN 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 scripts en paralelo con el análisis de HTML, pero los ejecuta después de que el documento se haya analizado. Esto evita bloquear el renderizado sin la complejidad de la carga async ni de gestionar el 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 evitan Cumulative Layout Shift (CLS). El atributo loading="lazy" difiere las imágenes fuera de pantalla. WebP ofrece archivos entre 25 y 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, lo que permite que el navegador empiece a obtener CSS antes de que el servidor termine de generar la respuesta de HTML.¹⁷

JavaScript mínimo

La huella total de JavaScript:

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

Implementación

Railway

blakecrosley.com se implementa 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 desde requirements.txt, instala las dependencias y ejecuta el comando de inicio. No se requiere archivo Docker. El endpoint de verificación de estado asegura que la aplicación responda antes de recibir tráfico:

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

El pipeline de implementación

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 queda en caché entre implementaciones.

Procfile

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

El Procfile ofrece una alternativa compatible con Heroku. Railway admite tanto railway.toml como Procfile. La sintaxis ${PORT:-8000} usa el puerto proporcionado por la plataforma o, de forma predeterminada, 8000 para el desarrollo local.

Configuración de producción de Uvicorn

Para implementaciones con más tráfico, usa varios 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 observa cambios en los 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 pequeño el contenedor. --no-cache-dir evita que pip almacene paquetes descargados en la capa de la imagen.

CDN de Cloudflare

blakecrosley.com usa Cloudflare para caché de 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é durante 5 minutos
• s-maxage=3600 — la CDN almacena en caché durante 1 hora
• stale-while-revalidate=86400 — sirve contenido obsoleto mientras se revalida durante 24 horas

Los assets estáticos reciben max-age=31536000, immutable porque las URL con hash de contenido garantizan frescura.

Marco de decisión

¿Necesitas herramientas de build?

Responde cuatro preguntas:

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

2. ¿Tu aplicación administra estado complejo del lado cliente? Si arrastrar y soltar, la colaboración en tiempo real o los datos offline-first son funciones centrales (no simples extras deseables), un framework como React o Svelte justifica su complejidad. Agrega un paso de build.

3. ¿Varios productos consumen una biblioteca de componentes compartida? Si la respuesta es sí, esa biblioteca necesita empaquetado npm, versionado semántico y tree shaking. Agrega un paso de build.

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 build es obligatorio.

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

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 al servidor de 200 ms por evento de arrastre es inaceptable
• Colaboración en tiempo real — el estado impulsado por WebSocket requiere resolución de conflictos del lado cliente
• Aplicaciones offline-first — sin servidor no hay HTMX
• Animaciones complejas vinculadas al estado — Framer Motion y React Spring asumen un modelo de reconciliación de React
• Aplicaciones Canvas/WebGL — el loop de renderizado es inherentemente del lado cliente

Para estos casos de uso, un framework del lado cliente es la herramienta correcta. El enfoque sin build 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 -->

Custom Properties 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=()

Checklist de 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 es 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 central de diseño: la documentación de HTMX indica que la biblioteca no romperá aplicaciones existentes dentro de una versión principal.¹⁹ La biblioteca pesa alrededor de 16 KB minificada y comprimida con gzip, no tiene dependencias y sigue versionado semántico. blakecrosley.com ha usado HTMX en producción durante tres años sin ningún bug relacionado con HTMX.²⁰

¿Puedo usar TypeScript sin un paso de build?

Parcialmente. Los archivos de TypeScript se pueden verificar con tsc --noEmit sin generar archivos de salida, lo que ofrece validación en tiempo de compilación como si fuera un linter. Sin embargo, los navegadores no pueden ejecutar archivos .ts directamente, así que sigue siendo necesario un paso de build para servir TypeScript. La alternativa es usar anotaciones de tipos JSDoc en archivos .js planos, que TypeScript puede verificar sin compilación. Esto te da seguridad de tipos durante el desarrollo mientras publicas 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 un mínimo de JavaScript en el cliente, pero requieren un paso de build (Node.js, npm install, un comando de build). El enfoque sin build elimina ese paso: el servidor renderiza HTML en cada solicitud. La diferencia: Astro/11ty producen páginas estáticas más rápidas (sin cómputo del 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 separada de API.

¿Qué pasa con el server-side rendering (SSR) con React?

Next.js SSR y el enfoque FastAPI + HTMX comparten un objetivo: enviar HTML renderizado por el servidor al navegador. La diferencia está en lo que ocurre después del render inicial. Next.js hidrata la página con React, enviando al cliente el runtime del framework y el código de los componentes. 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 aproximadamente 35-40 KB de JavaScript en total, frente a 100-300 KB para 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 dentro del 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 necesitas una biblioteca de validación del lado del cliente. El atributo required de HTML ofrece 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 con endpoints de 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 que se muestran arriba. Si usas HTMX 1.x, la sintaxis antigua hx-ws todavía funciona.

Ruta beta de HTMX 4.0: htmx 4.0.0-beta4 ahora está en la etiqueta next de npm y en la documentación 4.0, mientras que el inicio rápido de htmx.org y la etiqueta latest de npm siguen en 2.0.10. Esta guía todavía apunta a HTMX 2.x, que sigue siendo la versión recomendada para trabajo en producción hasta que 4.0 sea estable; la migración de 2.x a 4.x es un salto generacional, no una actualización menor de 2.x. El patrón de versionado de big-skies-software omite versiones principales impares, así que 4.0 es el siguiente paso después de 2.x.²¹²²

Vale la pena seguir esto en la documentación 4.0. Hay dos incorporaciones que destacan para revisión de seguridad y arquitectura antes de 4.0 GA: la nueva extensión hx-live introduce expresiones reactivas al DOM que se vuelven a evaluar cuando cambia el estado referenciado, y la nueva extensión hx-nonce controla el procesamiento de atributos de htmx mediante nonces de CSP. La guía de migración 4.0 también mueve varios conceptos de configuración, restaura o cambia algunos comportamientos de eventos e historial, y elimina algunos helpers de JavaScript del núcleo. Trata 4.0 como un proyecto de migración, no como un parche directo de 2.x.²¹

Los mensajes del servidor se intercambian dentro del DOM usando la misma mecánica de destino e intercambio que las respuestas HTTP. El servidor envía fragmentos de HTML por el WebSocket, y HTMX los inserta.

¿Cómo maneja este stack el SEO?

El HTML renderizado por el servidor es inherentemente favorable para SEO porque los crawlers 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 alternates hreflang para los 10 locales
• RSS feed en /blog/feed.xml
• llms.txt en la raíz para facilitar el descubrimiento por crawlers de AI
• URLs canónicas y etiquetas Open Graph en la plantilla base
• HTML semántico: <article>, <section>, <main>, jerarquía adecuada de encabezados

No necesitas configuración de SSR. No getStaticProps. No 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 considerablemente menor. Ya conoces el lenguaje. Los route handlers de FastAPI devuelven respuestas de plantilla: el mismo modelo mental que las vistas de Flask o Django. HTMX agrega un puñado de atributos de HTML (hx-get, hx-target, hx-swap). Alpine.js agrega algunos más (x-data, x-show, @click). No hay JSX, DOM virtual, sistema de hooks, biblioteca de gestión de estado ni configuración de herramientas de build 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 sobre 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 de HTMX en elementos HTML. La sintaxis es más simple; el modelo mental exige desaprender la suposición de las SPA de que el cliente controla el renderizado.

Registro de cambios

Referencias

Esta guía cubre el sistema completo usado para crear blakecrosley.com. The No-Build Manifesto presenta el argumento filosófico. La publicación Puntuación perfecta en Lighthouse documenta el recorrido de optimización de rendimiento. La publicación Vibe Coding vs. Engineering explora dónde encaja el desarrollo asistido por AI en este flujo de trabajo.