DEV Community: Juan Torchia

Swiper: the touch slider that won't wreck your sprint

Juan Torchia — Sat, 11 Jul 2026 12:02:19 +0000

This is entry #10 of Awesome Curated: The Tools, the series where I dissect the tools that make it through our automated curation system. Today's subject looks simple on the surface but has a lot more depth than you'd expect.

There's a moment in every web developer's career when the client — or the designer, or the product manager — says: "we need a carousel here." And something dies inside you. Not because it's technically hard, but because you know exactly what's coming: three days hunting for the right library, five outdated tutorials, a custom implementation that breaks on Samsung Internet, and finally, at 11pm, realizing that touch on iOS feels like dragging a brick across sandpaper.

That happened to me in 2022, on an e-commerce project with a product catalog that had to work as a carousel on mobile. I tried three libraries before landing on Swiper. The first two had touch behavior that felt like it was pulled from 2013. The third one worked fine but required jQuery — in 2022, jQuery. When I finally opened the Swiper docs and saw the official React wrapper with lazy loading built-in and GPU acceleration, my only thought was: why didn't I start here?

What it does

Swiper is the most complete touch slider/carousel library in the modern web ecosystem. Zero external dependencies. Official wrappers for React, Vue, Angular, and Web Components. Hardware-accelerated transitions that feel native on both iOS and Android.

We're not talking about a glorified jQuery plugin. Swiper has its own module system that you can import selectively: pagination, arrow navigation, image lazy loading, autoplay, thumbnails, parallax effects, zoom, and a dozen transition styles (fade, cube, flip, cards). All of that without dragging half a third-party library into your bundle.

The React API is declarative and pretty clean:

import { Swiper, SwiperSlide } from 'swiper/react';
// Import only the modules we need — key to keeping the bundle lean
import { Navigation, Pagination, Lazy } from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';

function ProductCarousel({ products }) {
  return (
    <Swiper
      modules={[Navigation, Pagination, Lazy]}
      spaceBetween={16}       // space between slides in px
      slidesPerView={1.2}     // peek at the next slide — classic mobile UX pattern
      navigation                // prev/next arrows
      pagination={{ clickable: true }}
      lazy={true}              // native lazy loading — don't load images outside the viewport
      breakpoints={{
        // show more slides on desktop — responsive without extra media queries
        768: { slidesPerView: 2.5 },
        1200: { slidesPerView: 3.5 },
      }}
    >
      {products.map((p) => (
        <SwiperSlide key={p.id}>
          <img
            data-src={p.image}   // data-src for lazy loading
            className="swiper-lazy"
            alt={p.name}
          />
          <p>{p.name}</p>
        </SwiperSlide>
      ))}
    </Swiper>
  );
}

The CSS is modular too. If you're not using the scrollbar module, you don't import the scrollbar CSS. Simple as that.

Under the hood, Swiper uses transform: translate3d() and will-change to force the browser to hand off animations to the GPU. The result is that touch scrolling has real inertia — with physical deceleration that respects the OS parameters — instead of the robotic behavior you get with pure CSS or most alternatives.

The official docs live at swiperjs.com and the GitHub repo has over 39k stars. This isn't recent hype — that consensus has been building for years.

Why it made the list

Swiper showed up in 4 independent awesome lists. When a specific UI component — not a framework, not a general-purpose library, but a slider — reaches that level of consensus, it's doing something right.

The difference between Swiper and alternatives like Keen-Slider or Embla Carousel isn't that Swiper is objectively better at everything — Embla is noticeably lighter. The difference is that Swiper has the most complete official wrappers, the most exhaustive documentation, and multi-framework support without needing third-party adapters. If you work on a team where there are simultaneous projects in React, Vue, and Angular, having one library that behaves identically across all three is a genuine asset.

The module system matters too. Before Swiper got this right, the recurring complaint was bundle size. Today, if you import only Navigation and Pagination and nothing else, the bundle impact is much more reasonable. The ~30kb gzip figure that gets thrown around is for the full package with every effect and module included.

And — this is something I genuinely appreciate after living through some painful migrations over 30 years — the team publishes detailed changelogs and migration guides between major versions. The API changed significantly from v6 to v8 and from v8 to v11, sure, but they don't leave you to figure it out alone.

When NOT to use it

Honest first case: if your carousel has three static slides and you don't need touch, Swiper is probably overkill. That's what pure CSS with scroll-snap-type is for. Zero JavaScript, zero dependencies, native support in every modern browser:

/* A basic touch carousel with CSS only — no JS */
.carousel {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;  /* snap to the nearest slide */
  -webkit-overflow-scrolling: touch; /* inertia on iOS */
  gap: 16px;
}

.carousel-slide {
  scroll-snap-align: start;  /* each slide snaps from the start */
  flex: 0 0 80%;             /* each slide takes up 80% of the width */
}

Second case: if performance is critical and bundle size is genuinely painful, look at Embla Carousel. It's smaller, more extensible by design, and takes the "bring only what you need" philosophy to its logical extreme. The trade-off is that the API is lower-level and requires more configuration for things that in Swiper are a single prop.

Third case, and this is the most important one: question whether you actually need a carousel at all. There's substantial UX evidence suggesting that carousels reduce engagement on landing pages. Not because Swiper is the problem — the pattern itself can be the problem. When a client asks for a carousel, ask what problem they're actually trying to solve. Sometimes there's a better answer.

Closing

Swiper made it through the curation system's filter for the right reasons: real community consensus, active maintenance, and a clear value proposition that holds up under technical scrutiny. It's not magic, but it does what it promises better than almost any alternative.

This is entry #10 of Awesome Curated: The Tools. If you landed here directly and missed the rest of the series, there are posts worth checking out: the one on Sniffnet for network monitoring and the one on Node.js we kicked off last week are solid entry points if you're interested in the tooling ecosystem beyond ML. The next post in the series follows the same criteria: a tool that appeared in multiple lists, passed the automated filter, and that I reviewed personally before writing a single word about it.

This article was originally published on juanchi.dev

Swiper: el slider táctil que no te va a arruinar el sprint

Juan Torchia — Sat, 11 Jul 2026 12:02:14 +0000

Esta es la entrega #10 de Awesome Curated: The Tools, la serie donde disecciono las herramientas que pasan el filtro de nuestro sistema de curación automático. Hoy le toca a algo que parece simple pero que tiene más profundidad de la que se ve a primera vista.

Hay un momento en la carrera de todo desarrollador web donde el cliente —o el diseñador, o el product manager— te dice: "necesitamos un carousel acá". Y en ese momento, algo muere adentro tuyo. No porque sea difícil técnicamente, sino porque sabés lo que viene: tres días buscando la librería correcta, cinco tutoriales desactualizados, una implementación propia que queda rota en Samsung Internet, y finalmente, a las 11 de la noche, dándote cuenta de que el touch en iOS se siente como arrastrar un ladrillo.

Me pasó en 2022, trabajando en un proyecto de e-commerce con un catálogo de productos que tenía que funcionar como carrusel en mobile. Probé tres librerías antes de llegar a Swiper. Las primeras dos tenían comportamiento táctil que parecía sacado de 2013. La tercera funcionaba bien pero requería jQuery. Cuando finalmente abrí la doc de Swiper y vi el wrapper oficial para React, con lazy loading built-in y aceleración por GPU, pensé: ¿por qué no empecé acá?

Qué hace

Swiper es la librería de sliders/carousels táctiles más completa del ecosistema web moderno. Cero dependencias externas. Wrappers oficiales para React, Vue, Angular y Web Components. Transiciones aceleradas por hardware que en iOS y Android se sienten como si fueran nativas.

No estamos hablando de un jQuery plugin glorificado. Swiper tiene su propio sistema de módulos que podés importar selectivamente: paginación, navegación con flechas, lazy loading de imágenes, autoplay, thumbnails, efectos de parallax, zoom, y una docena de transiciones (fade, cube, flip, cards). Todo esto sin meter media librería de terceros en el bundle.

La API en React es declarativa y bastante limpia:

import { Swiper, SwiperSlide } from 'swiper/react';
// Importamos solo los módulos que necesitamos — clave para no inflar el bundle
import { Navigation, Pagination, Lazy } from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';

function ProductCarousel({ productos }) {
  return (
    <Swiper
      modules={[Navigation, Pagination, Lazy]}
      spaceBetween={16}       // espacio entre slides en px
      slidesPerView={1.2}     // mostramos un poco del próximo slide (patrón UX clásico en mobile)
      navigation                // flechas prev/next
      pagination={{ clickable: true }}
      lazy={true}              // lazy loading nativo — no cargamos imágenes fuera del viewport
      breakpoints={{
        // en desktop mostramos más slides — responsive sin media queries extra
        768: { slidesPerView: 2.5 },
        1200: { slidesPerView: 3.5 },
      }}
    >
      {productos.map((p) => (
        <SwiperSlide key={p.id}>
          <img
            data-src={p.imagen}   // data-src para lazy loading
            className="swiper-lazy"
            alt={p.nombre}
          />
          <p>{p.nombre}</p>
        </SwiperSlide>
      ))}
    </Swiper>
  );
}

El CSS lo podés importar modularmente también. Si no usás el módulo de scrollbar, no importás el CSS de scrollbar. Simple.

Por abajo, Swiper usa transform: translate3d() y will-change para forzar que el navegador delegue las animaciones a la GPU. El resultado es que el scroll táctil tiene inercia real —con deceleración física que respeta los parámetros del sistema operativo— en lugar del comportamiento robótico que tenés con CSS puro o la mayoría de las alternativas.

El sitio oficial con la documentación completa está en swiperjs.com y el repo en GitHub tiene más de 39k estrellas. No es hype reciente: lleva años acumulando ese consenso.

Por qué está en la lista

Swiper apareció en 4 awesome lists independientes. Cuando un componente de UI específico —no un framework, no una librería de propósito general, sino un slider— logra ese nivel de consenso, algo está haciendo bien.

La diferencia con alternativas como Keen-Slider o Embla Carousel no es que Swiper sea objetivamente mejor en todo —Embla es notablemente más liviano— sino que Swiper tiene los wrappers oficiales más completos, la documentación más exhaustiva, y el soporte multi-framework sin necesitar adaptadores de terceros. Si trabajás en un equipo donde hay proyectos en React, Vue y Angular simultáneamente, tener una sola librería que funciona igual en los tres es un activo real.

El sistema de módulos también importa. Antes de que Swiper lo implementara bien, la queja recurrente era el bundle size. Hoy, si importás solo Navigation y Pagination sin nada más, el impacto en el bundle es mucho más razonable. El ~30kb gzip que figura como número de referencia es para el paquete completo con todos los efectos y módulos.

Además —y esto es algo que aprecio mucho como alguien que vivió migraciones dolorosas— el equipo publica changelogs detallados y guías de migración entre versiones mayores. La API cambió bastante de v6 a v8 y de v8 a v11, sí, pero no te dejan solos en el proceso.

Cuándo NO usarlo

Primer caso honesto: si tu carousel tiene tres slides fijos y no necesitás touch, probablemente Swiper sea overkill. Para eso existe CSS puro con scroll-snap-type. Cero JavaScript, cero dependencias, soporte nativo en todos los browsers modernos:

/* Un carousel básico táctil solo con CSS — sin JS */
.carousel {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;  /* snap al slide más cercano */
  -webkit-overflow-scrolling: touch; /* inercia en iOS */
  gap: 16px;
}

.carousel-slide {
  scroll-snap-align: start;  /* cada slide hace snap desde el inicio */
  flex: 0 0 80%;             /* cada slide ocupa el 80% del ancho */
}

Segundo caso: si el performance es crítico y el bundle size te duele, mirá Embla Carousel. Es más pequeño, más extensible por diseño, y tiene una filosofía de "traé solo lo que necesitás" llevada al extremo. La contra es que la API es más de bajo nivel y requiere más configuración para cosas que en Swiper son un prop.

Tercer caso, el más importante: cuestioná si realmente necesitás un carousel. Hay bastante evidencia de UX que sugiere que los carousels reducen el engagement en landing pages. No porque Swiper sea el problema, sino porque el patrón mismo puede ser problemático. Si el cliente te pide un carousel, preguntá qué problema quiere resolver — a veces hay una respuesta mejor.

Cierre

Swiper pasó el filtro del sistema de curación por las razones correctas: consenso real de la comunidad, mantenimiento activo, y una propuesta de valor clara que resiste el escrutinio técnico. No es magia, pero hace lo que promete mejor que casi cualquier alternativa.

Esta es la entrega #10 de Awesome Curated: The Tools. Si llegaste acá directo y no viste el resto de la serie, hay posts que vale la pena revisar: el de Sniffnet para monitoreo de red y el de Node.js que arrancamos la semana pasada son buenos puntos de entrada si te interesa el ecosistema de herramientas más allá del ML. El próximo post de la serie sigue el mismo criterio: una herramienta que apareció en múltiples listas, que pasó el filtro automatizado, y que yo revisé personalmente antes de escribir una sola palabra sobre ella.

Este artículo fue publicado originalmente en juanchi.dev

Node.js: the runtime that changed how we think about backend

Juan Torchia — Wed, 08 Jul 2026 12:01:59 +0000

It was 2012 and I was buried up to my ears in Linux servers, babysitting LAMP stacks that crawled under load. A colleague dropped a benchmark on my desk: a Node.js server handling 10,000 concurrent connections with a single process consuming less memory than Apache under 500. I read it three times. I was sure it was wrong. It wasn't wrong.

I didn't adopt it then — I stayed in my world of infrastructure and Java. But the seed was planted. When I made my definitive pivot to software development in 2021, Node was everywhere. And when I truly understood it — not just how to use it but why it works the way it does — everything clicked. I finally got why it had made so much noise.

This is post #9 in the Awesome Curated: The Tools series, where I dig into tools that pass the filter of our automated curation system. Node.js came up through Sindre Sorhus's awesome-nodejs list — which is basically a universe unto itself — and crossed with a signal in 4 independent awesome lists. That doesn't happen by accident.

What it does

Node.js is a JavaScript runtime built on Chrome's V8 engine, but that's the boring technical description. What makes it special is the non-blocking event loop. In a traditional web server, every incoming request waits: waits for the database to respond, waits for the disk to read a file, waits for the network to return something. While it waits, that thread is blocked — sitting there doing absolutely nothing useful. Multiply that by thousands of connections and you understand why you needed 64GB of RAM just to run a decent server.

Node flips the model. When you kick off an I/O operation, Node registers a callback and moves on. When the disk finishes reading, when the DB responds, when the socket has data — Node knows, and executes what comes next. A single thread managing thousands of in-flight operations simultaneously. It's not magic, it's a different mental model.

// The traditional model (blocking): you wait at every step
// The Node model: you register what you want to happen WHEN something is ready

const fs = require('fs');
const http = require('http');

const server = http.createServer((req, res) => {
  // This does NOT block the event loop
  // Node keeps handling other requests while the disk reads
  fs.readFile('./data.json', 'utf8', (err, data) => {
    if (err) {
      res.writeHead(500);
      res.end('Something blew up');
      return;
    }
    // Only now do we respond, when the data is actually available
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(data);
  });
});

server.listen(3000, () => {
  console.log('Listening on port 3000');
});

Modern async/await syntax makes this a lot more readable today:

const fs = require('fs').promises;
const http = require('http');

const server = http.createServer(async (req, res) => {
  try {
    // Await doesn't block the event loop — it releases the thread while it waits
    // Other requests keep getting processed in parallel
    const data = await fs.readFile('./data.json', 'utf8');

    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(data);
  } catch (err) {
    res.writeHead(500);
    res.end(JSON.stringify({ error: 'Could not read the file' }));
  }
});

server.listen(3000);

The npm ecosystem is a whole other beast. Over 2 million packages. It's simultaneously an absurd superpower and a security nightmare vector (left-pad, event-stream, the ghosts of the past). But the point is: for almost anything you need, there's a library. You can find the official repository here and Sindre Sorhus's awesome-nodejs here — that second URL is practically a map of the entire ecosystem.

Why it's on the list

Four independent awesome lists pointing at Node.js is community consensus, not hype. And it makes sense: Node solved a real problem that backend development had pre-2009 — the C10K problem, the difficulty of handling 10,000 concurrent connections with traditional servers. Ryan Dahl didn't invent the event loop, but he took an idea that already existed in Nginx and put it in the hands of JavaScript developers, who were already tens of millions strong.

The most important unlock was unifying the language. Before Node, if you were a web dev, you knew JavaScript in the browser and something else (PHP, Ruby, Java) on the server. With Node, same language, same paradigms, same team. That had an enormous organizational impact that you can still feel today in the job market.

Compared to contemporary alternatives: Go wins on raw performance and simplicity of its concurrency model. Python with FastAPI or Django is more readable for many use cases. Java with Spring Boot — my current world — has enterprise maturity and tooling that Node is still building toward. But none of them have the npm ecosystem, none of them have such a low barrier to entry for someone who already knows JavaScript, and none of them moved the developer tooling market as fast — Webpack, Babel, ESLint, Prettier, they all run on Node.

When NOT to use it

If you've got CPU-bound workloads — image processing, heavy cryptography, machine learning, compilation — Node will let you down. The event loop is brilliant for concurrent I/O, but the single thread becomes a bottleneck the moment there's serious computation involved. Worker Threads mitigate this, but at that point you're fighting against the runtime's own design. For those cases, Python with multiprocessing, Go, or Java are more natural fits.

Memory leaks are more frequent and harder to debug than in compiled languages. V8's garbage collector is good, but if you don't deeply understand the model of closures and circular references, you'll watch processes grow in memory without stopping until they explode in production at 3am. I'm speaking from personal experience. Also: if your team doesn't have solid experience with async programming, callback hell and the subtle bugs of async/await can produce code that's genuinely painful to maintain. In those cases, a more opinionated framework like Spring Boot or Django might be healthier in the long run.

Closing thoughts

Node.js is one of those tools that permanently changed the ecosystem. Not because it's perfect — it isn't — but because it arrived at exactly the right moment with exactly the right idea, and pulled millions of developers along with it. Thirty years of watching technology come and go taught me to tell the difference between hype that fades and real change. Node is the latter.

If this post was useful, the Awesome Curated: The Tools series has 8 more posts where I analyze tools with the same lens. From cryptography with Themis to network monitoring with Sniffnet — each one passed the same curation filter before landing here. The next one will too.

This article was originally published on juanchi.dev

Node.js: el runtime que cambió cómo pensamos el backend

Juan Torchia — Wed, 08 Jul 2026 12:01:54 +0000

Corría 2012 y yo estaba metido hasta las orejas en servidores Linux, administrando stacks LAMP que respondían lento bajo carga. Un colega me pasó un benchmark: un servidor Node.js manejando 10.000 conexiones concurrentes con un proceso que consumía menos memoria que un Apache con 500. Lo miré tres veces. Pensé que era mentira. No era mentira.

En ese momento no lo adopté — seguí con mi mundo de infraestructura y Java. Pero la semilla quedó. Cuando en 2021 hice el pivot definitivo al desarrollo de software, Node estaba en todos lados. Y cuando lo entendí de verdad — no solo cómo usarlo sino por qué funciona así — me cayó la ficha de por qué había generado tanto ruido.

Este es el post #9 de la serie Awesome Curated: The Tools, donde analizo herramientas que pasan el filtro de nuestro sistema de curación automático. Node.js apareció referenciado desde la lista awesome-nodejs de Sindre Sorhus — que por sí sola es un universo — y cruzó con señal en 4 awesome lists independientes. Eso no pasa por casualidad.

Qué hace

Node.js es un runtime de JavaScript construido sobre el motor V8 de Chrome, pero eso es la descripción técnica aburrida. Lo que lo hace especial es el event loop no-bloqueante. En un servidor web tradicional, cada request que llega espera: espera que la base de datos responda, espera que el disco lea un archivo, espera que la red devuelva algo. Mientras espera, ese hilo está bloqueado, sin hacer nada útil. Multiplicá eso por miles de conexiones y entendés por qué necesitabas 64GB de RAM para un servidor decente.

Node invierte el modelo. Cuando hacés una operación I/O, Node registra un callback y sigue adelante. Cuando el disco termina de leer, cuando la DB responde, cuando el socket tiene datos — Node lo sabe y ejecuta lo que sigue. Un solo hilo manejando miles de operaciones en vuelo simultáneamente. No es magia, es un modelo mental diferente.

// El modelo tradicional (bloqueante): esperás en cada paso
// El modelo Node: registrás lo que querés que pase CUANDO algo esté listo

const fs = require('fs');
const http = require('http');

const server = http.createServer((req, res) => {
  // Esto NO bloquea el event loop
  // Node sigue atendiendo otras requests mientras el disco lee
  fs.readFile('./data.json', 'utf8', (err, data) => {
    if (err) {
      res.writeHead(500);
      res.end('Algo explotó');
      return;
    }
    // Recién acá respondemos, cuando el dato está disponible
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(data);
  });
});

server.listen(3000, () => {
  console.log('Escuchando en puerto 3000');
});

Hoy la sintaxis moderna con async/await hace esto mucho más legible:

const fs = require('fs').promises;
const http = require('http');

const server = http.createServer(async (req, res) => {
  try {
    // Await no bloquea el event loop — libera el hilo mientras espera
    // Otros requests siguen siendo procesados en paralelo
    const data = await fs.readFile('./data.json', 'utf8');

    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(data);
  } catch (err) {
    res.writeHead(500);
    res.end(JSON.stringify({ error: 'No se pudo leer el archivo' }));
  }
});

server.listen(3000);

El ecosistema npm es otro animal completamente. Más de 2 millones de paquetes. Es tanto una fortaleza absurda como un vector de quilombos de seguridad (left-pad, event-stream, los fantasmas del pasado). Pero el punto es que para casi cualquier cosa que necesitás, existe una librería. Podés ver el repositorio oficial acá y la awesome-nodejs de Sindre Sorhus acá — esa segunda URL es prácticamente un mapa del ecosistema completo.

Por qué está en la lista

Cuatro awesome lists independientes señalando Node.js es consenso de comunidad, no hype. Y tiene sentido: Node resolvió un problema real que tenía el desarrollo backend pre-2009 — la C10K problem, la dificultad de manejar 10.000 conexiones concurrentes con servidores tradicionales. Ryan Dahl no inventó el event loop, pero tomó una idea que existía en Nginx y la puso en manos de developers JavaScript que ya eran millones.

El unlock más importante fue unificar el lenguaje. Antes de Node, si eras dev web, sabías JavaScript en el browser y algo más (PHP, Ruby, Java) en el server. Con Node, el mismo lenguaje, los mismos paradigmas, el mismo equipo. Eso tuvo un impacto organizacional enorme que todavía se siente hoy en el mercado laboral.

Comparado con alternativas contemporáneas: Go gana en raw performance y simplicidad del modelo de concurrencia. Python con FastAPI o Django es más legible para muchos casos. Java con Spring Boot (mi mundo actual) tiene una madurez y tooling empresarial que Node todavía está construyendo. Pero ninguno de ellos tiene el ecosistema npm, ninguno tiene la barrera de entrada tan baja para alguien que ya sabe JavaScript, y ninguno movió tan rápido el mercado de herramientas de desarrollo — Webpack, Babel, ESLint, Prettier, todos corren sobre Node.

Cuándo NO usarlo

Si tenés CPU-bound workloads — procesamiento de imágenes, criptografía pesada, machine learning, compilación — Node te va a defraudar. El event loop es brillante para I/O concurrente pero el single thread se convierte en cuello de botella cuando hay cómputo intensivo. Los Worker Threads mitigan esto, pero en ese punto ya estás peleando contra el diseño del runtime. Para eso, Python con multiprocessing, Go, o Java son opciones más naturales.

Los memory leaks son más frecuentes y más difíciles de debuggear que en lenguajes compilados. El garbage collector de V8 es bueno, pero si no entendés el modelo de closures y referencias circulares, vas a ver procesos que crecen de memoria sin parar hasta que explotan en producción a las 3 de la mañana. Hablo por experiencia propia. También: si tu equipo no tiene experiencia sólida con programación asíncrona, el callback hell y los errores sutiles de async/await pueden generar código muy difícil de mantener. En esos casos, un framework con más estructura opinionada como Spring Boot o Django puede ser más sano a largo plazo.

Cierre

Node.js es una de esas herramientas que cambió el ecosistema de forma permanente. No porque sea perfecta — no lo es — sino porque llegó en el momento justo con la idea correcta y arrastró a millones de developers con ella. Treinta años viendo tecnología me enseñaron a distinguir el hype que se desvanece del cambio real. Node es lo segundo.

Si este post te resultó útil, la serie Awesome Curated: The Tools tiene 8 posts más donde analizo herramientas con el mismo criterio. Desde criptografía con Themis hasta monitoreo de red con Sniffnet — cada una pasó el mismo filtro de curación antes de llegar acá. El próximo también.

Este artículo fue publicado originalmente en juanchi.dev

Rate limiting in web apps: what to protect before picking a library

Juan Torchia — Tue, 07 Jul 2026 12:00:52 +0000

Rate limiting in web apps: what to protect before picking a library

I spent months convinced that rate limiting was just a matter of adding middleware, setting a request-per-minute number, and moving on. It took seeing a login endpoint with zero controls — in a reference project I was using to study architecture — to understand that the missing library wasn't the problem. Nobody had defined what was being protected, from what kind of abuse, and at what cost.

I'm not telling that story to look bad. I'm telling it because you're probably going to copy that upstash/ratelimit or express-rate-limit snippet before you ask yourself that question. And if you do, you'll have rate limiting that works on paper and fails exactly where it matters most.

My take: rate limiting is not a dependency. It's an abuse policy. And a policy without context is decoration.

Rate limiting in Next.js web apps: the real problem

Most rate limiting tutorials for Next.js start from the library. They show you how to configure Upstash Redis, how many tokens to put in the bucket, and how to return a 429. All of that is fine. The problem is that sequence skips four questions that should come first:

What asset are you protecting? A login endpoint? A public API with no auth? A contact form? A route that fires an email? They don't all deserve the same policy.
What kind of abuse are you expecting? Credential stuffing, scraping, form spam, and DDoS are four different problems. Rate limiting solves some of them, not all.
What does a false positive cost you? Blocking a legitimate user at an e-commerce checkout has a very different cost than blocking a bot on a public query API.
How will you know it's working? Without logs, without metrics, without alerts, the middleware acts in silence and you have no idea whether it's blocking what it should or what it shouldn't.

These four points aren't philosophical. They're the difference between a control that actually protects and one that gives you a false sense of security.

What OWASP says — and what it doesn't

The OWASP Authentication Cheat Sheet is the most-cited public reference when talking about defensive controls around authentication and abuse. Worth reading directly instead of trusting someone else's summary.

What OWASP explicitly says in that document:

Implement controls to limit failed login attempts to mitigate brute force attacks.
Consider temporary lockout, CAPTCHA, or user notification as possible responses.
Aggressive lockout can itself be used as a denial-of-service vector against legitimate users — meaning the false positive has a security cost, not just a UX one.

What OWASP doesn't say in that document:

How many requests per minute is the right number. That number doesn't exist outside of context.
That IP-based rate limiting is sufficient. An attacker with distributed infrastructure rotates IPs trivially.
That every route in an application deserves the same control.

This matters because a lot of people cite "OWASP recommends rate limiting" as if it were a universal recipe. It isn't. It's one control among several, with explicit preconditions and trade-offs.

If you've already read my post on what to expose and what to hide in Spring Boot Actuator, you'll recognize the pattern: the problem isn't enabling or disabling a feature. It's understanding what decision you're making and why.

Where the common recipe goes wrong

The typical setup in Next.js App Router looks like this: install @upstash/ratelimit, wrap the Route Handler or Server Action, configure 10 requests per minute per IP, return 429 if exceeded. It works. And that's exactly the problem: it works for the case that doesn't matter.

Hidden cost 1: IP-based granularity is weak where it hurts most.
The most sensitive endpoints — login, password recovery, registration — are precisely the ones a resourceful attacker will hit from multiple IPs. IP rate limiting stops amateur abuse. It doesn't stop well-crafted credential stuffing. For that you need to combine IP + User-Agent fingerprinting, or put CAPTCHA directly in the flow.

Hidden cost 2: a 429 without logging is a blind control.
If the middleware blocks and you don't emit a structured log with at minimum { ip, route, timestamp, reason }, you have no way to tell the difference between a real attack and a legitimate user behind a corporate NAT sharing an IP with a hundred colleagues. That legitimate user gets a 429 and has no idea why.

Hidden cost 3: a global config flattens the policy.
A global limit of 100 requests per minute might be generous for a login endpoint and absurdly restrictive for a public search API. When everything uses the same configuration, the policy has no real semantics — it's an arbitrary number nobody ever justified.

Concrete counterexample: a contact form that fires an email has a real per-request cost (the email send). There, rate limiting by IP + by session makes sense, and the threshold should be low. A public read endpoint serving already-cached static data has a completely different abuse profile. Modeling them the same way is just imprecise.

Same logic I went into with caching in Next.js App Router: there's no one config that works for everything. Every route has a behavioral contract.

Decision checklist: before you copy the middleware

This checklist doesn't replace per-system analysis. It's a starting point to structure the conversation before you open the library docs.

1. Define the asset

Route type	Sensitivity	Minimum recommended control
Login / authentication	High	Rate limit by IP + by user if it exists; consider CAPTCHA on retries
Password recovery	High	Limit by IP; notify user; don't reveal whether the email exists
Form with side effect (email, payment)	Medium-High	Rate limit by IP + session; log every block
Public read API without auth	Medium	Global rate limit by IP; consider whether caching already mitigates the risk
Authenticated API	Low-Medium	Rate limit by token/user; differentiated policy by plan if applicable
Static or health routes	N/A	No rate limit; false positive cost is maximum

Prudent criteria based on documented patterns. The numeric threshold depends on each system's real traffic volume.

2. Define the expected abuse

Brute force / credential stuffing: control at the authentication endpoint, not across the whole app.
Form spam: rate limit by IP + honeypot + CAPTCHA if the volume justifies it.
Scraping: rate limit by IP + User-Agent headers; consider whether the content should be public anyway.
Layer 7 DDoS: app-level rate limiting isn't enough; that problem lives at the infrastructure layer (CDN, WAF, Railway regions).

3. Measure the cost of the false positive

Before setting a threshold, answer: what happens if a legitimate user exceeds it? If the answer is "they lose a session they can recover easily," the threshold can be more aggressive. If the answer is "they lose a purchase or can't get into an active account," the threshold needs more tolerance — or a progressive challenge mechanism instead of a hard block.

4. Define observability from day one

A minimal snippet of what you should log on every block:

// app/api/login/route.ts — reproducible example, not production code
import { NextRequest, NextResponse } from 'next/server'

// Rate limit check goes BEFORE any business logic
export async function POST(req: NextRequest) {
  const ip = req.headers.get('x-forwarded-for') ?? 'unknown'
  const limitExceeded = await checkRateLimit(ip) // your implementation

  if (limitExceeded) {
    // ALWAYS log: IP, route, timestamp, reason
    console.warn(JSON.stringify({
      event: 'rate_limit_exceeded',
      ip,
      route: '/api/login',
      timestamp: new Date().toISOString(),
    }))
    return NextResponse.json({ error: 'Too many requests' }, { status: 429 })
  }

  // Authentication logic here
}

Without that log, the middleware is a black box. You don't know if it blocked ten bots or ten real users. I covered the observability angle in the Docker healthchecks post too: measuring well is part of the control, not an optional extra.

Honest limits: what you can't conclude without your own data

I'm saying this explicitly because a lot of rate limiting content just skips it:

You can't know the right threshold without real traffic logs. The number 10, 100, or 1000 requests per minute means nothing out of context. If you don't have real usage data, start with a conservative threshold, log it, and adjust.
IP-based rate limiting is not equivalent to user-based rate limiting. Behind a corporate NAT there can be dozens of users sharing one IP. An aggressive per-IP policy in that context generates systematic false positives.
You can't assume the 429 reached the right attacker. Without logs, you don't know who you blocked. With logs, you have evidence to adjust.
Rate limiting doesn't replace authentication, authorization, or input validation. It's a last-line control against volumetric abuse, not a general security layer. Same logic applies to digital signatures: every control has its domain, none of them covers everything.

FAQ: common questions about rate limiting in Next.js

What rate limiting library do you recommend for Next.js?
@upstash/ratelimit is the most documented option for Next.js with Redis on the edge. express-rate-limit works fine if your backend is plain Node.js. But the library is the last step, not the first. If you haven't defined what asset you're protecting and what abuse you're expecting, any library gives you a false sense of control.

Rate limiting in Next.js middleware or in each Route Handler?
Depends on the granularity you need. Next.js middleware runs before the request reaches the route — useful for global or prefix-level protection. Route Handlers let you have different policies per endpoint. The most practical approach is usually: base policy in middleware, specific policy on sensitive endpoints (login, password recovery, forms with side effects).

Is IP enough as an identifier for rate limiting?
For amateur abuse, yes. For distributed attacks, no. If the asset you're protecting is critical — login, payments, endpoints that fire emails — combine IP with session or user identifier when it exists, and consider CAPTCHA as a progressive challenge instead of a hard block.

How do I handle rate limiting on Railway without Redis?
Railway lets you add Redis as an internal service. If you don't want that dependency, you can use an in-memory store for prototypes — but you have to accept that the limit won't be shared across instances. In production with multiple replicas, a shared store is necessary for the policy to be consistent.

Does infrastructure-layer rate limiting (CDN, WAF) replace the code-level one?
No, they're complementary. The infrastructure layer protects against raw volume and layer 7 DDoS. Application-level rate limiting enables semantic policies: by user, by action type, by cost of the operation. Both together are more robust than either one alone.

What do I do if rate limiting is blocking legitimate users?
First, log it. Second, check whether the problem is the threshold (too low) or the identifier (IP instead of user). Third, consider a progressive challenge mechanism: instead of blocking outright, ask for confirmation, CAPTCHA, or a short wait. Hard blocking should be the last resort, not the default response.

The policy before the dependency

The scene I opened with — an endpoint with zero abuse controls in a reference project — wasn't a missing-library problem. It was a design problem: nobody had defined what to protect, from what, and at what cost.

That order matters. If you pick the library first and then ask yourself what to configure, you end up with middleware that acts but has no policy. It acts in silence, blocks without documented criteria, and tells you nothing when it fails.

What I think is honest to recommend:

List the assets that deserve protection — not the whole app, just the endpoints with real side effects.
Define the type of abuse before choosing the control. They're different problems.
Calculate the false positive cost for each asset before setting the threshold.
Log it from day one. Without logs, the control is decoration.
Use the library that fits the above, not the other way around.

Well-applied rate limiting is a real defensive control. Badly applied, it's a number in a config file that nobody will revisit until a legitimate user calls asking why they can't get in.

The question I'll leave you with is concrete: do you know today how many 429s your app returned in the last 24 hours, and to whom?

Primary source:

OWASP Authentication Cheat Sheet — defensive controls around authentication and abuse: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html

This article was originally published on juanchi.dev

Rate limiting en aplicaciones web: qué proteger antes de elegir una librería

Juan Torchia — Tue, 07 Jul 2026 12:00:47 +0000

Rate limiting en aplicaciones web: qué proteger antes de elegir una librería

Estuve meses convencido de que rate limiting era cuestión de agregar un middleware, configurar un número de requests por minuto y seguir. Me alcanzó con ver un endpoint de login sin ningún control —en un proyecto de referencia que usé para estudiar arquitectura— para entender que el problema no era la librería que faltaba. Era que nadie había definido qué se estaba protegiendo, de qué tipo de abuso y a qué costo.

No lo cuento para quedar mal, lo cuento porque probablemente vos también vas a copiar ese snippet de upstash/ratelimit o express-rate-limit antes de hacerte esa pregunta. Y si lo hacés, vas a tener rate limiting que funciona en el papel y falla exactamente donde más importa.

Mi tesis: rate limiting no es una dependencia. Es una política de abuso. Y una política sin contexto es decoración.

Rate limiting en aplicaciones web con Next.js: el problema real

La mayoría de los tutoriales sobre rate limiting en Next.js arrancan desde la librería. Te muestran cómo configurar Upstash Redis, cuántos tokens poner en el bucket y cómo devolver un 429. Todo eso está bien. El problema es que esa secuencia saltea cuatro preguntas que deberían ir primero:

¿Qué activo estás protegiendo? ¿Un endpoint de login? ¿Una API pública sin autenticación? ¿Un formulario de contacto? ¿Una ruta que dispara un email? No todos merecen la misma política.
¿Qué tipo de abuso esperás? Credential stuffing, scraping, spam de formulario y DDoS son cuatro problemas distintos. Rate limiting resuelve algunos, no todos.
¿Cuánto te cuesta un falso positivo? Bloquear a un usuario legítimo en el checkout de un e-commerce tiene un costo diferente al de bloquear un bot en una API de consulta pública.
¿Cómo vas a saber que está funcionando? Sin logs, sin métricas, sin alertas, el middleware actúa en silencio y no sabés si está bloqueando lo que tiene que bloquear o lo que no debería.

Estos cuatro puntos no son filosóficos. Son la diferencia entre un control que protege y uno que da una sensación falsa de seguridad.

Qué dice OWASP y qué no dice

La OWASP Authentication Cheat Sheet es la referencia pública más citada cuando se habla de controles defensivos en autenticación y abuso. Vale la pena leerla directo en lugar de confiar en el resumen de alguien más.

Lo que OWASP dice explícitamente en ese documento:

Implementar controles de límite de intentos fallidos de login para mitigar ataques de fuerza bruta.
Considerar lockout temporal, CAPTCHA o notificación al usuario como respuestas posibles.
El lockout agresivo puede usarse como vector de denegación de servicio contra usuarios legítimos (es decir, el falso positivo tiene costo de seguridad, no solo de UX).

Lo que OWASP no dice en ese documento:

Cuántas requests por minuto es el número correcto. No existe ese número fuera de contexto.
Que rate limiting por IP sea suficiente. Un atacante con infraestructura distribuida rota IPs trivialmente.
Que todas las rutas de una aplicación merezcan el mismo control.

Esto importa porque mucha gente cita "OWASP recomienda rate limiting" como si fuera una receta universal. No lo es. Es un control entre varios, con precondiciones y trade-offs explícitos.

Si ya leíste mi post sobre qué exponer y qué ocultar en Spring Boot Actuator, reconocés el patrón: el problema no es activar o desactivar una feature. Es entender qué decisión tomás y por qué.

Dónde se equivoca la receta común

La receta típica en Next.js App Router se ve así: instalás @upstash/ratelimit, wrapeás el handler de la Route Handler o el Server Action, configurás 10 requests por minuto por IP y devolvés 429 si se supera. Funciona. Y acá está el problema: funciona para el caso que no importa.

Costo oculto 1: la granularidad por IP es débil donde más duele.
Los endpoints más sensibles —login, recuperación de contraseña, registro— son exactamente los que un atacante con recursos va a atacar desde múltiples IPs. Rate limiting por IP frena el abuso amateur. No frena credential stuffing bien armado. Para eso necesitás combinar IP + User-Agent fingerprinting, o directamente CAPTCHA en el flujo.

Costo oculto 2: el 429 sin logging es un control ciego.
Si el middleware bloquea y no emitís un log estructurado con al minimum { ip, route, timestamp, reason }, no tenés forma de distinguir un ataque real de un usuario detrás de un NAT corporativo que comparte IP con cien colegas. Ese usuario legítimo va a recibir un 429 y no va a entender por qué.

Costo oculto 3: la configuración global aplana la política.
Un límite global de 100 requests por minuto puede ser generoso para un endpoint de login y absurdamente restrictivo para una API de búsqueda pública. Cuando todo usa la misma configuración, la política no tiene semántica real: es un número arbitrario que nadie justificó.

Contraejemplo concreto: un formulario de contacto que dispara un email tiene un costo real por request (el envío del email). Ahí rate limiting por IP + por sesión tiene sentido, y el umbral debería ser bajo. Un endpoint de lectura pública que sirve datos estáticos ya cacheados tiene un perfil de abuso completamente diferente. Modelarlos igual es impreciso.

En el mismo sentido en que hablé de caching en Next.js App Router: no existe una configuración que sirva para todo. Cada ruta tiene un contrato de comportamiento.

Checklist de decisión: antes de copiar el middleware

Este checklist no reemplaza el análisis de cada sistema. Es un punto de partida para estructurar la conversación antes de abrir la documentación de la librería.

1. Definí el activo

Tipo de ruta	Sensibilidad	Control mínimo recomendado
Login / autenticación	Alta	Rate limit por IP + por usuario si existe; considerar CAPTCHA en reintentos
Recuperación de contraseña	Alta	Limit por IP; notificación al usuario; no revelar si el email existe
Formulario con efecto colateral (email, pago)	Media-Alta	Rate limit por IP + sesión; log de cada bloqueo
API pública de lectura sin auth	Media	Rate limit global por IP; considerar si el caching ya mitiga el riesgo
API autenticada	Baja-Media	Rate limit por token/usuario; política diferenciada por plan si aplica
Rutas estáticas o de health	No aplica	Sin rate limit; el costo de falso positivo es máximo

Criterios prudentes basados en patrones documentados. El umbral numérico depende del volumen real de cada sistema.

2. Definí el abuso esperado

Fuerza bruta / credential stuffing: control en el endpoint de autenticación, no en toda la app.
Spam de formulario: rate limit por IP + honeypot + CAPTCHA si el volumen lo justifica.
Scraping: rate limit por IP + headers de User-Agent; considerar si el contenido debería ser público de todas formas.
DDoS de capa 7: rate limiting en la app no es suficiente; ese problema vive en la capa de infraestructura (CDN, WAF, Railway regions).

3. Medí el costo del falso positivo

Antes de configurar un umbral, contestá: ¿qué pasa si un usuario legítimo lo supera? Si la respuesta es "pierde una sesión que puede recuperar fácil", el umbral puede ser más agresivo. Si la respuesta es "pierde una compra o no puede entrar a una cuenta activa", el umbral necesita más tolerancia o un mecanismo de desafío progresivo en lugar de bloqueo directo.

4. Definí observabilidad desde el día uno

Un snippet mínimo de lo que deberías loguear en cada bloqueo:

// app/api/login/route.ts — ejemplo reproducible, no código de producción
import { NextRequest, NextResponse } from 'next/server'

// El chequeo de rate limit va ANTES de cualquier lógica de negocio
export async function POST(req: NextRequest) {
  const ip = req.headers.get('x-forwarded-for') ?? 'unknown'
  const limitExceeded = await checkRateLimit(ip) // vos implementación

  if (limitExceeded) {
    // Loguear SIEMPRE: IP, ruta, timestamp, motivo
    console.warn(JSON.stringify({
      event: 'rate_limit_exceeded',
      ip,
      route: '/api/login',
      timestamp: new Date().toISOString(),
    }))
    return NextResponse.json({ error: 'Too many requests' }, { status: 429 })
  }

  // Lógica de autenticación acá
}

Sin ese log, el middleware es una caja negra. No sabés si bloqueó diez bots o diez usuarios reales. El tema de observabilidad lo traté también en el post de Docker healthchecks: medir bien es parte del control, no un extra opcional.

Límites honestos: qué no podés concluir sin datos propios

Esto lo digo explícitamente porque mucho contenido sobre rate limiting lo omite:

No podés saber el umbral correcto sin logs reales de tráfico. El número 10, 100 o 1000 requests por minuto no tiene sentido fuera de contexto. Si no tenés datos de uso real, empezá con un umbral conservador, loguéalo y ajustá.
Rate limiting por IP no es equivalente a rate limiting por usuario. Detrás de un NAT corporativo puede haber decenas de usuarios en la misma IP. Una política agresiva por IP en ese contexto genera falsos positivos sistemáticos.
No podés asumir que el 429 llegó al atacante correcto. Sin logs, no sabés a quién bloqueaste. Con logs, tenés evidencia para ajustar.
Rate limiting no reemplaza autenticación, autorización ni validación de inputs. Es un control de última línea frente a abuso volumétrico, no una capa de seguridad general. La misma lógica aplica a firma digital: cada control tiene su dominio, no hay uno que cubra todo.

FAQ: preguntas frecuentes sobre rate limiting en Next.js

¿Qué librería de rate limiting recomendás para Next.js?
@upstash/ratelimit es la opción más documentada para Next.js con Redis en el edge. express-rate-limit funciona si el backend es Node.js puro. Pero la librería es el último paso, no el primero. Si no definiste qué activo protegés y qué abuso esperás, cualquier librería te da una falsa sensación de control.

¿Rate limiting en middleware de Next.js o en cada Route Handler?
Depende de la granularidad que necesitás. El middleware de Next.js corre antes de que la request llegue a la ruta: es útil para protección global o por prefijo. Los Route Handlers permiten políticas distintas por endpoint. Lo más práctico suele ser: política base en middleware, política específica en los endpoints sensibles (login, recuperación de contraseña, formularios con efectos).

¿IP es suficiente como identificador para rate limiting?
Para abuso amateur, sí. Para ataques distribuidos, no. Si el activo que protegés es crítico —login, pagos, endpoints que disparan emails—, combiná IP con identificador de sesión o usuario cuando exista, y considerá CAPTCHA como desafío progresivo en lugar de bloqueo directo.

¿Cómo manejo rate limiting en Railway sin Redis?
Railway permite agregar Redis como servicio interno. Si no querés esa dependencia, podés usar un store en memoria para prototipos —pero tenés que aceptar que el límite no se comparte entre instancias. En producción con múltiples réplicas, un store compartido es necesario para que la política sea consistente.

¿El rate limiting de la capa de infraestructura (CDN, WAF) reemplaza el del código?
No, son complementarios. La capa de infraestructura protege contra volumen bruto y DDoS de capa 7. El rate limiting en la aplicación permite políticas semánticas: por usuario, por tipo de acción, por costo de la operación. Los dos juntos son más robustos que cualquiera de los dos solos.

¿Qué hago si el rate limiting bloquea usuarios legítimos?
Primero, loguéalo. Segundo, revisá si el problema es el umbral (muy bajo) o el identificador (IP en lugar de usuario). Tercero, considerá un mecanismo de desafío progresivo: en lugar de bloquear directo, pedí confirmación, CAPTCHA o una espera corta. El bloqueo duro debería ser el último recurso, no la respuesta por defecto.

Conclusión: la política antes que la dependencia

La escena con la que arranqué —un endpoint sin ningún control de abuso en un proyecto de referencia— no era un problema de librería faltante. Era un problema de diseño: nadie había definido qué proteger, de qué y a qué costo.

Ese orden importa. Si primero elegís la librería y después te preguntás qué configurar, terminás con un middleware que actúa pero no tiene política. Actúa en silencio, bloquea sin criterio documentado y no te dice nada cuando falla.

Lo que me parece honesto recomendar:

Listá los activos que merecen protección —no toda la app, los endpoints con efectos colaterales reales.
Definí el tipo de abuso antes de elegir el control. Son problemas distintos.
Calculá el costo del falso positivo para cada activo antes de configurar el umbral.
Loguéalo desde el día uno. Sin logs, el control es decoración.
Usá la librería que encaje con lo anterior, no al revés.

Rate limiting bien aplicado es un control defensivo real. Mal aplicado es un número en una configuración que nadie va a revisar hasta que un usuario legítimo llame por teléfono preguntando por qué no puede entrar.

La pregunta que te dejo es concreta: ¿sabés hoy cuántos 429 devolvió la app en las últimas 24 horas y a quién?

Fuente original:

OWASP Authentication Cheat Sheet — controles defensivos alrededor de autenticación y abuso: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html

Este artículo fue publicado originalmente en juanchi.dev

Spring Boot Actuator: What to Expose, What to Hide, and What to Check Before Adding Endpoints

Juan Torchia — Mon, 06 Jul 2026 12:01:36 +0000

Spring Boot Actuator: What to Expose, What to Hide, and What to Check Before Adding Endpoints

There's a configuration that shows up in almost every Spring Boot tutorial, and people copy it without really reading it:

management:
  endpoints:
    web:
      exposure:
        include: "*"

One asterisk. Every endpoint. All at once. And the tutorial moves straight to the next step without pausing for even a second to think about what that actually means.

My take is simple: Actuator isn't bad. The mistake is enabling it without a clear policy for what to expose, what to restrict, and for whom. That gap between operational tool and unnecessary public surface area isn't something Spring Boot closes on its own — you close it with explicit judgment.

I've been in tech for over thirty years, and one of the patterns I keep seeing isn't the dramatic bug that takes down production: it's the small decision made without a policy, accumulating quietly until someone finds it from the outside.

Spring Boot Actuator Endpoints Security: What the Docs Say — and What They Don't

The official Spring Boot Actuator documentation is clear about something most tutorials skip: by default, only health and info are exposed over HTTP. The rest exist but aren't automatically accessible.

What the documentation spells out precisely:

The distinction between enabling an endpoint (it exists in the context) and exposing it (it's reachable via HTTP or JMX).
That shutdown is enabled but not exposed by default — precisely because its impact is irreversible.
That env and configprops can leak sensitive values, and that Spring Boot offers configurable sanitization for those cases.
That securing endpoints is the developer's responsibility: Spring Boot doesn't add automatic authentication over Actuator.

What the documentation doesn't resolve for you:

Which endpoints actually make sense for your specific operation.
Whether the management port is separated from the app port or shared.
Whether there's a proxy, API gateway, or load balancer in front that filters — or doesn't filter — those routes.
Whether the team operating the system has differentiated access from public traffic.

That gap between "what Spring Boot configures by default" and "what you need in production" is exactly where implicit decisions pile up.

The Most Common Mistake: Enable Everything and Secure It Later (or Never)

The recipe that circulates across tutorials, Stack Overflow, and example repos usually looks like this:

# application.yml — common pattern worth reviewing before copying
management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: always

The hidden cost of this pattern isn't that it's "dangerous" in the abstract. The concrete cost is:

/actuator/env exposes environment variables — including keys, database URLs, and tokens if they aren't sanitized.
/actuator/heapdump can return a full JVM heap dump, which in many systems contains live in-memory data.
/actuator/shutdown lets you kill the application via HTTP POST if it's enabled and exposed.
/actuator/loggers lets you change log levels at runtime, which can generate operational noise or expose diagnostic information.

None of those endpoints are inherently bad. heapdump is invaluable for diagnosing a memory leak. loggers is exactly the tool you want when you need DEBUG output without a restart. The problem is exposing them without deciding who can reach them and from where.

The analogy I keep coming back to: it's similar to what happens with Docker healthchecks. A badly designed healthcheck doesn't fail because Docker is broken — it fails because nobody defined what "healthy" actually means for that container. Actuator is the same story: the tool is solid, but the exposure criteria has to be explicit.

Decision Matrix: What to Expose, What to Restrict, What to Disable Entirely

This matrix is a pragmatic guide, not an absolute rule. Each row represents an analysis worth doing before including that endpoint.

Endpoint	What it exposes	Recommended approach
`health`	App state and dependency health	Expose. Use `show-details: when-authorized` in production
`info`	Build metadata, version, git commit	Expose if you have useful data. Nothing sensitive by default
`metrics`	JVM, HTTP, and custom metrics	Expose only to internal monitoring systems (Prometheus, etc.)
`loggers`	Current logging levels	Restrict to operators. Useful, but with controlled access
`env`	Environment variables	Restrict. Review sanitization before enabling
`configprops`	Configuration properties	Restrict. Can surface sensitive values
`heapdump`	JVM heap dump	Controlled environments only. Not on public production
`threaddump`	Active thread state	Useful for diagnostics. Restrict to operators
`shutdown`	Shuts down the application	Don't enable unless there's a very clear operational reason
`mappings`	All REST endpoints in the app	Surface area information. Restrict
`beans`	All Spring context beans	Development only. Not in production

The configuration I'd use as a starting point in a production environment:

# application.yml — pragmatic starting point for production
management:
  server:
    port: 8081  # separate port, not publicly exposed
  endpoints:
    web:
      exposure:
        include: health, info, metrics, loggers
  endpoint:
    health:
      show-details: when-authorized
    env:
      enabled: false  # disable if no sanitization policy is defined

Separating the management port (management.server.port) from the application port is a decision that dramatically simplifies your policy: internal traffic hits 8081, public traffic has no access to that port at all. It turns security into a structural property instead of something that depends entirely on getting every auth rule right in code.

What You Can't Conclude Without Your Own Experiments, Logs, or Data

There's an honest limit worth naming here. This guide is based on the official documentation and careful analysis. What you can't conclude from this alone:

That your current configuration is secure: that requires checking what's in front of your app (proxy, gateway, firewall) and how it's configured.
That separating the management port is sufficient: if port 8081 is open in your security group or network firewall, the separation means nothing.
That env sanitization covers all your sensitive keys: Spring Boot sanitizes by known patterns (password, secret, key, etc.), but if you're using unconventional variable names, verify it explicitly.
That adding Spring Security over Actuator is the only solution: you can also handle access at the network level, proxy level, or ingress level. The right layer depends on your architecture.

If you want to inspect what traffic is actually reaching your management endpoints in a local environment, a tool like Sniffnet can help you visualize connections without diving straight into tcpdump.

FAQ: Spring Boot Actuator Endpoints Security

Which Actuator endpoints are enabled by default?

According to the official documentation, only health and info are exposed over HTTP by default. The rest are enabled in the context but not reachable via HTTP. The exception is shutdown, which isn't enabled by default precisely because of its impact.

What's the difference between enabling and exposing an endpoint?

Enabling means the endpoint exists in the Spring context and can be invoked internally. Exposing means it's reachable from outside (HTTP or JMX). You can have an endpoint enabled but not exposed: it exists, but nothing can call it from the outside. The management.endpoints.web.exposure.include property controls HTTP exposure.

Is Spring Security enough to protect Actuator?

Spring Security is a valid layer, but it's not the only one — and it's not necessarily your first line of defense. Separating the management port and restricting access to it at the network or proxy level is a more robust policy because it doesn't depend on every security rule in your code being correct. Ideally, both layers coexist.

Does /actuator/health expose sensitive information?

With the default configuration, health returns only the status (UP or DOWN). Dependency details (database, disk, etc.) only appear if you configure show-details: always. The more sensible middle ground for production is show-details: when-authorized: your monitoring system sees the detail, anonymous traffic doesn't.

What happens if I use include: "*" in production?

Every enabled endpoint gets exposed — including env, configprops, heapdump, and potentially shutdown if you've enabled it. It's not an invalid configuration in every context, but it requires that access to the management port be completely restricted to internal systems. If that port is publicly reachable, anyone can query your environment variables or request a heap dump.

How do I validate which endpoints are actually exposed in my app?

The /actuator endpoint returns a JSON with active endpoints and their URLs. That's your first stop. You can also check Spring Boot's startup logs: it logs registered endpoints at the right log level. And if you have Prometheus or any scraping system configured, verify it's only hitting the management port — not the public one.

My Take: Actuator Is an Operational Tool, Not a Convenience Feature

When I first encountered the Docker healthcheck story I mentioned in that earlier post, what stuck with me was the same lesson that applies here: the value of a tool is in describing an explicit contract, not in turning it on and seeing what happens.

Actuator is the same. It's not a feature you "add" to the app. It's an observability policy that defines what operational information gets exposed, to whom, and from where. That policy can be as simple as two lines in your YAML or as elaborate as differentiated roles with Spring Security — but it has to exist consciously.

The uncomfortable part is that the tutorial everyone copies shows include: "*" as if it were the natural next step. And technically it works. But "it works" and "it's a decision made with judgment" are different things, and that difference matters when the system grows.

The practical move for right now: open the application.yml of whatever project you're working on, find the management.endpoints section, and ask yourself whether what's there is an explicit policy or the result of copying a tutorial without questioning it. If it's the second thing, spend fifteen minutes on it before the system goes to a shared environment.

Not because Actuator is dangerous. But because implicit decisions are the ones that accumulate.

Sources:

Spring Boot Actuator — Endpoints (official documentation)

This article was originally published on juanchi.dev

Spring Boot Actuator: qué exponer, qué ocultar y qué mirar antes de agregar endpoints

Juan Torchia — Mon, 06 Jul 2026 12:01:30 +0000

Spring Boot Actuator: qué exponer, qué ocultar y qué mirar antes de agregar endpoints

Hay una configuración que aparece en casi todos los tutoriales de Spring Boot y que se copia sin leerla bien:

management:
  endpoints:
    web:
      exposure:
        include: "*"

Un asterisco. Todos los endpoints. De una. Y el tutorial sigue con el paso siguiente sin detenerse un segundo en lo que eso significa.

Mi tesis es simple: Actuator no es malo. El error es habilitarlo sin una política clara de qué exponer, qué restringir y para quién. Esa diferencia entre herramienta operativa y superficie pública innecesaria no la resuelve Spring Boot solo: la resolvés vos con criterio explícito.

Tengo más de treinta años de historia con la tecnología, y uno de los patrones que más veo repetirse no es el bug dramático que tira producción: es la decisión pequeña tomada sin política, que se acumula hasta que alguien la encuentra desde afuera.

Spring Boot Actuator endpoints seguridad: qué dice la documentación y qué no dice

La documentación oficial de Spring Boot Actuator es clara en algo que los tutoriales suelen saltear: por defecto, sobre HTTP solo están habilitados health e info. El resto existe pero no se expone automáticamente.

Lo que la documentación describe con precisión:

La distinción entre habilitar un endpoint (que exista en el contexto) y exponerlo (que sea accesible por HTTP o JMX).
Que shutdown está habilitado pero no expuesto por defecto, precisamente porque su impacto es irreversible.
Que env y configprops pueden mostrar valores sensibles, y que Spring Boot ofrece sanitización configurable para esos casos.
Que la seguridad de los endpoints es responsabilidad del desarrollador: Spring Boot no agrega autenticación automática sobre Actuator.

Lo que la documentación no resuelve por vos:

Qué endpoints tienen sentido para vos operación concreta.
Si el puerto de management está separado del puerto de la app o compartido.
Si hay un proxy, API gateway o balanceador de carga delante que filtra o no esas rutas.
Si el equipo que opera el sistema tiene acceso diferenciado del tráfico público.

Esa brecha entre "lo que Spring Boot configura por defecto" y "lo que necesitás en producción" es exactamente donde se acumulan las decisiones implícitas.

El error más común: habilitar todo y securizar después (o nunca)

La receta que circula en tutoriales, Stack Overflow y repositorios de ejemplo suele tener esta forma:

# application.yml — patrón común que vale revisar antes de copiar
management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: always

El costo oculto de este patrón no es que "sea peligroso" en abstracto. El costo concreto es que:

/actuator/env expone variables de entorno, incluyendo claves, URLs de base de datos y tokens si no están sanitizadas.
/actuator/heapdump puede devolver un dump del heap de la JVM, que en muchos sistemas contiene datos en memoria.
/actuator/shutdown permite apagar la aplicación vía HTTP POST si está habilitado y expuesto.
/actuator/loggers permite cambiar el nivel de logging en caliente, lo que puede generar ruido operativo o exponer información de diagnóstico.

Ninguno de esos endpoints es malo en sí mismo. heapdump es invaluable para diagnosticar un leak de memoria. loggers es exactamente la herramienta que querés cuando necesitás DEBUG sin reiniciar. El problema es exponerlos sin decidir quién puede acceder y desde dónde.

La comparación que me resulta útil: es parecido a lo que pasa con los Docker healthchecks. Un healthcheck mal diseñado no falla porque Docker sea malo; falla porque nadie definió qué significa "sano" para ese contenedor en particular. Con Actuator pasa lo mismo: la herramienta es sólida, pero el criterio de exposición tiene que ser explícito.

Matriz de decisión: qué exponer, qué restringir, qué directamente no habilitar

Esta matriz es un criterio prudente, no una regla absoluta. Cada fila representa un análisis que vale hacer antes de incluir ese endpoint.

Endpoint	¿Qué expone?	Criterio recomendado
`health`	Estado de la app y sus dependencias	Exponer. `show-details: when-authorized` en producción
`info`	Metadata de build, versión, git commit	Exponer si hay datos útiles. No expone nada sensible por defecto
`metrics`	Métricas JVM, HTTP, custom	Exponer solo a sistemas de monitoreo internos (Prometheus, etc.)
`loggers`	Niveles de logging actuales	Restringir a operadores. Útil, pero con acceso controlado
`env`	Variables de entorno	Restringir. Revisar sanitización antes de habilitar
`configprops`	Propiedades de configuración	Restringir. Puede mostrar valores sensibles
`heapdump`	Dump del heap de la JVM	Solo en ambientes controlados. No en producción pública
`threaddump`	Estado de los threads activos	Útil para diagnóstico. Restringir a operadores
`shutdown`	Apaga la aplicación	No habilitar salvo que haya una razón operativa muy clara
`mappings`	Todos los endpoints REST de la app	Información de superficie. Restringir
`beans`	Todos los beans del contexto Spring	Solo en desarrollo. No en producción

La configuración que yo usaría como punto de partida en un ambiente productivo:

# application.yml — punto de partida prudente para producción
management:
  server:
    port: 8081  # puerto separado, no expuesto públicamente
  endpoints:
    web:
      exposure:
        include: health, info, metrics, loggers
  endpoint:
    health:
      show-details: when-authorized
    env:
      enabled: false  # deshabilitar si no hay política de sanitización definida

Separar el puerto de management (management.server.port) del puerto de la aplicación es una decisión que simplifica mucho la política: el tráfico interno llega al 8081, el tráfico público no tiene acceso a ese puerto en absoluto. Es una forma de convertir la seguridad en una propiedad estructural en lugar de depender solo de autenticación.

Lo que no podés concluir sin experimento, logs o datos propios

Hay un límite honesto que vale nombrar. Esta guía está basada en la documentación oficial y en análisis prudente. Lo que no podés concluir solo con esto:

Que vos configuración actual es segura: eso requiere revisar qué hay delante de la aplicación (proxy, gateway, firewall) y cómo está configurado.
Que separar el puerto de management es suficiente: si el puerto 8081 está expuesto en el security group o en el firewall de red, la separación no sirve.
Que la sanitización de env cubre todas las claves sensibles: Spring Boot sanitiza por patrones conocidos (password, secret, key, etc.), pero si usás nombres de variables no convencionales, vale verificarlo.
Que agregar Spring Security sobre Actuator es la única solución: también podés resolver el acceso a nivel de red, de proxy o de ingress. La capa correcta depende de la arquitectura.

Si querés inspeccionar qué tráfico llega realmente a los endpoints de management en un ambiente local, una herramienta como Sniffnet puede ayudarte a visualizar conexiones sin meterte en tcpdump desde el primer momento.

FAQ: Spring Boot Actuator endpoints seguridad

¿Cuáles son los endpoints de Actuator que están habilitados por defecto?

Según la documentación oficial, sobre HTTP solo health e info están expuestos por defecto. El resto están habilitados en el contexto pero no accesibles por HTTP. La excepción es shutdown, que no está habilitado por defecto justamente por su impacto.

¿Qué diferencia hay entre habilitar y exponer un endpoint?

Habilitar significa que el endpoint existe en el contexto de Spring y puede ser invocado internamente. Exponer significa que es accesible desde el exterior (HTTP o JMX). Podés tener un endpoint habilitado y no expuesto: existe pero nadie puede llamarlo desde fuera. La propiedad management.endpoints.web.exposure.include controla la exposición HTTP.

¿Es suficiente con Spring Security para proteger Actuator?

Spring Security es una capa válida, pero no es la única ni necesariamente la primera línea. Separar el puerto de management y restringir acceso a ese puerto a nivel de red o proxy es una política más robusta porque no depende de la correcta configuración de cada regla de seguridad en el código. Idealmente, ambas capas conviven.

¿/actuator/health expone información sensible?

Con la configuración por defecto, health devuelve solo el estado (UP o DOWN). El detalle de dependencias (base de datos, disco, etc.) aparece solo si configurás show-details: always. La opción intermedia y más razonable en producción es show-details: when-authorized: el sistema de monitoreo ve el detalle, el tráfico anónimo no.

¿Qué pasa si uso include: "*" en producción?

Se exponen todos los endpoints habilitados, incluyendo env, configprops, heapdump y potencialmente shutdown si lo habilitaste. No es una configuración inválida en todos los contextos, pero requiere que el acceso al puerto de management esté completamente restringido a sistemas internos. Si ese puerto es accesible públicamente, cualquiera puede consultar variables de entorno o pedir un dump del heap.

¿Cómo valido qué endpoints están realmente expuestos en mi app?

El endpoint /actuator devuelve un JSON con los endpoints activos y sus URLs. Es el primer lugar donde mirar. También podés revisar los logs de startup de Spring Boot: loguea los endpoints registrados si tenés el nivel adecuado. Y si tenés Prometheus o cualquier sistema de scraping configurado, verificá que solo raspe el puerto de management y no el puerto público.

Mi postura: Actuator es una herramienta operativa, no una opción de conveniencia

Cuando vi por primera vez la anécdota de Docker que mencioné al principio del post sobre healthchecks, lo que me quedó fue la misma lección que aplica acá: el valor de la herramienta está en describir un contrato explícito, no en activarla y ver qué pasa.

Con Actuator es igual. No es una feature que "agregás" a la app. Es una política de observabilidad que define qué información operativa se expone, a quién y desde dónde. Esa política puede ser tan simple como dos líneas en el YAML o tan elaborada como roles diferenciados con Spring Security, pero tiene que existir de forma consciente.

Lo incómodo es que el tutorial que más circula muestra el include: "*" como si fuera el paso natural. Y técnicamente funciona. Pero "funciona" y "es una decisión tomada con criterio" son cosas distintas, y la diferencia importa cuando el sistema crece.

La decisión práctica para el próximo paso es esta: abrí el application.yml del proyecto en el que estás trabajando ahora, buscá la sección management.endpoints, y preguntate si lo que está ahí es una política explícita o el resultado de copiar un tutorial sin cuestionarlo. Si es lo segundo, dedicale quince minutos antes de que el sistema salga a un ambiente compartido.

No porque Actuator sea peligroso. Sino porque las decisiones implícitas son las que se acumulan.

Fuentes:

Spring Boot Actuator — Endpoints (documentación oficial)

Este artículo fue publicado originalmente en juanchi.dev

Next.js App Router Caching: revalidate, dynamic, and no-store Without the Folklore

Juan Torchia — Sun, 05 Jul 2026 12:00:55 +0000

Next.js App Router Caching: revalidate, dynamic, and no-store Without the Folklore

There's a very specific moment in App Router development that I know all too well: someone adds export const dynamic = 'force-dynamic' to a page, the build passes, and everyone breathes again. The data is fresh. The problem... is that nobody knows exactly why it works, or when it stops being the right answer.

That's folklore. And folklore in caching is expensive — you pay for it either with stale data when you don't want it, or with renders that skip the cache when they could've used it.

My thesis is this: the problem isn't memorizing the caching flags in Next.js. It's deciding how fresh each piece of data needs to be before you even open the docs. If you start from the flag, you're solving the problem backwards.

What the Official Docs Say — and What They Don't

The Next.js caching documentation describes four cache layers that interact with each other:

Request Memoization — deduplication of fetch calls with the same URL within a single render.
Data Cache — persistence of fetch responses across requests (configurable with revalidate or no-store).
Full Route Cache — static HTML + RSC payload generated at build time or runtime.
Router Cache — client-side cache for prefetching segments.

What the docs explain well: how to configure each layer, what options exist, what semantics they carry.

What the docs don't say: which one to pick based on the type of data you're serving. That's a product decision, not an API decision. And that's exactly where most people get lost.

The docs are honest about the system's limits, but not prescriptive about when each option actually makes sense. That part is on you.

Read the Flags as Data Contracts, Not Tricks

Before writing a single line of configuration, the right question isn't "which flag do I use?" It's:

How old can this data get before the user notices something is wrong?

That's the data contract. And every caching option in Next.js is a way to declare that contract explicitly.

`revalidate: N` (ISR — time-based revalidation)

// Data that changes, but not every second
// e.g.: blog posts, catalog prices with low turnover
export const revalidate = 3600 // revalidate every hour

Contract: "This data can be up to N seconds old. I'm okay with that."

When it makes sense: editorial content, product catalogs that don't change hourly, landing pages with semi-structured data.

When it doesn't make sense: real-time stock, user-personalized data, operational dashboards.

`dynamic = 'force-dynamic'`

// Every request triggers a fresh server render
// Equivalent to getServerSideProps in Pages Router
export const dynamic = 'force-dynamic'

Contract: "This data can't tolerate any staleness. I want it fresh on every request."

The uncomfortable truth about this flag: it's the easiest to slap on and the most expensive to sustain. No Full Route Cache, no Data Cache for this segment. Every single user pays the full cost of a fresh render. That can be exactly the right call — but it has to be a decision, not the default when something isn't working.

`cache: 'no-store'` on fetch

// At the individual fetch level — more granular than dynamic
const res = await fetch('https://api.example.com/sensitive-data', {
  cache: 'no-store' // never cache this response
})

Contract: "This specific piece of data should never be cached, even if other data in the same component can be."

The difference from force-dynamic is scope. no-store is surgical: it affects one specific fetch. force-dynamic disables the cache for the entire segment. If you need one fresh piece of data inside a page that otherwise has cacheable content, no-store on the fetch is the right tool.

No configuration (default)

// No revalidate, no dynamic, no cache: 'no-store'
// Next.js caches indefinitely at build time (or until manual invalidation)
const res = await fetch('https://api.example.com/static-content')

Contract: "This data is static. Generate once, serve forever, invalidate when the code changes."

Ideal for content that doesn't change between deploys: legal pages, documentation, institutional landing pages.

Where People Go Wrong (and the Hidden Cost)

The most common mistake I see in App Router projects isn't picking the wrong flag. It's not choosing consciously and letting the default decide.

Three problematic patterns:

1. force-dynamic as a universal escape hatch
When something "isn't updating properly," the first instinct is to throw force-dynamic at it. It works. But if the data could tolerate 5 minutes of staleness, you're paying the full render-per-request cost for no reason. There's no magic number here — it depends on your traffic volume and infrastructure — but the cost is real and worth measuring.

2. Mixing revalidate in layout and page without understanding inheritance
The docs are clear: the most restrictive segment wins. If the layout has revalidate = 0 (equivalent to force-dynamic) and the page has revalidate = 3600, the segment will render dynamically regardless. This catches a lot of people off guard because the page config "looks like it's being ignored."

3. Assuming revalidate is exact
ISR with revalidate: 60 does not guarantee your data updates exactly at 60 seconds. Revalidation is stale-while-revalidate: the first request after expiration returns stale data and triggers a background regeneration. The next request — which could be milliseconds or minutes later depending on traffic — gets the fresh data. If your system needs strict time-based consistency, ISR is not the right tool.

Decision Matrix: Which Flag Does Each Data Need

Before touching any configuration, answer these questions:

Question	Answer → option
Does the data change between deploys?	No → default (static)
Can it tolerate N seconds/minutes of staleness?	Yes → `revalidate: N`
Does it need to be fresh on each request, but only this one fetch?	Yes → `cache: 'no-store'` on the fetch
Does the entire segment need to be fresh on every request?	Yes → `dynamic = 'force-dynamic'`
Does the data depend on the authenticated user, headers, or cookies?	Yes → `force-dynamic` or `cookies()`/`headers()` (they activate dynamic automatically)

A note on that last row: in App Router, calling cookies() or headers() inside a Server Component automatically activates dynamic rendering for that segment, even if you never declare force-dynamic. This is documented behavior, but it surprises people constantly.

Reference Snippet: ISR with On-Demand Revalidation

This pattern combines time-based revalidate with on-demand revalidation via a Route Handler. It's useful when content changes unpredictably but you can fire an invalidation from a webhook or CMS:

// app/blog/[slug]/page.tsx
export const revalidate = 3600 // fallback: revalidate every hour

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache'
import { NextRequest } from 'next/server'

export async function POST(request: NextRequest) {
  const { path } = await request.json()

  // Validate that the request comes from a trusted source
  // (e.g.: secret token from the CMS)
  revalidatePath(path)

  return Response.json({ revalidated: true })
}

This isn't a production-ready recipe — it's a starting point. Webhook authentication, error handling, and path strategy are decisions that depend on your specific system.

Honest Limits: What You Can't Conclude Without Real Data

Before wrapping up, I want to be clear about what this guide does not prove:

There are no performance benchmarks here. The impact depends on request volume, deploy infrastructure (Vercel, Railway, self-hosted), and the response time of your external data sources. Without measurement in a real context, any number is folklore.
The Router Cache (client) interacts with the Full Route Cache (server) in ways that can genuinely surprise you. The official docs describe the cases, but the concrete behavior in an app with complex navigation is worth validating with Next.js DevTools or server logs.
ISR in self-hosted environments doesn't behave exactly the same as on Vercel. Some on-demand revalidation features assume specific infrastructure. Read the Next.js deploy docs for your platform before assuming behavioral parity.

If you're making a caching architecture decision for a critical system, these limits matter. Measure before you assume.

FAQ: Next.js App Router Caching

What's the difference between cache: 'no-store' and dynamic = 'force-dynamic'?
Scope. cache: 'no-store' affects a single fetch: that data doesn't cache, but the rest of the segment can still cache normally. force-dynamic disables the Full Route Cache for the entire segment: every request triggers a fresh server render, regardless of how individual fetches are configured. Use no-store when you need surgical precision; force-dynamic when the entire segment depends on fresh data or request context (user, cookies, headers).

Is revalidate: 0 the same as force-dynamic?
In practice, yes. The Next.js docs indicate that revalidate: 0 opts into dynamic rendering. But for clarity of intent, force-dynamic is more explicit and less ambiguous for whoever reads the code later.

What happens if I have different revalidate values in the layout and the page?
The most restrictive value wins (the lowest one). If the layout has revalidate = 60 and the page has revalidate = 3600, the segment revalidates every 60 seconds. This can make the page config look ignored — but it's documented behavior. Always check the configuration of layouts wrapping your pages.

How do I know if a Server Component is rendering statically or dynamically?
Run next build and look at the terminal output: static routes are marked (●), dynamic (λ), and ISR (◐). You can also use the Next.js dev toolbar in local development, which shows the render mode for each segment.

Does the client Router Cache interfere with my server-side configurations?
Yes, and it's a common source of confusion. The Router Cache stores visited segments on the client for a configurable duration — separate from the server cache. You can control this with staleTimes in your Next.js config (available since Next.js 14.2). If data looks stale on back navigation even though the server is revalidating correctly, the Router Cache is your first suspect.

Does ISR work the same in all deploy environments?
Not exactly. On Vercel, ISR has native CDN-level support. In self-hosted environments (Railway, VPS, Docker), revalidation works but depends on the Node.js server implementation and doesn't necessarily distribute the cache across instances. The Next.js docs have a specific section on self-hosting that's worth reading before assuming behavioral parity.

Closing: The Decision Comes Before the Flag

Next.js App Router caching isn't complicated when you read it as a system of contracts. Each option declares something about the staleness the data can tolerate. The work isn't memorizing which flag does what — the docs solve that in two minutes. The work is knowing, before you write a single line, how old each piece of information you're serving is allowed to get.

If you have data that changes every 5 minutes and you're serving it with the static default, you're breaking the contract without realizing it. If you have editorial content that could cache for hours and you're using force-dynamic, you're paying a cost nobody consciously approved.

My practical recommendation: before touching the configuration of any page or layout, write a comment answering "how old can this data get?" If you can't answer that question, the technical conversation hasn't started yet.

The concrete next step: open the next build output and look at which routes are static, which are dynamic, and which are ISR. If there are surprises, that's where the real investigation begins.

Original sources:

Next.js caching docs — App Router

If you're into the idea of implicit contracts in infrastructure, I have related posts on Docker healthchecks and what they actually measure and digital signatures: the difference between format, certificate, and validation policy that follow the same logic.

This article was originally published on juanchi.dev

Next.js App Router caching: revalidate, dynamic y no-store sin folklore

Juan Torchia — Sun, 05 Jul 2026 12:00:50 +0000

Next.js App Router caching: revalidate, dynamic y no-store sin folklore

Hay un momento muy específico en el desarrollo con App Router que conozco bien: alguien agrega export const dynamic = 'force-dynamic' a una page, el build pasa, y todos respiran. El dato está fresco. El problema... es que nadie sabe exactamente por qué funciona, ni cuándo deja de ser la respuesta correcta.

Eso es folklore. Y el folklore en caching se paga caro: o con datos viejos cuando no querés, o con renders que no cachean cuando podrían.

Mi tesis es esta: el problema no es memorizar los flags de caching en Next.js. Es decidir la frescura que necesita cada dato antes de agarrar la documentación. Si arrancás desde el flag, estás resolviendo el problema al revés.

Qué dice la documentación oficial y qué NO dice

La documentación de caching de Next.js describe cuatro capas de cache que interactúan entre sí:

Request Memoization — deduplicación de fetch con mismo URL dentro de un render.
Data Cache — persistencia de respuestas de fetch entre requests (configurable con revalidate o no-store).
Full Route Cache — HTML + RSC payload estático generado en build o en runtime.
Router Cache — cache del lado del cliente para prefetching de segmentos.

Lo que la doc explica bien: cómo configurar cada capa, qué opciones existen, qué semántica tienen.

Lo que la doc no dice: cuál elegir según el tipo de dato que estás sirviendo. Eso es una decisión de producto, no de API. Y ahí es exactamente donde la mayoría se pierde.

La doc es honesta sobre los límites del sistema, pero no prescriptiva sobre cuándo cada opción tiene sentido. Esa parte la ponés vos.

Leer los flags como contratos de datos, no como trucos

Antes de escribir una sola línea de configuración, la pregunta correcta no es "¿qué flag uso?". Es:

¿Qué tan viejo puede estar este dato antes de que el usuario note que algo está mal?

Eso es el contrato de datos. Y cada opción de caching en Next.js es una manera de declarar ese contrato explícitamente:

`revalidate: N` (ISR — revalidación por tiempo)

// Datos que cambian, pero no cada segundo
// Ej: posts de un blog, precios de catálogo con baja rotación
export const revalidate = 3600 // revalida cada hora

Contrato: "Este dato puede tener hasta N segundos de antigüedad. Estoy de acuerdo con eso."

Cuando tiene sentido: contenido editorial, catálogos de productos que no cambian por hora, páginas de landing con datos semiestructurados.

Cuando no tiene sentido: stock en tiempo real, datos personalizados por usuario, dashboards operativos.

`dynamic = 'force-dynamic'`

// Cada request genera un render nuevo en el servidor
// Equivalente a getServerSideProps en Pages Router
export const dynamic = 'force-dynamic'

Contrato: "Este dato no puede tener ninguna antigüedad tolerable. Lo quiero fresco en cada request."

Lo incómodo de este flag: es el más fácil de poner y el más caro de sostener. No hay Full Route Cache, no hay Data Cache para este segmento. Cada usuario que entra paga el costo de un render completo. Eso puede ser exactamente lo correcto — pero tiene que ser una decisión, no el default cuando algo no funciona.

`cache: 'no-store'` en fetch

// A nivel de fetch individual — más granular que dynamic
const res = await fetch('https://api.ejemplo.com/datos-sensibles', {
  cache: 'no-store' // nunca cachear esta respuesta
})

Contrato: "Este dato específico nunca debe cachear, aunque otros datos en el mismo componente sí puedan."

La diferencia con force-dynamic es el alcance. no-store es quirúrgico: afecta un fetch puntual. force-dynamic desactiva el cache del segmento completo. Si necesitás un dato fresco en medio de una page que tiene otros datos cacheables, no-store en el fetch es la herramienta correcta.

Sin configuración (default)

// Sin revalidate, sin dynamic, sin cache: 'no-store'
// Next.js cachea indefinidamente en build time (o hasta invalidación manual)
const res = await fetch('https://api.ejemplo.com/contenido-estatico')

Contrato: "Este dato es estático. Genera una vez, servís siempre, invalidás cuando cambia el código."

Ideal para contenido que no cambia entre deploys: páginas legales, documentación, landings institucionales.

Donde se equivoca la gente (y el costo oculto)

El error más común que veo en proyectos con App Router no es elegir el flag equivocado. Es no elegir conscientemente y dejar que el default decida.

Tres patrones problemáticos:

1. force-dynamic como escape hatch universal
Cuando algo "no actualiza bien", el primer instinto es poner force-dynamic. Funciona. Pero si el dato podría tolerar 5 minutos de antigüedad, estás pagando el costo de un render por request sin necesidad. No hay número mágico aquí — depende del volumen del sitio y de la infraestructura — pero el costo existe y vale medirlo.

2. Mezclar revalidate en layout y en page sin entender la herencia
La documentación aclara: el segmento más restrictivo gana. Si el layout tiene revalidate = 0 (equivalente a force-dynamic) y la page tiene revalidate = 3600, el segmento va a renderizar dinámicamente igual. Esto sorprende a mucha gente porque la configuración de la page "parece ignorada".

3. Asumir que revalidate es exacto
ISR con revalidate: 60 no garantiza que el dato se actualice exactamente a los 60 segundos. La revalidación es stale-while-revalidate: el primer request después de expirar devuelve el dato viejo y dispara la regeneración en background. El siguiente request —que puede ser milisegundos o minutos después, según el tráfico— ya trae el dato nuevo. Si el sistema necesita consistencia estricta por tiempo, ISR no es la herramienta correcta.

Matriz de decisión: qué flag necesita cada dato

Antes de tocar la configuración, respondé estas tres preguntas:

Pregunta	Respuesta → opción
¿El dato cambia entre deploys?	No → default (estático)
¿Puede tolerar N segundos/minutos de antigüedad?	Sí → `revalidate: N`
¿Necesita ser fresco en cada request, pero solo este fetch?	Sí → `cache: 'no-store'` en el fetch
¿Todo el segmento necesita ser fresco en cada request?	Sí → `dynamic = 'force-dynamic'`
¿El dato depende del usuario autenticado o de headers/cookies?	Sí → `force-dynamic` o `cookies()`/`headers()` (activan dynamic automáticamente)

Una nota sobre la última fila: en App Router, usar cookies() o headers() dentro de un Server Component activa automáticamente el renderizado dinámico para ese segmento, aunque no declares force-dynamic. Esto es un comportamiento documentado que vale tener claro.

Snippet de referencia: ISR con revalidación por demanda

Este patrón combina revalidate por tiempo con revalidación por demanda vía Route Handler. Es útil cuando el contenido cambia de forma impredecible pero podés disparar una invalidación desde un webhook o un CMS:

// app/blog/[slug]/page.tsx
export const revalidate = 3600 // fallback: revalida cada hora

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache'
import { NextRequest } from 'next/server'

export async function POST(request: NextRequest) {
  const { path } = await request.json()

  // Validar que el request viene de una fuente confiable
  // (ej: token secreto del CMS)
  revalidatePath(path)

  return Response.json({ revalidated: true })
}

No es una receta lista para producción — es un punto de partida. La validación de autenticidad del webhook, el manejo de errores y la estrategia de paths son decisiones que dependen de cada sistema.

Límites honestos: qué no podés concluir sin datos reales

Antes de cerrar, quiero ser claro sobre lo que esta guía no prueba:

No hay benchmarks de rendimiento entre opciones. El impacto depende del volumen de requests, la infraestructura de deploy (Vercel, Railway, self-hosted) y el tiempo de respuesta de los datos externos. Sin medición en contexto real, cualquier número es folklore.
El comportamiento del Router Cache (cliente) interactúa con el Full Route Cache (servidor) de maneras que pueden sorprender. La documentación oficial describe los casos, pero el comportamiento concreto en una app con navegación compleja conviene validarlo con las DevTools de Next.js o con logs.
ISR en entornos self-hosted no se comporta exactamente igual que en Vercel. Algunas características de revalidación por demanda asumen infraestructura específica. Revisá la documentación de deploy de Next.js para vos plataforma.

Si estás tomando una decisión de arquitectura de caching en un sistema crítico, estos límites importan. Medí antes de asumir.

FAQ: Next.js App Router caching

¿Cuál es la diferencia entre cache: 'no-store' y dynamic = 'force-dynamic'?
El alcance. cache: 'no-store' afecta un fetch individual: ese dato no cachea, pero el resto del segmento puede seguir cacheando. force-dynamic desactiva el Full Route Cache para el segmento completo: cada request hace un render nuevo en el servidor, sin importar cómo configuren los fetches individuales. Usá no-store cuando necesitás precisión quirúrgica; force-dynamic cuando todo el segmento depende de datos frescos o del contexto del request (usuario, cookies, headers).

¿revalidate: 0 es lo mismo que force-dynamic?
En la práctica, sí. La documentación de Next.js indica que revalidate: 0 equivale a optar por renderizado dinámico. Pero para mayor claridad de intención en el código, force-dynamic es más explícito y menos ambiguo para quien lee el código después.

¿Qué pasa si tengo revalidate diferente en el layout y en la page?
Gana el valor más restrictivo (el más bajo). Si el layout tiene revalidate = 60 y la page tiene revalidate = 3600, el segmento revalida cada 60 segundos. Esto puede hacer que la configuración de la page parezca ignorada, pero es el comportamiento documentado. Revisá siempre la configuración de los layouts que envuelven los pages.

¿Cómo sé si un Server Component está renderizando estático o dinámico?
Con next build podés ver en la salida del terminal qué rutas quedaron estáticas (●), dinámicas (λ) o ISR (◐). También podés usar la barra de herramientas de desarrollo de Next.js en desarrollo local, que indica el modo de renderizado de cada segmento.

¿El Router Cache del cliente interfiere con mis configuraciones de servidor?
Sí, y es una fuente común de confusión. El Router Cache guarda en el cliente los segmentos visitados por un tiempo configurable (distinto al cache del servidor). Podés controlar esto con staleTimes en la configuración de Next.js (disponible desde Next.js 14.2). Si los datos parecen viejos en navegación de vuelta atrás aunque el servidor esté revalidando, el Router Cache es el primer sospechoso.

¿ISR funciona igual en todos los entornos de deploy?
No exactamente. En Vercel, ISR tiene soporte nativo a nivel de CDN. En entornos self-hosted (Railway, VPS, Docker), la revalidación funciona pero depende de la implementación del servidor de Node.js y no necesariamente distribuye el cache entre instancias. La documentación de Next.js tiene una sección específica sobre self-hosting que vale leer antes de asumir paridad de comportamiento.

Cierre: la decisión antes del flag

El caching de Next.js App Router no es complicado cuando lo leés como un sistema de contratos. Cada opción declara algo sobre la frescura que acepta el dato. El trabajo no es memorizar cuál flag hace qué — eso lo resuelve la documentación en dos minutos. El trabajo es tener claro, antes de escribir una línea, cuánta antigüedad puede tolerar cada pieza de información que servís.

Si tenés un dato que cambia cada 5 minutos y lo estás sirviendo con el default estático, estás rompiendo el contrato sin saberlo. Si tenés contenido editorial que podría cachear por horas y usás force-dynamic, estás pagando un costo que nadie aprobó conscientemente.

Mi recomendación práctica: antes de tocar la configuración de cualquier page o layout, escribí en un comentario la respuesta a "¿qué tan viejo puede estar este dato?". Si no podés responder esa pregunta, la conversación técnica no arrancó todavía.

El próximo paso concreto: abrí el output de next build y mirá qué rutas quedaron estáticas, cuáles dinámicas y cuáles ISR. Si hay sorpresas, ahí empieza la investigación real.

Fuentes originales:

Next.js caching docs — App Router

Si te interesa el tema de contratos implícitos en infraestructura, tengo posts relacionados sobre Docker healthchecks y qué miden de verdad y firma digital: la diferencia entre formato, certificado y política de validación que siguen la misma lógica.

Este artículo fue publicado originalmente en juanchi.dev

Docker healthchecks: what they actually measure and what you shouldn't promise

Juan Torchia — Fri, 03 Jul 2026 12:01:57 +0000

Docker healthchecks: what they actually measure and what you shouldn't promise

Why do we treat a Docker healthcheck like it's a full health monitoring system when the official documentation promises nothing of the sort? You've been running containers for months, the Railway dashboard shows "healthy" in green, and somehow you assume the app is fine. That assumption bothers me. And I think it's worth putting it under pressure.

My thesis is straightforward: a healthcheck that only confirms the process responds can hide entire business failures. The mechanism does what it says it does — nothing more, nothing less. The problem is what we promise on top of it.

Docker healthcheck: what the docs say and what they DON'T

The official HEALTHCHECK reference is clear about its scope. The HEALTHCHECK instruction defines a command that Docker runs periodically inside the container to know whether that container "works." If the command returns exit code 0, the container is healthy. If it returns 1, it's unhealthy. If it returns 2, it's ignored (reserved code).

# Minimal example from the official documentation
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

The available parameters are:

--interval: how often it runs (default: 30s)
--timeout: maximum time for the command to respond (default: 30s)
--start-period: initial grace period for the container to start up (default: 0s)
--retries: how many consecutive failures mark it unhealthy (default: 3)

What the documentation doesn't say is that the /health endpoint verifies the real state of the application. That's the responsibility of whoever implements it. Docker only evaluates the exit code of the command — it doesn't read the response body, doesn't parse JSON, doesn't know if the database is down or if a queue is accumulating unprocessed messages.

The uncomfortable truth: most examples floating around in tutorials use curl -f against an endpoint that returns {"status":"ok"} without connecting to anything real. It's a healthcheck that only confirms the Node, Go, or Java process started and is accepting TCP connections. That has value — but it's very limited value.

Where people go wrong: the common recipe and its hidden cost

The most frequent pattern showing up in public Docker setups looks like this:

# Common pattern — measures TCP, not business logic
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

And on the app side, the endpoint does something like this:

// Handler that only confirms the server is responding
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok' });
});

The container shows up as healthy. The orchestrator doesn't restart it. Railway shows green. And meanwhile, the PostgreSQL connection could be timing out, the connection pool exhausted, or a critical worker silently dead.

The hidden cost isn't that the healthcheck lies — it's that we believe it more than we should. When a team assumes "healthy = app is fine," they stop looking at logs, metrics, and richer signals. The healthcheck becomes the invisible scapegoat: if the dashboard is green, the problem must be somewhere else.

There's a counterexample that applies to any typical system: imagine a backend that processes payments. The /health endpoint returns 200, the container is healthy, but the payment gateway client has an expired token. Every transaction fails silently. Docker knows nothing about that — and it shouldn't have to, if the endpoint doesn't check for it.

Decision matrix: when to trust the healthcheck and when to go further

This matrix isn't absolute — it's a sensible criterion for deciding what to verify and from where:

Signal	What it detects	What it DOESN'T detect	Best tool
Basic `HEALTHCHECK` (curl TCP)	Process started, port open	DB failures, broken logic, queues	First-level triage
`/health` endpoint with DB ping	Database connectivity	Corrupt data, permissions, migrations	Basic readiness
Deep `/health` endpoint	Critical dependencies responding	Degraded latency, silent errors	Startup checks in prod
Application metrics (Prometheus, logs)	Errors per route, latencies, queues	Problems outside the app's scope	Real observability
External alerts (uptime monitors)	Availability from outside the container	Internal process state	SLA and contracts

When to trust the basic healthcheck:

So Docker/Railway restarts the container if the process dies or goes zombie.
To prevent a container that's still starting up from receiving traffic (with --start-period).
As a first-level triage tool in local development.

When to go further:

If the service has critical external dependencies (DB, caches, third-party APIs).
If a silent failure has direct business cost.
If the container keeps restarting but the problem persists because the error isn't process-level.

A useful question before writing the endpoint: ask what you want Docker to do if this check fails. If the answer is "restart the container," verify that restarting actually fixes that kind of failure. If the problem is a downed DB, restarting the container doesn't help — and it can trigger a restart loop that makes things worse.

Common mistakes and gotchas the documentation doesn't warn you about

1. --start-period too short for heavy apps.
Apps with migrations, cache warmup, or slow initialization need a generous --start-period. If the first checks fail before the app finishes starting up, Docker can mark the container unhealthy before it's even ready. In Railway, that can translate into premature restarts.

2. The /health endpoint that does too much.
If the check connects to the DB, calls an external API, and verifies storage on every execution every 30 seconds, you're adding artificial load and creating a new failure point. A deep check can fail on timeout even when everything else is fine.

3. exit 1 with no context in the logs.
When a healthcheck fails, Docker only records that it failed — not the command output. If you don't add your own logging inside the endpoint or the script, diagnosing why the check is failing in production becomes harder than it needs to be.

# Better: wrapper script with logging before the exit
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD /bin/sh -c 'curl -fsS http://localhost:3000/health > /tmp/hc.log 2>&1 || (cat /tmp/hc.log; exit 1)'

4. Confusing liveness with readiness.
Docker HEALTHCHECK is essentially a liveness check: is the process still alive? Kubernetes explicitly separates liveness from readiness. In standalone Docker or Railway, that distinction doesn't exist at the orchestrator level — so the responsibility falls on how you design the endpoint and when you expose it.

5. Assuming "healthy" means the container is correctly receiving traffic.
HEALTHCHECK affects the status reported by docker ps and can influence restart policies, but it doesn't guarantee the load balancer (if there's one in front) is routing correctly. Those are separate layers.

FAQ: Docker healthcheck best practices

What exit codes does HEALTHCHECK accept?
Only 0 (healthy), 1 (unhealthy), and 2 (reserved, ignored). Any other code higher than that is treated as 1. The logic lives in the exit code of the command defined in CMD — Docker doesn't read stdout or the HTTP response body.

Should I include a database check in the healthcheck?
Depends on what you want Docker to do when it fails. If the DB goes down and restarting the container solves nothing, a DB ping in the healthcheck can generate restart loops with no resolution. A more sensible approach: verify the DB during app startup and fail there; use the healthcheck to confirm the process keeps responding after it's started.

How do I inspect the state of a running healthcheck?

# See state and logs of the last healthcheck
docker inspect --format='{{json .State.Health}}' <container_id> | jq

This shows the log of the last attempt, the exit code, and the timestamp — useful information for diagnosing without guessing.

Does the healthcheck affect docker compose up behavior?
Yes, if you use depends_on with condition: service_healthy. In that case, the dependent service won't start until the check passes. That's useful, but it requires --start-period to be well-calibrated; otherwise, compose can get stuck waiting indefinitely.

Does Railway use the HEALTHCHECK from the Dockerfile?
Railway respects the HEALTHCHECK defined in the Dockerfile to determine if a deploy was successful. If the check doesn't pass within the grace period, the deploy can get stuck in an error state. Worth checking the deploy logs if the service gets stuck in a loop.

When does it make sense NOT to define HEALTHCHECK?
In short-lived task containers (batch jobs, migration scripts), where the concept of "continuous health" doesn't apply. Also in local development where the overhead of configuring it doesn't add real value.

Closing: the signal is limited, and that's fine — as long as you know it

A well-configured healthcheck is a basic safety net: it detects that the process died or went zombie, and gives the orchestrator a signal to act on. That's valuable. But if you build an entire service's operations on that single signal, you're promising yourself more than the mechanism can deliver.

My stance is this: use HEALTHCHECK for what it does well — liveness — and build real observability for everything else. Structured logs, application metrics, external alerts. Not because the healthcheck is bad, but because no tool should carry responsibilities that don't belong to it.

The concrete next step: open the Dockerfile of any service you have running and ask yourself what happens if that endpoint returns 200 but the DB is down. If the answer is "I don't find out until someone reports an error," you have an observability gap that the healthcheck will never close.

If you made it this far and you're thinking about how to evaluate dependencies before adding them to an operational stack, you might find what I wrote about how to evaluate npm dependencies before pulling them into production useful. And if the topic of signals in systems resonates with you, the post on Sniffnet for monitoring network traffic follows a similar logic: tools with a clear scope, without overpromising.

Original source:

Docker HEALTHCHECK reference: https://docs.docker.com/reference/dockerfile/#healthcheck

This article was originally published on juanchi.dev

Docker healthchecks: qué miden de verdad y qué no deberías prometer

Juan Torchia — Fri, 03 Jul 2026 12:01:52 +0000

Docker healthchecks: qué miden de verdad y qué no deberías prometer

¿Por qué tratamos a un healthcheck de Docker como si fuera un monitor de salud completo cuando la documentación oficial no promete nada de eso? Llevás meses corriendo contenedores, el panel de Railway muestra "healthy" en verde, y de alguna manera asumís que la app está bien. Esa suposición me incomoda. Y creo que vale la pena ponerla en crisis.

Mi tesis es directa: un healthcheck que solo confirma que el proceso responde puede esconder fallas de negocio enteras. El mecanismo hace lo que dice que hace — ni más, ni menos. El problema está en lo que le prometemos encima.

Docker healthcheck: qué dice la documentación y qué NO dice

La referencia oficial de HEALTHCHECK es clara en su alcance. La instrucción HEALTHCHECK define un comando que Docker ejecuta periódicamente dentro del contenedor para saber si ese contenedor "funciona". Si el comando devuelve exit code 0, el contenedor es healthy. Si devuelve 1, es unhealthy. Si devuelve 2, se ignora (código reservado).

# Ejemplo mínimo de la documentación oficial
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

Los parámetros disponibles son:

--interval: cada cuánto se ejecuta (default: 30s)
--timeout: tiempo máximo para que el comando responda (default: 30s)
--start-period: gracia inicial para que el contenedor arranque (default: 0s)
--retries: cuántos fallos consecutivos marcan unhealthy (default: 3)

Lo que la documentación no dice es que ese endpoint /health verifica el estado real de la aplicación. Eso es responsabilidad del desarrollador que lo implementa. Docker solo evalúa el exit code del comando — sin leer el body de la respuesta, sin interpretar JSON, sin saber si la base de datos está caída o si una queue acumula mensajes sin procesar.

Lo incómodo: la mayoría de los ejemplos que circulan en tutoriales usan curl -f contra un endpoint que devuelve {"status":"ok"} sin conectar nada real. Es un healthcheck que solo confirma que el proceso de Node, Go o Java arrancó y acepta conexiones TCP. Eso tiene valor — pero es un valor muy limitado.

Dónde se equivoca la gente: la receta común y su costo oculto

El patrón más frecuente que aparece en setups públicos de Docker es este:

# Patrón común — mide TCP, no lógica de negocio
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

Y del lado de la app, el endpoint hace algo así:

// Handler que solo confirma que el servidor responde
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok' });
});

El contenedor aparece como healthy. El orquestador no lo reinicia. Railway muestra verde. Y mientras tanto, la conexión a PostgreSQL puede estar en timeout, el pool de conexiones agotado, o un worker crítico silenciosamente caído.

El costo oculto no es que el healthcheck mienta — es que le creemos más de lo que debería. Cuando un equipo asume que "healthy = app sana", deja de mirar logs, métricas y señales más ricas. El healthcheck se convierte en el chivo expiatorio invisible: si el panel está verde, el problema tiene que estar en otro lado.

Hay un contraejemplo que vale para cualquier sistema típico: imaginá un backend que procesa pagos. El endpoint /health responde 200, el contenedor está healthy, pero el cliente de la pasarela de pago tiene un token expirado. Cada transacción falla silenciosamente. Docker no sabe nada de eso — y no tendría por qué saberlo, si el endpoint no lo verifica.

Matriz de decisión: cuándo confiar en el healthcheck y cuándo ir más lejos

Esta matriz no es absoluta — es un criterio prudente para decidir qué verificar y desde dónde:

Señal	Qué detecta	Qué NO detecta	Herramienta más adecuada
`HEALTHCHECK` básico (curl TCP)	Proceso arrancado, puerto abierto	Fallas de DB, lógica rota, queues	Primer nivel de triaje
Endpoint `/health` con DB ping	Conectividad a base de datos	Datos corruptos, permisos, migraciones	Readiness básico
Endpoint `/health` profundo	Dependencias críticas respondiendo	Latencia degradada, errores silenciosos	Startup checks en prod
Métricas de aplicación (Prometheus, logs)	Errores por ruta, latencias, colas	Problemas fuera del scope de la app	Observabilidad real
Alertas externas (uptime monitors)	Disponibilidad desde fuera del contenedor	Estado interno del proceso	SLA y contratos

Cuándo confiar en el healthcheck básico:

Para que Docker/Railway reinicie el contenedor si el proceso muere o queda zombi.
Para evitar que un contenedor que todavía está arrancando reciba tráfico (con --start-period).
Como primer nivel de triaje en desarrollo local.

Cuándo ir más lejos:

Si el servicio tiene dependencias externas críticas (DB, caches, APIs de terceros).
Si una falla silenciosa tiene costo de negocio directo.
Si el contenedor se reinicia pero el problema persiste porque el error no es de proceso.

Un criterio útil antes de escribir el endpoint: preguntá qué querés que haga Docker si este check falla. Si la respuesta es "reiniciar el contenedor", verificá que reiniciar realmente solucione ese tipo de falla. Si el problema es una DB caída, reiniciar el contenedor no ayuda — y puede generar un loop de reinicios que agrava la situación.

Errores comunes y gotchas que la documentación no anticipa

1. --start-period demasiado corto para apps pesadas.
Apps con migraciones, warmup de caché o inicialización lenta necesitan un --start-period generoso. Si los primeros checks fallan antes de que la app termine de arrancar, Docker puede marcar el contenedor como unhealthy antes de que esté listo. En Railway, eso puede traducirse en reinicios prematuros.

2. El endpoint /health que hace demasiado.
Si el check conecta a la DB, llama a una API externa y verifica storage en cada ejecución cada 30 segundos, estás agregando carga artificial y creando un punto de falla nuevo. Un check profundo puede fallar por timeout aunque todo lo demás esté bien.

3. exit 1 sin contexto en los logs.
Cuando el healthcheck falla, Docker solo registra que falló — no el output del comando. Si no agregás logging propio dentro del endpoint o del script, diagnosticar por qué el check falla en producción se vuelve más difícil de lo necesario.

# Mejor: script wrapper con logging antes del exit
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD /bin/sh -c 'curl -fsS http://localhost:3000/health > /tmp/hc.log 2>&1 || (cat /tmp/hc.log; exit 1)'

4. Confundir liveness con readiness.
Docker HEALTHCHECK es básicamente un liveness check: ¿el proceso sigue vivo? Kubernetes separa liveness de readiness de manera explícita. En Docker standalone o en Railway, esa distinción no existe a nivel de orquestador — así que la responsabilidad cae en cómo diseñás el endpoint y cuándo lo exponés.

5. Asumir que "healthy" implica que el contenedor recibe tráfico correctamente.
HEALTHCHECK afecta el estado reportado por docker ps y puede influir en políticas de reinicio, pero no garantiza que el load balancer (si hay uno por delante) esté enrutando bien. Son capas distintas.

FAQ: Docker healthcheck buenas prácticas

¿Qué exit codes acepta HEALTHCHECK?
Solo 0 (healthy), 1 (unhealthy) y 2 (reserved, ignorado). Cualquier otro código mayor se trata como 1. La lógica está en el exit code del comando definido en CMD — Docker no lee el stdout ni el body HTTP.

¿Debería incluir un check de base de datos en el healthcheck?
Depende de qué querés que haga Docker cuando falle. Si la DB cae y reiniciar el contenedor no soluciona nada, un DB ping en el healthcheck puede generar loops de reinicio sin resolución. Una opción más prudente: verificar la DB en el startup de la app y fallar ahí; usar el healthcheck para confirmar que el proceso sigue respondiendo después de arrancar.

¿Cómo inspecciono el estado de un healthcheck en ejecución?

# Ver estado y logs del último healthcheck
docker inspect --format='{{json .State.Health}}' <container_id> | jq

Esto muestra el log del último intento, el exit code y el timestamp — información útil para diagnosticar sin adivinar.

¿El healthcheck afecta el comportamiento de docker compose up?
Sí, si usás depends_on con condition: service_healthy. En ese caso, el servicio dependiente no arranca hasta que el check pase. Eso es útil, pero requiere que --start-period esté bien calibrado; si no, el compose puede quedarse esperando indefinidamente.

¿Railway usa el HEALTHCHECK del Dockerfile?
Railway respeta el HEALTHCHECK definido en el Dockerfile para determinar si el deploy fue exitoso. Si el check no pasa dentro del período de gracia, el deploy puede quedar en estado de error. Vale revisar los logs del deploy si el servicio queda en loop.

¿Cuándo tiene sentido no definir HEALTHCHECK?
En contenedores de tareas cortas (batch jobs, scripts de migración), donde el concepto de "salud continua" no aplica. También en desarrollo local donde el overhead de configurarlo no aporta valor real.

Cierre: la señal es limitada, y eso está bien — si lo sabés

Un healthcheck bien configurado es una red de seguridad básica: detecta que el proceso murió o quedó zombi, y le da al orquestador una señal para actuar. Eso es valioso. Pero si construís toda la operación de un servicio sobre esa única señal, estás prometiéndote más de lo que el mecanismo puede darte.

Mi postura es esta: usá HEALTHCHECK para lo que hace bien — liveness — y construí observabilidad real para todo lo demás. Logs estructurados, métricas de aplicación, alertas externas. No porque el healthcheck sea malo, sino porque ninguna herramienta debería cargar con responsabilidades que no le corresponden.

El próximo paso concreto: abrí el Dockerfile de cualquier servicio que tengas corriendo y preguntate qué pasa si ese endpoint devuelve 200 pero la DB está caída. Si la respuesta es "no me entero hasta que alguien reporta un error", tenés un gap de observabilidad que el healthcheck nunca va a cerrar.

Si llegaste hasta acá y estás pensando en cómo evaluar las dependencias de un proyecto antes de meterlas en un stack operativo, puede interesarte lo que escribí sobre cómo evaluar dependencias npm antes de incorporarlas. Y si el tema de señales en sistemas te llama la atención, el post sobre Sniffnet para monitorear tráfico de red tiene una lógica parecida: herramientas con alcance claro, sin sobreprometer.

Fuente original:

Docker HEALTHCHECK reference: https://docs.docker.com/reference/dockerfile/#healthcheck

Este artículo fue publicado originalmente en juanchi.dev

DEV Community: Juan Torchia

Swiper: the touch slider that won't wreck your sprint

What it does

Why it made the list

When NOT to use it

Closing

Swiper: el slider táctil que no te va a arruinar el sprint

Qué hace

Por qué está en la lista

Cuándo NO usarlo

Cierre

Node.js: the runtime that changed how we think about backend

What it does

Why it's on the list

When NOT to use it

Closing thoughts

Node.js: el runtime que cambió cómo pensamos el backend

Qué hace

Por qué está en la lista

Cuándo NO usarlo

Cierre

Rate limiting in web apps: what to protect before picking a library

Rate limiting in web apps: what to protect before picking a library

Rate limiting in Next.js web apps: the real problem

What OWASP says — and what it doesn't

Where the common recipe goes wrong

Decision checklist: before you copy the middleware

1. Define the asset

2. Define the expected abuse

3. Measure the cost of the false positive

4. Define observability from day one

Honest limits: what you can't conclude without your own data

FAQ: common questions about rate limiting in Next.js

The policy before the dependency

Rate limiting en aplicaciones web: qué proteger antes de elegir una librería

Rate limiting en aplicaciones web: qué proteger antes de elegir una librería

Rate limiting en aplicaciones web con Next.js: el problema real

Qué dice OWASP y qué no dice

Dónde se equivoca la receta común

Checklist de decisión: antes de copiar el middleware

1. Definí el activo

2. Definí el abuso esperado

3. Medí el costo del falso positivo

4. Definí observabilidad desde el día uno

Límites honestos: qué no podés concluir sin datos propios

FAQ: preguntas frecuentes sobre rate limiting en Next.js

Conclusión: la política antes que la dependencia

Spring Boot Actuator: What to Expose, What to Hide, and What to Check Before Adding Endpoints

Spring Boot Actuator: What to Expose, What to Hide, and What to Check Before Adding Endpoints

Spring Boot Actuator Endpoints Security: What the Docs Say — and What They Don't

The Most Common Mistake: Enable Everything and Secure It Later (or Never)

Decision Matrix: What to Expose, What to Restrict, What to Disable Entirely

What You Can't Conclude Without Your Own Experiments, Logs, or Data

FAQ: Spring Boot Actuator Endpoints Security

My Take: Actuator Is an Operational Tool, Not a Convenience Feature

Spring Boot Actuator: qué exponer, qué ocultar y qué mirar antes de agregar endpoints

Spring Boot Actuator: qué exponer, qué ocultar y qué mirar antes de agregar endpoints

Spring Boot Actuator endpoints seguridad: qué dice la documentación y qué no dice

El error más común: habilitar todo y securizar después (o nunca)

Matriz de decisión: qué exponer, qué restringir, qué directamente no habilitar

Lo que no podés concluir sin experimento, logs o datos propios

FAQ: Spring Boot Actuator endpoints seguridad

Mi postura: Actuator es una herramienta operativa, no una opción de conveniencia

Next.js App Router Caching: revalidate, dynamic, and no-store Without the Folklore

Next.js App Router Caching: revalidate, dynamic, and no-store Without the Folklore

What the Official Docs Say — and What They Don't

Read the Flags as Data Contracts, Not Tricks

revalidate: N (ISR — time-based revalidation)

dynamic = 'force-dynamic'

cache: 'no-store' on fetch

No configuration (default)

Where People Go Wrong (and the Hidden Cost)

Decision Matrix: Which Flag Does Each Data Need

Reference Snippet: ISR with On-Demand Revalidation

Honest Limits: What You Can't Conclude Without Real Data

FAQ: Next.js App Router Caching

Closing: The Decision Comes Before the Flag

Next.js App Router caching: revalidate, dynamic y no-store sin folklore

Next.js App Router caching: revalidate, dynamic y no-store sin folklore

Qué dice la documentación oficial y qué NO dice

`revalidate: N` (ISR — time-based revalidation)

`dynamic = 'force-dynamic'`

`cache: 'no-store'` on fetch

`revalidate: N` (ISR — revalidación por tiempo)

`dynamic = 'force-dynamic'`

`cache: 'no-store'` en fetch