DEV Community: Juan Torchia

The Complete Guide to Docker HEALTHCHECK: Dockerfile vs Compose vs Orchestrator

Juan Torchia — Tue, 04 Aug 2026 12:00:17 +0000

How many times have you seen a HEALTHCHECK CMD curl -f http://localhost/health || exit 1 pasted into a Dockerfile without anyone asking what happens when that endpoint returns 200 while the database behind it is dead?

That's the scene that triggered this post. Not a production incident story — I don't have that kind of public evidence to show here — but a pattern that repeats every time someone searches "docker healthcheck", "dockerfile healthcheck" or "docker container health check" on Google expecting a quick recipe. They get one. And with that recipe, in a real deployment, the orchestrator ends up restarting healthy containers or leaving broken ones running, depending on which side the error is on.

My thesis is simple and I'll stand by it: a healthcheck with no criteria behind it — the classic copy-pasted curl to /health — is infrastructure folklore, not real observability. It's good for checking a box on a best-practices checklist. It's useless for knowing whether the container can actually serve traffic.

The real pain before you write a single line of HEALTHCHECK

The problem isn't syntax — the docs solve that in two minutes. The problem is deciding what to check, how often, and what to do when the check fails. That's where most guides stop short: they hand you the command and leave you alone with the decision that actually matters.

And that decision has concrete consequences on a stack running Next.js or Node behind PostgreSQL: a badly placed healthcheck isn't neutral. It generates false positives that restart containers mid-workload, or false negatives that keep sending traffic to a process that can no longer respond with anything useful.

What the official source says (and what it doesn't)

Docker's documentation on HEALTHCHECK is clear on the syntax side. It defines the instruction, its flags (--interval, --timeout, --start-period, --retries), and the exit codes Docker interprets: 0 healthy, 1 unhealthy, 2 reserved.

# Official Dockerfile syntax
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

That's what the official source gives you: https://docs.docker.com/reference/dockerfile/#healthcheck

What it doesn't give you — and that's the whole point of this post — is judgment about:

What that /health endpoint should actually return to be honest ("the process is alive" vs "I can talk to the database")
What interval makes sense for your real load
What happens when the orchestrator (Swarm, Kubernetes, Railway) decides what to do with an "unhealthy" container

The docs give you the tool. They don't give you the signal design.

Dockerfile vs Compose vs orchestrator: not the same question

Here's where the confusion from the three searches in the title collides. These are three distinct layers, and each answers a different question:

flowchart TD
  A[Dockerfile HEALTHCHECK] -->|defines the test| B[Docker Engine]
  B -->|marks status| C{Compose depends_on: condition}
  C -->|healthy| D[Starts the next service]
  C -->|unhealthy| E[Blocks or retries]
  B --> F{Orchestrator: Swarm/K8s}
  F -->|repeated unhealthy| G[Replaces the container]

Dockerfile defines the test itself: the command, the interval, the retries. It's the lowest layer, it lives with the image.
Compose consumes that status to sequence startup with depends_on: condition: service_healthy, or to override the HEALTHCHECK parameters without touching the image:

# docker-compose.yml
services:
  api:
    build: .
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 20s
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

The orchestrator (Swarm, Kubernetes with its own liveness/readiness probes, or a platform like Railway) decides what to do with that signal: retry, replace the container, pull it out of the load balancer. At that point Docker's HEALTHCHECK stops being the only source of truth — Kubernetes, for instance, has its own probes that don't depend on the Dockerfile's HEALTHCHECK at all.

Mixing up these three layers is exactly why someone searches "docker healthcheck" thinking there's one answer, when really they're asking three different things depending on which layer they're standing in.

Where people get it wrong: the common recipe and its hidden cost

The common recipe is this: expose a /health endpoint that returns 200 OK with a hardcoded {"status": "ok"}, and don't touch anything else. It compiles, it works in the demo, it checks the "I have a healthcheck" box.

The hidden cost shows up when that Node process is still alive — the runtime responds, the port is listening — but the PostgreSQL connection dropped, the connection pool is exhausted, or a critical external dependency isn't responding. The healthcheck says "healthy." The container can't serve a single real request.

It's the same design mistake I ran into when I talked about what to expose and what to hide in Actuator: the surface you decide to show as "status" has to reflect what actually matters, not what's easy to check. A /health that only confirms the process started is equivalent to an Actuator endpoint that returns UP without checking any real dependency.

The honest counterexample, and the one I actually worry about more: an overly strict healthcheck can do just as much damage. Picture an endpoint that checks the database, the cache, and three external services on every 10-second ping. As a rule of thumb — not something I've measured in production, but a pattern that shows up constantly in infra discussions — any transient latency spike in one of those external dependencies is enough to drag the whole container down to "unhealthy." The orchestrator restarts it, killing active connections, over a problem that most likely would've resolved itself on the next retry.

Decision matrix: what to look at before writing the CMD

Scenario	What to check	Suggested interval	Risk if you get it wrong
Simple stateless API	Process responds on the port	30s, timeout 5s	Low — not much to break
API with PostgreSQL connection	Port + lightweight query like `SELECT 1`	15-30s, high retries (3-5)	High if the check is heavy: overloads the database with pings
Worker with no HTTP port	Lock file, processed queue, own heartbeat	Depends on the job cycle	False "unhealthy" if the cycle runs longer than the interval
Service behind Compose with `depends_on`	Make sure `service_healthy` doesn't block the whole stack's startup indefinitely	Generous `start_period`	Whole stack fails to start over a too-short `start_period`
Container in an orchestrator (Swarm/K8s)	Separate liveness (is it alive?) from readiness (can it take traffic?)	Relaxed liveness, strict readiness	Cascading restarts if liveness and readiness share the same check

This matrix isn't a closed formula. It's a starting point to ask "is what I'm checking actually what fails when the service fails?" before copying the first example you find in a tutorial.

I use a similar filter for npm libraries: before putting a dependency into production, it's worth evaluating it with actual criteria instead of adding it because "everyone uses it." Same logic applies to a HEALTHCHECK — the fact that a command shows up in a hundred GitHub Dockerfiles says nothing about whether it fits your case. Popularity isn't evidence.

Common mistakes / gotchas

Using curl without having it in the final image. If the Dockerfile uses a slim or alpine base, curl might not be installed, and the healthcheck fails every single time with a "command not found" error, not because of an actual service problem.
start_period too short for apps with slow startup. If the app takes 15 seconds to come up (migrations, pool connection, warm-up) and start_period is set to 5 seconds, the container gets marked unhealthy before it's even finished booting.
Confusing liveness with readiness. A check that only confirms "the process hasn't crashed" doesn't tell you if it can serve traffic. That distinction, which Kubernetes makes explicit with two separate probes, gets lost easily when plain Docker only gives you one HEALTHCHECK.
Healthchecks that write to the database just to verify. A check that does a test INSERT every 10 seconds generates noise in the PostgreSQL logs — something you notice fast if you've ever turned on Prisma's query logging and watched that background traffic compete with the real queries.
Not logging the healthcheck result. docker inspect --format='{{json .State.Health}}' <container> gives you the history of the last checks. If you've never looked at it, it's hard to know whether the healthcheck is actually doing anything or just sitting there for decoration.

# Check the health check history of a running container
docker inspect --format='{{json .State.Health}}' mi_contenedor | jq

Limits of this guide

This is design judgment based on the official docs and known failure patterns, not an experiment with my own metrics. I don't have a reproducible benchmark comparing intervals, or a documented public production case to cite here. If you're deciding on the healthcheck for a system with a real SLA, the next step isn't reading a blog post — it's instrumenting your own system, running a controlled-load experiment, and watching the docker inspect logs over a representative period. This guide gives you the framework to design that test, not the result of having run it.

There's also no evidence here about specific Kubernetes probe behavior or Railway — every orchestrator has its own semantics, and it's worth reading its specific docs before assuming it behaves the same as Docker Compose.

FAQ

What's the difference between HEALTHCHECK in Dockerfile vs Compose?
The Dockerfile defines the image's default healthcheck. Compose can inherit it or override it with its own healthcheck section, without rebuilding the image. Useful for tuning intervals per environment (dev vs staging) without touching the Dockerfile.

What happens if I don't set any HEALTHCHECK?
Docker assumes the container is healthy as long as the main process keeps running. No active check. That's not necessarily worse than a badly designed healthcheck — sometimes "no check" is more honest than a check that lies.

What's a good interval for HEALTHCHECK?
There's no universal number. It depends on how expensive the check is and how fast you need to detect a problem. A typical reference range is 10-30 seconds with a short timeout (3-5s) and retries of 3 to 5 to avoid false positives from a transient spike.

Does HEALTHCHECK replace Kubernetes probes?
No. Kubernetes has its own livenessProbe and readinessProbe, independent of Docker's HEALTHCHECK. If you deploy on K8s, the Dockerfile's HEALTHCHECK might end up unused — the real config lives in the pod manifest.

Can I use a script instead of curl?
Yes. HEALTHCHECK's CMD accepts any command that returns an exit code of 0 or non-zero. A custom script gives you more control to check, for example, whether the PostgreSQL connection pool has available connections, instead of just hitting an HTTP port.

Can a too-strict healthcheck backfire?
Yes, and it's one of the central points of this guide. If the check depends on external services with variable latency, a transient spike can drag the container into "unhealthy" and trigger a restart that fixes nothing — because the real problem was outside the container, not inside it.

Closing: the position

A HEALTHCHECK isn't a best-practices checkbox. It's a signal that some other system — Compose, Swarm, Kubernetes, whatever platform you're using — is going to use to make an automatic decision about your container. Designing it without thinking about what decision you're going to trigger is folklore, not observability.

My concrete recommendation: before writing the CMD, write down the question that check has to answer first — "can this process serve traffic right now?" — and only then write the command. If the answer needs a SELECT 1 against PostgreSQL, let it have one. If it needs to separate liveness from readiness because the process can be alive but not ready, let it separate them. The command is the easy part. Deciding what to ask is what makes the healthcheck useful on the day something actually breaks. The uncomfortable question worth sitting with: if your healthcheck failed right now, would it be telling you the truth, or just following a script nobody re-checked?

Original source: Docker Docs - HEALTHCHECK — https://docs.docker.com/reference/dockerfile/#healthcheck

This article was originally published on juanchi.dev

Guía completa de HEALTHCHECK en Docker: Dockerfile vs Compose vs orquestador

Juan Torchia — Tue, 04 Aug 2026 12:00:12 +0000

¿Cuántas veces viste un HEALTHCHECK CMD curl -f http://localhost/health || exit 1 pegado en un Dockerfile sin que nadie se preguntara qué pasa si ese endpoint responde 200 con la base de datos caída atrás?

Esa es la escena que motiva este post. No una anécdota de incidente en producción — no tengo esa evidencia pública para mostrar acá — sino un patrón que se repite cada vez que alguien busca "docker healthcheck", "dockerfile healthcheck" o "docker container health check" en Google esperando una receta rápida. La reciben. Y con esa receta, en un despliegue real, el orquestador reinicia contenedores sanos o deja corriendo contenedores rotos, según de qué lado esté el error.

Mi tesis es simple y la sostengo: un healthcheck sin criterio, el clásico curl a /health copiado y pegado, es folklore de infraestructura, no observabilidad real. Sirve para completar un checklist de buenas prácticas. No sirve para saber si el contenedor puede atender tráfico.

El dolor real antes de escribir una línea de HEALTHCHECK

El problema no es la sintaxis — eso lo resuelve la documentación en dos minutos. El problema es decidir qué chequear, con qué frecuencia, y qué hacer cuando el chequeo falla. Ahí es donde la mayoría de las guías se quedan cortas: te dan el comando y te dejan solo con la decisión que realmente importa.

Y esa decisión tiene consecuencias concretas en un stack con Next.js o Node corriendo detrás de PostgreSQL: un healthcheck mal puesto no es neutral. Genera falsos positivos que reinician contenedores en medio de una carga de trabajo normal, o falsos negativos que dejan tráfico yendo a un proceso que ya no puede responder nada útil.

Qué dice la fuente oficial (y qué no dice)

La documentación de Docker sobre HEALTHCHECK es clara en lo sintáctico. Define la instrucción, sus flags (--interval, --timeout, --start-period, --retries) y los códigos de salida que Docker interpreta: 0 sano, 1 no sano, 2 reservado.

# Sintaxis oficial de Dockerfile
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

Eso es lo que la fuente oficial te da: https://docs.docker.com/reference/dockerfile/#healthcheck

Lo que no te da — y ahí está el punto de este post — es criterio sobre:

Qué debería devolver ese endpoint /health para ser honesto (¿solo "el proceso está vivo" o "puedo hablar con la base"?)
Qué intervalo tiene sentido para tu carga real
Qué pasa cuando el orquestador (Swarm, Kubernetes, Railway) decide qué hacer con un contenedor "unhealthy"

La documentación te da la herramienta. No te da el diseño de la señal.

Dockerfile vs Compose vs orquestador: no es la misma pregunta

Acá está la confusión que junta las tres búsquedas del título. Son tres capas distintas y cada una responde una pregunta distinta:

flowchart TD
  A[Dockerfile HEALTHCHECK] -->|define la prueba| B[Docker Engine]
  B -->|marca estado| C{Compose depends_on: condition}
  C -->|healthy| D[Levanta el siguiente servicio]
  C -->|unhealthy| E[Bloquea o reintenta]
  B --> F{Orquestador: Swarm/K8s}
  F -->|unhealthy repetido| G[Reemplaza el contenedor]

Dockerfile define la prueba en sí: el comando, el intervalo, los reintentos. Es la capa más baja, vive con la imagen.
Compose consume ese estado para ordenar el arranque con depends_on: condition: service_healthy, o para overridear los parámetros del HEALTHCHECK sin tocar la imagen:

# docker-compose.yml
services:
  api:
    build: .
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 20s
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

El orquestador (Swarm, Kubernetes con sus propios liveness/readiness probes, o una plataforma como Railway) decide qué hacer con esa señal: reintentar, reemplazar el contenedor, sacarlo del balanceo. Ahí el HEALTHCHECK de Docker deja de ser la única fuente de verdad — Kubernetes, por ejemplo, tiene sus propios probes que no dependen del HEALTHCHECK del Dockerfile.

Confundir estas tres capas es la razón por la que alguien busca "docker healthcheck" pensando que hay una sola respuesta, cuando en realidad está preguntando tres cosas distintas según en qué capa esté parado.

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

La receta común es esta: exponer un endpoint /health que devuelve 200 OK con un {"status": "ok"} hardcodeado, sin tocar nada más. Compila, funciona en el demo, pasa el checklist de "tengo healthcheck".

El costo oculto aparece cuando ese proceso Node sigue vivo — el runtime responde, el puerto escucha — pero la conexión a PostgreSQL se cayó, el pool de conexiones está agotado, o una dependencia externa crítica no responde. El healthcheck dice "sano". El contenedor no puede atender una sola request real.

Es el mismo error de diseño que discutí cuando hablé de qué exponer y qué ocultar en Actuator: la superficie que decidís mostrar como "estado" tiene que reflejar lo que de verdad importa, no lo que es fácil de chequear. Un /health que solo confirma que el proceso arrancó es equivalente a un endpoint de Actuator que devuelve UP sin chequear ninguna dependencia real.

El contraejemplo honesto, y este es el que más se pasa por alto: un healthcheck demasiado estricto puede ser igual de dañino que uno vacío. Pensalo así — si el endpoint chequea la base, el caché y tres servicios externos en cada ping cada pocos segundos, alcanza con que una sola de esas dependencias tenga una latencia transitoria para que el chequeo completo falle. El orquestador ve "unhealthy" y reinicia el contenedor, cortando conexiones activas por un problema que capaz se resolvía solo en el próximo intento. No tengo un caso productivo propio con logs para mostrar acá, pero es un patrón de fallo conocido en cualquier chequeo que agrega dependencias externas sin un timeout ajustado y sin distinguir "no puedo responder" de "una cosa que consulto está lenta".

Matriz de decisión: qué mirar antes de escribir el CMD

Escenario	Qué chequear	Intervalo sugerido	Riesgo si te equivocás
API stateless simple	Proceso responde en el puerto	30s, timeout 5s	Bajo — poco que romper
API con conexión a PostgreSQL	Puerto + query liviana tipo `SELECT 1`	15-30s, retries altos (3-5)	Alto si el chequeo es pesado: sobrecarga la base con pings
Worker sin puerto HTTP	Archivo de lock, cola procesada, heartbeat propio	Depende del ciclo del job	Falso "unhealthy" si el ciclo es más largo que el intervalo
Servicio detrás de Compose con `depends_on`	Que el `service_healthy` no bloquee el arranque de todo el stack indefinidamente	`start_period` generoso	Stack entero no levanta por un `start_period` corto
Contenedor en orquestador (Swarm/K8s)	Separar liveness (¿está vivo?) de readiness (¿puede recibir tráfico?)	Liveness relajado, readiness estricto	Reinicios en cascada si liveness y readiness comparten el mismo chequeo

Esta matriz no es una fórmula cerrada. Es un punto de partida para preguntarte "¿esto que estoy chequeando es lo que realmente falla cuando el servicio falla?" antes de copiar el primer ejemplo que aparece en un tutorial.

Ya me pasó algo parecido con librerías npm: la tentación de sumar una dependencia porque "todos la usan" en vez de evaluarla con criterio propio. Con un HEALTHCHECK el vicio es idéntico — que el comando aparezca copiado en cien Dockerfiles de GitHub no dice absolutamente nada sobre si tiene sentido para tu caso puntual.

Errores comunes / gotchas

Usar curl sin tenerlo en la imagen final. Si el Dockerfile usa una imagen slim o alpine, curl puede no estar instalado y el healthcheck falla siempre por un error de "command not found", no por un problema real del servicio.
start_period demasiado corto para apps con arranque lento. Si la app tarda 15 segundos en levantar (migraciones, conexión a pool, warm-up) y el start_period es de 5 segundos, el contenedor se marca unhealthy antes de terminar de arrancar.
Confundir liveness con readiness. Un chequeo que solo confirma "el proceso no crasheó" no dice si puede atender tráfico. Esa distinción, que Kubernetes hace explícita con dos probes separados, se pierde fácil cuando en Docker plano solo hay un HEALTHCHECK.
Healthchecks que escriben en la base para verificar. Un chequeo que hace un INSERT de prueba cada 10 segundos genera ruido en los logs de PostgreSQL — algo que se nota rápido si alguna vez activaste el query logging de Prisma y viste ese tráfico de fondo compitiendo con las queries reales.
No loguear el resultado del healthcheck. docker inspect --format='{{json .State.Health}}' <container> te da el historial de los últimos chequeos. Si nunca lo miraste, es difícil saber si el healthcheck está funcionando o solo está ahí de adorno.

# Ver el historial de health checks de un contenedor corriendo
docker inspect --format='{{json .State.Health}}' mi_contenedor | jq

Límites de esta guía

Esto es criterio de diseño basado en la documentación oficial y en patrones de fallo conocidos, no un experimento con métricas propias. No tengo un benchmark reproducible que compare intervalos ni un caso productivo documentado públicamente para citar acá. Si estás decidiendo el healthcheck de un sistema con SLA real, el próximo paso no es leer un blog — es instrumentar tu propio sistema, correr un experimento con carga controlada y mirar los logs de docker inspect durante un período representativo. Esta guía te da el marco para diseñar esa prueba, no el resultado de haberla corrido.

Tampoco hay evidencia acá sobre comportamiento específico de Kubernetes probes o Railway — cada orquestador tiene su propia semántica y vale la pena leer su documentación puntual antes de asumir que se comporta igual que Docker Compose.

FAQ

¿Cuál es la diferencia entre HEALTHCHECK en Dockerfile y en Compose?
El Dockerfile define el healthcheck por defecto de la imagen. Compose puede heredarlo o sobreescribirlo con su propia sección healthcheck, sin necesidad de reconstruir la imagen. Es útil para ajustar intervalos según el entorno (dev vs staging) sin tocar el Dockerfile.

¿Qué pasa si no pongo ningún HEALTHCHECK?
Docker asume que el contenedor está sano mientras el proceso principal siga corriendo. No hay chequeo activo. No es necesariamente peor que un healthcheck mal diseñado — a veces "sin chequeo" es más honesto que un chequeo que miente.

¿Cuál es un buen intervalo para HEALTHCHECK?
No hay un número universal. Depende de qué tan caro es el chequeo y qué tan rápido necesitás detectar un problema. Un rango típico de referencia es 10-30 segundos con timeout corto (3-5s) y retries de 3 a 5 para evitar falsos positivos por un pico transitorio.

¿HEALTHCHECK reemplaza a los probes de Kubernetes?
No. Kubernetes tiene sus propios livenessProbe y readinessProbe, independientes del HEALTHCHECK de Docker. Si desplegás en K8s, el HEALTHCHECK del Dockerfile puede quedar sin uso — la configuración real vive en el manifiesto del pod.

¿Puedo usar un script en vez de curl?
Sí. El CMD de HEALTHCHECK acepta cualquier comando que devuelva código de salida 0 o distinto de 0. Un script propio te da más control para chequear, por ejemplo, si el pool de conexiones a PostgreSQL tiene conexiones disponibles, en vez de solo golpear un puerto HTTP.

¿Un healthcheck muy estricto puede ser contraproducente?
Sí, y es uno de los puntos centrales de esta guía. Si el chequeo depende de servicios externos con latencia variable, un pico transitorio puede tirar el contenedor a "unhealthy" y gatillar un reinicio que no resuelve nada — porque el problema real estaba afuera del contenedor.

Cierre: la postura

Un HEALTHCHECK no es un checkbox de buenas prácticas. Es una señal que otro sistema — Compose, Swarm, Kubernetes, la plataforma que uses — va a usar para tomar una decisión automática sobre tu contenedor. Diseñarlo sin pensar qué decisión vas a gatillar es folklore, no observabilidad.

Mi recomendación concreta: antes de escribir el CMD, escribí primero la pregunta que ese chequeo tiene que responder — "¿puede este proceso atender tráfico ahora mismo?" — y recién después el comando. Si la respuesta necesita un SELECT 1 a PostgreSQL, que lo tenga. Si necesita separar liveness de readiness porque el proceso puede estar vivo pero no listo, que lo separe. El comando es la parte fácil. La decisión de qué preguntar es la que hace que el healthcheck sirva para algo el día que algo se rompe de verdad.

La pregunta incómoda que me queda dando vueltas: ¿tu healthcheck actual lo diseñaste pensando en esto, o lo copiaste de un ejemplo y nunca lo volviste a mirar?

Fuente original: Docker Docs - HEALTHCHECK — https://docs.docker.com/reference/dockerfile/#healthcheck

Este artículo fue publicado originalmente en juanchi.dev

Qwen3 locally with Ollama: what changed in the architecture and whether it's worth switching

Juan Torchia — Sun, 02 Aug 2026 12:00:16 +0000

Qwen3 locally with Ollama: what changed in the architecture and whether it's worth switching

In 2005, when I was 16 and managing the cyber café, I learned something I still apply today: don't change what works until you can prove the new thing beats it in your scenario. Not in someone else's benchmark. Not in the vendor announcement. In yours. Every time we updated something without a clear reason, someone ended up diagnosing a connection outage at 11pm with a full house.

I see the exact same thing every time a new model drops. Qwen3 comes out, Twitter explodes, and the question nobody asks is the only one that matters: is it actually worth replacing the model you already have running in Ollama, or is this more hype than substance?

My thesis: Qwen3 is genuinely interesting for local inference, but the interesting part isn't the model itself — it's that most teams evaluate the switch backwards. They test the new model in isolation, like it, and only discover the real cost (parser breaking on <think> tokens, context window assumptions that don't hold, sampling defaults that don't transfer) once it's already in the pipeline. The thinking mode support and the code quality improvements are real, documented by the Alibaba team themselves. But for most agent pipelines running Llama 3.1 or 3.2, the jump doesn't justify blowing up your setup overnight. You need to measure first, and you need to measure the failure modes, not just the wins.

Qwen3 in Ollama: what the architecture actually says (and what it doesn't)

Qwen3 is available in Ollama (ollama.com/library/qwen3) in multiple sizes: 0.6B, 1.7B, 4B, 8B, 14B, 30B-A3B (MoE), 32B, and 235B-A22B (MoE). That's already a signal — the Qwen team isn't only targeting peak performance, they're covering the range of models a developer can actually run on reasonable hardware.

What the official Qwen blog and the Hugging Face model card document:

Prompt-activatable thinking mode: Qwen3 supports explicit reasoning (chain of thought) that can be turned on or off depending on the use case. That's useful in pipelines where you need reasoning traceability without having to maintain two separate models.
MoE variants (Mixture of Experts): the 30B-A3B and 235B-A22B models activate only a fraction of their parameters per inference. On paper, that reduces the computational cost relative to the total model size.
Extended multilingual support: the team claims support for 119 languages, including Spanish. Relevant for pipelines that need to work in languages other than English.
Improvements in reasoning and code: comparisons published by the Qwen team show solid results in code and math benchmarks against previous-generation models.

What that evidence doesn't say: the published benchmarks are the ones the team selected. I don't have my own production logs with Qwen3, and I'm not going to fabricate them. What I can do is help you reason through the switch with reproducible technical criteria.

Where people go wrong when adopting a new model

The most common mistake isn't technical — it's a judgment failure. The pattern I keep seeing:

A new model drops with flashy benchmarks.
Someone tests it with a single prompt and it "works great."
They drop it into the pipeline with no clear baseline.
Days later, something downstream starts behaving oddly — a parser choking on unexpected tokens, an output that used to be short suddenly padded with reasoning traces — and nobody can say for sure whether it's the model, the context, or both. This is the failure mode I'd flag as the one to actually test for, not something I've logged myself with Qwen3.

For a TypeScript agent pipeline running on Ollama, the hidden cost of switching models is higher than it looks:

Output format changes: Qwen3 can generate <think>...</think> tokens when thinking mode is active. If your agent's parser isn't expecting that block, it's going to break the JSON or text that downstream consumers rely on.
Different context window: Qwen3-8B declares a 128K token context window per the model card. If the pipeline assumes a smaller limit, it can behave differently in subtle ways.
Temperature and sampling: every model has a different sampling space. What worked with Llama 3.1 at temperature: 0.7 doesn't transfer directly.

// A basic checkpoint before migrating models in an Ollama pipeline
// Not a guarantee — a minimum-friction checklist

const modelConfig = {
  model: "qwen3:8b",
  // Disable thinking mode if you don't need explicit traceability
  options: {
    temperature: 0.6,
    num_ctx: 8192, // Start conservative — don't assume 128K is free in RAM
  },
  // If the pipeline parses structured JSON, add validation for <think> blocks
};

// Before deploying: run the same prompt set with the previous model
// and with Qwen3, then compare outputs. No baseline, no decision.

The thinking mode in Qwen3 is real and useful, but it requires the pipeline to handle it explicitly. If you don't, you're paying the cost of extra tokens without capturing the benefit.

Decision matrix: when does switching to Qwen3 actually make sense

This is the tool I find most useful when evaluating a model change. It's not my own production evidence — it's prudent technical judgment based on what public documentation actually lets you claim.

Scenario	Does Qwen3 add value?	Reason
Agent that needs traceable reasoning	Yes, try it	Prompt-activatable thinking mode is a real advantage
TypeScript/Python code generation pipeline	Yes, try it	Code improvements are documented
Agent parsing strict JSON with no validation layer	Not yet	`<think>` tokens can break the parser
Spanish-language pipeline with Llama 3.1 that already works	Evaluate first	The jump isn't guaranteed without your own baseline
Hardware with less than 16GB RAM running the 8B model	Careful	128K context window has a real memory cost
MoE use case (30B-A3B) on limited hardware	Test locally first	MoE reduces active compute, but total RAM is still high

The logic behind each row: if thinking mode is relevant to the use case, Qwen3 has a concrete advantage. If the pipeline already works and you don't need that capability, the migration risk outweighs the expected benefit without your own data.

This connects to something I covered in the post about Node.js and the event loop: runtime or model changes get evaluated in context, not in the abstract.

Honest limits: what you can't conclude from this evidence

Before wrapping up, I need to be explicit about what this evidence doesn't let you claim:

I don't know if Qwen3 is "better" than Llama 3.1/3.2 for your pipeline: that depends on the use case, the prompts, the hardware, and how the agent is structured. Published benchmarks are directional, not decisive.
I don't know the actual RAM consumption in your setup: the 8B model with a large context window can exceed what the technical spec suggests depending on the Ollama backend and OS.
I don't know if thinking mode will help or hurt: in pipelines that expect short, structured outputs, reasoning tokens can be expensive noise. In pipelines where reasoning quality matters more than latency, they can be genuinely valuable.
Alibaba chose the benchmarks: that doesn't invalidate them, but it's a data point to weigh when reading the evidence.

If you want to validate, the reproducible path is: spin up Qwen3 locally with Ollama, run the same prompt set from your pipeline against both the previous model and Qwen3, and compare. Without that, any conclusion is speculation.

This applies to broader infrastructure decisions too — like when I discussed what to expose and what to hide in Spring Boot Actuator: same principle, don't change what you haven't measured.

FAQ: Qwen3, Ollama, and local inference

How do I install Qwen3 in Ollama?
One command: ollama pull qwen3:8b. Replace 8b with the size that matches your hardware. Available sizes are listed at ollama.com/library/qwen3. For the 8B you need at least 8–10GB of free RAM depending on your system.

What is Qwen3's thinking mode and how do I activate it?
It's the model's ability to generate an explicit reasoning chain before delivering the final response. You activate it by including /think in the prompt or via system parameters according to the official documentation. Reasoning tokens appear in <think>...</think> blocks, and the pipeline needs to handle them if it's going to use them.

Is Qwen3 better than Llama 3.1 for TypeScript agents?
Depends on the use case. For complex reasoning and code, the published comparisons are favorable. For pipelines that already work with structured outputs and don't need reasoning traceability, the switch isn't automatically positive. Evaluate with your own baseline before migrating.

Are Qwen3's MoE models viable on consumer hardware?
The 30B-A3B activates roughly 3B parameters per inference, which reduces active compute — but the RAM needed to load the full model is still significant. It's not a 3B model in terms of memory consumption. Check the requirements before assuming it's a lightweight option.

Does Qwen3 handle English well beyond benchmarks?
The Qwen team claims support for 119 languages in the official blog. In practice, multilingual support in open models varies by domain and task type. Your own baseline is still necessary for any production pipeline.

Should I wait for the community to test Qwen3 or just install it now?
If you have a specific use case where thinking mode or code quality are relevant, installing and testing it locally has almost zero cost. If the pipeline already works and the driver for switching is "the new model dropped," wait until you have a more concrete reason.

The decision that actually matters

Qwen3 is a genuinely interesting model. The activatable thinking mode, the MoE variants, and the documented multilingual support are real improvements — not empty marketing. If you have a pipeline where traceable reasoning matters, it's worth testing.

But "worth testing" is not the same as "blow up your setup overnight." The question I ask myself every time a new model drops is the same one I learned to ask diagnosing connection outages at the cyber café: what specific problem does this solve better than what I have today? If the answer is specific, the switch makes sense. If the answer is "the benchmarks are better," that's not enough — and if that's genuinely your only answer, that's the moment to stop and go get a baseline instead of a new model.

For agent pipelines running Llama 3.1 or 3.2 that already work: spin up Qwen3 in parallel, run the same prompt set, compare. Without that, any decision is noise. And noise costs time you could be spending on something else.

If you want to keep exploring AI pipelines from a technical-criteria standpoint rather than hype, the post on how to visualize ML models with Netron is a good companion: same philosophy, different angle.

Original sources:

This article was originally published on juanchi.dev

Qwen3 en local con Ollama: qué cambió en la arquitectura y si vale el cambio

Juan Torchia — Sun, 02 Aug 2026 12:00:11 +0000

Qwen3 en local con Ollama: qué cambió en la arquitectura y si vale el cambio

En 2005, cuando administraba el cyber a los 16, aprendí algo que todavía aplico: no cambies lo que funciona hasta que puedas demostrar que lo nuevo lo supera en tu escenario. No en el benchmark de otro. No en el anuncio del fabricante. En el tuyo. Cada vez que actualizábamos algo sin criterio, alguien terminaba diagnosticando un corte de conexión a las 11pm con el local lleno de pibes esperando para jugar.

Hoy veo lo mismo cuando sale un modelo nuevo. Sale Qwen3, Twitter explota, y la pregunta que nadie se hace es la única que importa: ¿vale la pena reemplazar el modelo que ya tenés en Ollama, o es más hype que sustancia?

Mi tesis es esta: Qwen3 es genuinamente interesante para inferencia local, pero no por las razones que circulan en los hilos virales. El thinking mode activable por prompt no es "más inteligencia", es un control explícito sobre cuándo pagás el costo de tokens extra a cambio de trazabilidad. Esa es la diferencia real con Llama 3.1/3.2, y es la que determina si migrar tiene sentido para tu pipeline específico, no un promedio de benchmarks que armó el propio equipo de Alibaba.

Qwen3 en Ollama: qué dice la arquitectura (y qué no dice)

Qwen3 está disponible en Ollama (ollama.com/library/qwen3) en múltiples tamaños: 0.6B, 1.7B, 4B, 8B, 14B, 30B-A3B (MoE), 32B y 235B-A22B (MoE). Eso ya es una señal: el equipo de Qwen no apunta solo al extremo de performance, sino al rango de modelos que un desarrollador puede correr en hardware razonable.

Lo que el blog oficial de Qwen y la model card en Hugging Face documentan:

Thinking mode activable por prompt: Qwen3 soporta razonamiento explícito (cadena de pensamiento) que se puede activar o desactivar según el caso de uso. Sirve en pipelines donde necesitás trazabilidad del razonamiento, sin mantener dos modelos distintos.
Variantes MoE (Mixture of Experts): los modelos 30B-A3B y 235B-A22B activan solo una fracción de parámetros por inferencia. En papel, eso reduce el costo computacional para el tamaño total del modelo.
Soporte multilingüe extendido: el equipo declara soporte para 119 idiomas, incluyendo español. Relevante para agentes hispanohablantes.
Mejoras en razonamiento y código: las comparativas publicadas por el equipo de Qwen muestran resultados sólidos en benchmarks de código y matemáticas frente a modelos de generaciones anteriores.

Qué no dice esa evidencia: los benchmarks publicados son los que el propio equipo seleccionó. No tengo logs propios de producción con Qwen3, y no los voy a inventar. Lo que sí puedo hacer es darte un criterio técnico reproducible para que decidas con tu propia medición.

Dónde se equivoca la gente al adoptar un modelo nuevo

El error más común no es técnico: es de criterio. El patrón que veo repetirse en foros y en charlas de pasillo:

Sale un modelo nuevo con benchmarks llamativos.
Alguien lo prueba con un prompt suelto y "anda bien".
Lo meten en el pipeline sin baseline claro.
En algún punto algo empieza a fallar en producción de forma rara, y nadie puede afirmar con certeza si fue el cambio de modelo o el contexto que se armó distinto. Es una hipótesis de manual, no un log que tenga yo: si migrás sin comparar antes/después con los mismos prompts, perdés la capacidad de diagnosticarlo cuando pase.

Para un pipeline de agentes con TypeScript y Ollama, el costo oculto de cambiar de modelo es más alto de lo que parece:

Cambios en el formato de output: Qwen3 puede generar tokens de <think>...</think> cuando el thinking mode está activo. Si el parser del agente no espera ese bloque, va a romper el JSON o el texto que consume el downstream.
Context window diferente: Qwen3-8B declara una context window de 128K tokens según la model card. Si el pipeline asume un límite menor, puede comportarse distinto de formas sutiles.
Temperatura y sampling: cada modelo tiene un espacio de sampling diferente. Lo que funcionaba con Llama 3.1 con temperature: 0.7 no se transfiere directamente.

// Un punto de control básico antes de migrar modelos en un pipeline Ollama
// No es una garantía, es un checklist de fricción mínima

const modelConfig = {
  model: "qwen3:8b",
  // Desactivar thinking mode si no necesitás trazabilidad explícita
  options: {
    temperature: 0.6,
    num_ctx: 8192, // Arrancá conservador, no asumas que 128K es gratis en RAM
  },
  // Si el pipeline parsea JSON estructurado, añadí validación de bloques <think>
};

// Antes de deployar: corré el mismo conjunto de prompts con el modelo anterior
// y con Qwen3, y comparás outputs. Sin baseline, no hay decisión.

El thinking mode de Qwen3 es real y útil, pero requiere que el pipeline lo maneje explícitamente. Si no lo hacés, estás pagando el costo de tokens extra sin capturar el beneficio. Eso es lo incómodo que nadie menciona en los hilos de lanzamiento: la ventaja no es gratis, hay que codearla.

Matriz de decisión: cuándo tiene sentido cambiar a Qwen3

Esta es la herramienta que me resulta más útil cuando evalúo un cambio de modelo. No es evidencia de producción propia, es criterio técnico prudente basado en lo que la documentación pública permite afirmar.

Escenario	¿Qwen3 suma?	Razón
Agente que necesita razonamiento trazable	Sí, probá	Thinking mode activable por prompt es una ventaja real
Pipeline de generación de código TypeScript/Python	Sí, probá	Las mejoras en código están documentadas
Agente que parsea JSON estricto sin capa de validación	No todavía	Los tokens `<think>` pueden romper el parser
Pipeline hispanohablante con Llama 3.1 que ya funciona	Evaluá primero	El salto no es garantizado sin baseline propio
Hardware con menos de 16GB RAM y modelo 8B	Con cuidado	128K context window tiene costo de memoria real
Caso de uso con modelo MoE (30B-A3B) en hardware limitado	Probá en local antes	MoE reduce cómputo activo, pero RAM total sigue alta

La lógica detrás de cada fila: si el thinking mode es relevante para el caso de uso, Qwen3 tiene una ventaja concreta. Si el pipeline ya funciona y no necesitás esa capacidad, el riesgo de migración supera el beneficio esperado sin datos propios.

Esto conecta con algo que ya planteé en el post sobre Node.js y el event loop: los cambios de runtime o modelo se evalúan en contexto, no en abstracto. La abstracción es cómoda para escribir un thread, pero no paga las cuentas cuando el agente falla a las 3am.

Límites honestos: qué no podés concluir con esta evidencia

Antes de cerrar, necesito ser explícito sobre lo que esta evidencia no permite afirmar:

No sé si Qwen3 es "mejor" que Llama 3.1/3.2 en tu pipeline: eso depende del caso de uso, los prompts, el hardware y cómo está estructurado el agente. Los benchmarks publicados son orientativos, no decisivos.
No sé el consumo de RAM real en tu setup: el modelo 8B con context window grande puede exceder lo que sugiere el spec técnico dependiendo del backend de Ollama y el sistema operativo.
No sé si el thinking mode va a ayudar o molestar: en pipelines que esperan outputs cortos y estructurados, los tokens de razonamiento pueden ser ruido costoso. En pipelines donde la calidad del razonamiento importa más que la latencia, pueden valer la pena.
Los benchmarks de Alibaba los eligió Alibaba: eso no los invalida, pero es un dato para pesar la evidencia.

Si querés validar, el camino reproducible es: levantás Qwen3 en local con Ollama, corrés el mismo conjunto de prompts de tu pipeline con el modelo anterior y con Qwen3, y comparás. Sin eso, cualquier conclusión es especulación con formato de post técnico.

Esto también aplica a decisiones de infraestructura más amplias, como cuando discutí qué exponer y qué ocultar en Spring Boot Actuator: el principio es el mismo, no cambies lo que no mediste.

FAQ: Qwen3, Ollama e inferencia local

¿Cómo instalo Qwen3 en Ollama?
Con un comando: ollama pull qwen3:8b. Reemplazá 8b con el tamaño que corresponda a tu hardware. Los tamaños disponibles están en ollama.com/library/qwen3. Para el 8B necesitás al menos 8-10GB de RAM libre dependiendo del sistema.

¿Qué es el thinking mode de Qwen3 y cómo lo activo?
Es la capacidad del modelo de generar una cadena de razonamiento explícita antes de dar la respuesta final. Se activa incluyendo /think en el prompt o mediante parámetros del sistema según la documentación oficial. Los tokens de razonamiento aparecen en bloques <think>...</think> y el pipeline los tiene que manejar si los espera.

¿Qwen3 es mejor que Llama 3.1 para agentes en TypeScript?
Depende del caso de uso. Para razonamiento complejo y código, las comparativas publicadas son favorables. Para pipelines que ya funcionan con outputs estructurados y no necesitan trazabilidad de razonamiento, el salto no es automáticamente positivo. Evaluá con baseline propio antes de migrar.

¿Los modelos MoE de Qwen3 son viables en hardware de consumo?
El 30B-A3B activa aproximadamente 3B parámetros por inferencia, lo que reduce el cómputo activo, pero la RAM necesaria para cargar el modelo completo sigue siendo significativa. No es un modelo de 3B en consumo de memoria. Revisá los requerimientos antes de asumirlo como opción liviana.

¿Qwen3 soporta español bien?
El equipo de Qwen declara soporte para 119 idiomas incluyendo español en el blog oficial. En la práctica, el soporte multilingüe en modelos abiertos varía según el dominio y el tipo de tarea. Para pipelines hispanohablantes, el baseline propio sigue siendo necesario.

¿Conviene esperar a que la comunidad pruebe Qwen3 o lo instalo ya?
Si tenés un caso de uso específico donde el thinking mode o la calidad en código son relevantes, instalarlo y probarlo localmente tiene costo casi nulo. Si el pipeline ya funciona y el driver del cambio es "el modelo nuevo salió", esperá a tener un criterio más concreto.

Cierre: la decisión que importa

Qwen3 es un modelo genuinamente interesante. El thinking mode activable, las variantes MoE y el soporte multilingüe documentado son mejoras reales, no marketing vacío. Si tenés un pipeline donde el razonamiento trazable importa, vale la pena probarlo.

Pero "vale la pena probarlo" no es lo mismo que "cambiá el setup de golpe". La pregunta que me hago cada vez que sale un modelo nuevo es la misma que aprendí a hacerme diagnosticando cortes de conexión en el cyber: ¿qué problema concreto resuelve esto mejor que lo que tengo hoy? Si la respuesta es específica, el cambio tiene sentido. Si la respuesta es "los benchmarks son mejores", eso no alcanza, y lo digo habiendo migrado sistemas por peores razones que esa.

Para los pipelines de agentes hispanohablantes con Llama 3.1 o 3.2 que ya funcionan: levantá Qwen3 en paralelo, corré el mismo conjunto de prompts, comparás. Sin eso, cualquier decisión es ruido. Y el ruido cuesta tiempo que podrías estar invirtiendo en otra cosa. La pregunta incómoda que dejo sobre la mesa: ¿estás migrando porque el modelo resuelve algo que el actual no resuelve, o porque te da vergüenza seguir usando "el viejo"?

Si querés seguir explorando pipelines de IA desde criterio técnico y no desde hype, el post sobre cómo visualizar modelos ML con Netron es un buen complemento: misma filosofía, otro ángulo.

Fuentes originales:

Este artículo fue publicado originalmente en juanchi.dev

Prisma Query Logging and PostgreSQL: Where the ORM Ends and the Database Begins

Juan Torchia — Wed, 29 Jul 2026 12:00:16 +0000

You turned on log: ['query'] on the Prisma client, watched the console fill up with SELECTs and their parameters, and that's where the investigation stopped. The endpoint is still slow. The log tells you what SQL ran, but it doesn't tell you if that SQL used an index, if it waited on a lock, or if the problem is the query itself or the connection running it. That gap between "I can see the query" and "I understand why it's slow" is what this post is about.

My thesis: the log and the database answer two different categories of question, and the mistake isn't using one or the other — it's not knowing which question you're actually asking before you open either. Almost every "slow endpoint" investigation I've seen (my own included, more than once) starts by staring at the log as if staring harder would eventually reveal a lock or a missing index. It won't. The log was never built to show you that.

Prisma query logging PostgreSQL: what the ORM's log actually solves

The official Prisma docs on logging are clear about the scope: the logging system lets you subscribe to query, info, warn, and error events from the client, and every query-type event includes the generated SQL, the parameters, and the total duration of that call. That's the whole promise. Nothing about execution plans, nothing about locks, nothing about what happens inside PostgreSQL once it receives that query.

Setting it up looks like this:

// prisma-client.ts — basic logging with levels
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient({
  log: [
    { level: 'query', emit: 'event' },
    { level: 'warn', emit: 'stdout' },
    { level: 'error', emit: 'stdout' },
  ],
})

prisma.$on('query', (evento) => {
  console.log('SQL:', evento.query)
  console.log('Parametros:', evento.params)
  console.log('Duracion (ms):', evento.duration)
})

With this you already get everything the docs promise: exact SQL, parameters, total round-trip duration. That's enough to answer ORM-type questions: Is Prisma generating a JOIN I wasn't expecting? Is this findMany with a nested include firing 40 queries instead of one? Is some middleware running something twice? The log alone answers those questions, no need to touch the database.

What it does NOT answer — and to be fair to the source, the docs never claim it does — is why a specific query takes 800ms instead of 8ms. That lives on the other side.

Where people get it wrong: using the log as if it were a database profiler

The common recipe: turn on the log, notice a query taking forever, copy it, run it by hand in the SQL client, it runs "fast" there because the table's cached in the plan or because data volume at that moment is different, and close the ticket saying "it fixed itself." Three months later it happens again.

The hidden cost is that the duration number Prisma reports includes the full round trip: parameter serialization, network time to PostgreSQL, execution time in the database, and deserialization of the result back in the TypeScript client. If the connection pool is saturated or there's network latency, that number goes up without the query itself having any problem at all. The log gives you a total, not a breakdown.

Classic counterexample: a query the log shows as 300ms could be a 2ms query in PostgreSQL that spent 298ms waiting to grab a connection from the pool. If the diagnosis stops at "this query is slow, gotta optimize it," the real problem — pool configuration, number of concurrent connections, a badly set timeout — never gets touched.

flowchart LR
  A[Request llega] --> B[Prisma pide conexion al pool]
  B --> C{Pool disponible?}
  C -->|no, espera| D[Tiempo de espera se suma al log]
  C -->|si| E[PostgreSQL ejecuta la query]
  E --> F[Prisma deserializa resultado]
  D --> E
  F --> G[Log reporta duracion total]

The diagram shows why the log's number mixes together things worth separating before you touch any code.

Decision checklist: when the log is enough and when to look at PostgreSQL

This is the cutoff criteria I use before sinking time into either side:

The Prisma log is enough when:

The suspicion is about what SQL the ORM generates (N+1 queries, includes that blow up, unnecessary selects).
The problem shows up always, regardless of data volume, in any environment.
You can reproduce it with an isolated call and see the exact SQL in the console.
The question is "is this doing what I think it's doing?" and not "is this fast?"

You need to look at PostgreSQL directly when:

A specific query takes different amounts of time depending on the time of day or data volume.
The log shows high durations but the SQL, run by hand, "runs fine" — that's when the problem isn't the query.
You suspect locks, contention, or concurrent queries stepping on each other.
You need to know if an index is actually being used or not — that's what EXPLAIN ANALYZE tells you, not the ORM's log.

PostgreSQL tools that fall into this second category: EXPLAIN (ANALYZE, BUFFERS) on the exact query you captured in the log, the pg_stat_statements extension to see real accumulated execution stats over time, and pg_stat_activity to see what's running right now and whether anything's blocked. None of these get replaced by Prisma, and that's fine — it's not Prisma's job.

What to check first, in order: Prisma's log to confirm the exact SQL → run it with EXPLAIN ANALYZE to see the actual plan → if the plan looks reasonable but the log still shows high times, suspect the connection pool before suspecting the query.

I apply a version of this same split — find which layer actually caused the problem instead of fixing the layer where it just happens to surface — in other parts of the stack too. It's the same instinct behind checking how to evaluate a library before shipping it to production before blaming a dependency for something that's actually a config issue, or behind tracing a TypeScript error back to a badly defined type further up instead of patching the symptom, like I laid out in strict null checks in production. Different tools, same discipline: don't fix where it hurts, fix where it broke.

Limits: what this evidence doesn't let you conclude

Neither the Prisma docs nor this post give a figure for how much overhead logging itself adds, nor a number like "past X queries per second it's worth instrumenting the database." Any claim like that would need a reproducible experiment with controlled load, and I don't have one — I'd rather not make it up.

You also can't conclude, just from Prisma's log, whether an index is missing, whether a table needs partitioning, or whether the problem is schema design. Those conclusions require looking at PostgreSQL's real execution plan, not the client's report.

And an honest note about the source: Prisma's docs don't compare their logging against database observability tools, nor do they suggest it's a substitute. The limit I'm laying out in this post is mine, not something the docs contradict or explicitly back up — it's a reading of what the log promises versus what it doesn't.

My take and the next step

I use Prisma's log for everything that's about SQL shape: confirming the ORM generated what I expected, catching N+1s before they hit an environment with real data, checking that an include isn't pulling in extra relations. For that it's fast and needs nothing else.

The moment the question shifts from "what SQL is this?" to "why is it slow?", I close the log console and open EXPLAIN ANALYZE. Mixing both questions into the same tool is exactly what keeps people staring at logs without moving forward.

The uncomfortable part, if I'm honest: most teams don't skip EXPLAIN ANALYZE because it's hard, they skip it because the Prisma log already feels like "doing observability," and it's not — it's doing a third of it. If you're bringing more serious observability into your stack — structured logs, pool metrics, tracing — ask first what layer each tool actually covers before adding it, the same question I asked when I brought an external model into the code pipeline in DeepSeek API in TypeScript. Adding a tool because it feels thorough is how you end up with five dashboards and still no answer for why the endpoint is slow.

FAQ

Does Prisma's log show the query's execution plan?
No. It shows the generated SQL, the parameters, and the total round-trip duration. The execution plan you have to request separately with EXPLAIN ANALYZE directly in PostgreSQL.

Does turning on log: ['query'] in production have a cost?
It adds serialization and logging overhead per query, especially if the emitted level is stdout instead of event with a lightweight handler. The official docs don't give an exact figure for that cost, so it's worth measuring it in your own environment before assuming it's negligible.

Can I use Prisma's log to detect N+1 queries?
Yes, it's one of the most direct uses: if a findMany with relations fires dozens of individual queries in the log, that's your N+1 right there. It's exactly the kind of question the log answers well because it's about SQL shape, not database performance.

Does pg_stat_statements replace Prisma's logging?
It doesn't replace it, it complements it. pg_stat_statements accumulates real execution stats inside PostgreSQL over time; Prisma's log gives you the point-in-time view of each call from the client. They answer different questions.

Why does a query the log flags as slow run fast when I execute it by hand?
Because the log's number includes network time and connection pool wait time, not just execution in the database. If you run the query in isolation in a SQL client, you skip that wait and see only PostgreSQL's real time.

Is Prisma's logging useful for diagnosing locks or contention?
Not directly. For that you need to look at pg_stat_activity in PostgreSQL, which shows which sessions are running and whether any of them are blocked waiting on another. Prisma's log has no visibility into that.

Original source: Prisma logging docs

This article was originally published on juanchi.dev

Prisma Query Logging y PostgreSQL: dónde termina el ORM y empieza la base

Juan Torchia — Wed, 29 Jul 2026 12:00:11 +0000

Activaste log: ['query'] en el cliente de Prisma, viste la consola llenarse de SELECTs con sus parámetros, y ahí quedó la investigación. El endpoint sigue lento. El log te dice qué SQL se ejecutó, pero no te dice si ese SQL usó un índice, si esperó un lock, o si el problema es la query en sí o la conexión que la ejecuta. Esa distancia entre "veo la query" y "entiendo por qué tarda" es el tema de este post.

Mi tesis es simple y no es nueva, pero acá casi nadie la aplica con disciplina: el query logging de Prisma sirve para encontrar patrones — queries N+1, SQL inesperado, parámetros raros — pero no reemplaza instrumentar PostgreSQL cuando el problema es de rendimiento real. Son dos capas distintas, resuelven preguntas distintas, y mezclarlas es la razón por la que tanta gente mira logs durante media hora sin llegar a ninguna conclusión.

Prisma query logging PostgreSQL: qué resuelve el log del ORM

La documentación oficial de Prisma sobre logging es clara sobre el alcance: el sistema de logs te permite suscribirte a eventos query, info, warn y error del cliente, y cada evento de tipo query incluye el SQL generado, los parámetros y la duración total de esa llamada. Eso es todo lo que promete. No dice nada de planes de ejecución, no dice nada de locks, no dice nada de qué pasa dentro de PostgreSQL cuando recibe esa query.

Configurarlo es así:

// prisma-client.ts — logging basico con niveles
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient({
  log: [
    { level: 'query', emit: 'event' },
    { level: 'warn', emit: 'stdout' },
    { level: 'error', emit: 'stdout' },
  ],
})

prisma.$on('query', (evento) => {
  console.log('SQL:', evento.query)
  console.log('Parametros:', evento.params)
  console.log('Duracion (ms):', evento.duration)
})

Con esto ya tenés lo que la doc promete: SQL exacto, parámetros, duración total del round trip. Es suficiente para responder preguntas de tipo ORM: ¿Prisma está generando un JOIN que no esperabas? ¿Este findMany con include anidado dispara 40 queries en vez de una? ¿Un middleware está ejecutando algo dos veces? Ese tipo de preguntas las resuelve el log solo, sin tocar la base.

Lo que NO resuelve — y la doc tampoco lo promete, hay que ser justo con la fuente — es por qué una query puntual tarda 800ms en vez de 8ms. Eso vive del otro lado.

Dónde se equivoca la gente: usar el log como si fuera un profiler de base

La receta común es: activo el log, veo que una query tarda mucho, la copio, la corro a mano en el cliente SQL, ahí anda "rápido" porque la tabla está cacheada en el plan o porque el volumen de datos en ese momento es distinto, y cierro el ticket diciendo "se resolvió solo". Tres meses después vuelve a pasar. Lo vi pasar más de una vez en tickets que se reabren solos: nadie mintió, nadie fue negligente, simplemente se confundió la capa.

El costo oculto es que el número de duración que reporta Prisma incluye el viaje completo: serialización de parámetros, tiempo de red hacia PostgreSQL, tiempo de ejecución en la base, y deserialización del resultado en el cliente TypeScript. Si el pool de conexiones está saturado o hay latencia de red, ese número sube sin que la query en sí tenga ningún problema. El log te da un total, no un desglose.

Contraejemplo típico: una query que en el log muestra 300ms de duración puede ser una query de 2ms en PostgreSQL que esperó 298ms para conseguir una conexión del pool. Si el diagnóstico se queda en "esta query es lenta, hay que optimizarla", el problema real — configuración de pool, número de conexiones concurrentes, timeout mal seteado — sigue sin tocarse.

flowchart LR
  A[Request llega] --> B[Prisma pide conexion al pool]
  B --> C{Pool disponible?}
  C -->|no, espera| D[Tiempo de espera se suma al log]
  C -->|si| E[PostgreSQL ejecuta la query]
  E --> F[Prisma deserializa resultado]
  D --> E
  F --> G[Log reporta duracion total]

El diagrama muestra por qué el número del log mezcla cosas que conviene separar antes de tocar código.

Checklist de decisión: cuándo alcanza el log y cuándo mirar PostgreSQL

Esto es lo que uso como criterio de corte antes de invertir tiempo en cualquiera de los dos lados:

Alcanza con el log de Prisma cuando:

La sospecha es sobre qué SQL genera el ORM (queries N+1, includes que explotan, selects innecesarios).
El problema aparece siempre, con cualquier volumen de datos, en cualquier ambiente.
Podés reproducirlo con una llamada aislada y ver el SQL exacto en la consola.
La pregunta es "¿esto hace lo que yo creo que hace?" y no "¿esto es rápido?".

Hay que mirar PostgreSQL directamente cuando:

Una query específica tarda distinto según el momento del día o el volumen de datos.
El log muestra duraciones altas pero el SQL, corrido a mano, "anda bien" — ahí el problema no es la query.
Sospechás de locks, contención, o queries concurrentes pisándose.
Necesitás saber si un índice se está usando o no — eso lo dice EXPLAIN ANALYZE, no el log del ORM.

Herramientas de PostgreSQL que entran en esta segunda categoría: EXPLAIN (ANALYZE, BUFFERS) sobre la query exacta que capturaste en el log, la extensión pg_stat_statements para ver acumulados reales de ejecución en el tiempo, y pg_stat_activity para ver qué está corriendo ahora mismo y si hay algo bloqueado. Ninguna de estas la reemplaza Prisma, y está bien que sea así — no es su trabajo.

Qué mirar primero, en orden: log de Prisma para confirmar el SQL exacto → correrlo con EXPLAIN ANALYZE para ver el plan real → si el plan es razonable pero el log sigue mostrando tiempos altos, sospechar del pool de conexiones antes que de la query.

Lo incómodo de este criterio es que obliga a soltar la primera hipótesis. Cuesta más aceptar "no es la query, es el pool" que quedarte reescribiendo el SELECT una vez más, porque tocar la query da la sensación de estar avanzando aunque no cambie nada. Este mismo criterio de "separar la capa que generó el problema de la capa donde se manifiesta" es el mismo tipo de pregunta que me hago cuando evalúo si vale la pena sumar una dependencia nueva al proyecto — ver cómo evaluar una librería antes de meterla en producción — o cuando el compilador de TypeScript marca un error que en realidad viene de un tipo mal definido más arriba, como escribí en strict null checks en producción. No es la misma herramienta ni el mismo bug, pero la pregunta de fondo —¿dónde nació esto realmente?— se repite en cualquier capa del stack.

Límites: lo que esta evidencia no permite concluir

Ni la documentación de Prisma ni este post dan una cifra de cuánto overhead agrega el logging en sí, ni un número de "a partir de tantas queries por segundo conviene instrumentar la base". Cualquier claim de ese tipo necesitaría un experimento reproducible con carga controlada, y no lo tengo — y prefiero no inventarlo.

Tampoco se puede concluir, solo con el log de Prisma, si un índice falta, si una tabla necesita particionado, o si el problema es de diseño de esquema. Esas conclusiones requieren mirar el plan de ejecución real de PostgreSQL, no el reporte del cliente.

Y una aclaración honesta sobre la fuente: la doc de Prisma no compara su logging contra herramientas de observabilidad de base de datos ni sugiere que sea un sustituto. El límite que planteo en este post es mío, no algo que la doc contradiga ni respalde explícitamente — es una lectura de lo que el log promete versus lo que no promete.

Mi postura y el próximo paso

Uso el log de Prisma para todo lo que es forma del SQL: confirmar que el ORM generó lo que esperaba, cazar N+1 antes de que lleguen a un ambiente con datos reales, revisar que un include no esté trayendo relaciones de más. Para eso es rápido y no necesita nada extra.

En el momento en que la pregunta cambia de "¿qué SQL es?" a "¿por qué tarda?", cierro la consola del log y abro EXPLAIN ANALYZE. Mezclar las dos preguntas en la misma herramienta es lo que hace que la gente se quede mirando logs sin avanzar, y es la trampa más fácil de caer porque las dos preguntas usan el mismo texto de SQL en pantalla.

Si estás evaluando meter observabilidad más seria al stack — logs estructurados, métricas de pool, tracing — vale la misma lógica que aplico cuando incorporo cualquier pieza nueva al backend: primero entender qué capa resuelve, después decidir si hace falta. Ese mismo filtro lo usé evaluando un modelo externo en el pipeline de código — DeepSeek API en TypeScript — antes de sumarlo: separar lo que la herramienta promete de lo que uno quiere que prometa evita bastante frustración después.

Si tenés que elegir una sola cosa para hoy: la próxima vez que el log te muestre una query "lenta", antes de tocar el SQL, corré esa misma query con EXPLAIN ANALYZE aislada. Si el plan sale limpio y rápido, el problema no está en la query — está en algo que el log nunca te iba a mostrar.

FAQ

¿El log de Prisma muestra el plan de ejecución de la query?
No. Muestra el SQL generado, los parámetros y la duración total del round trip. El plan de ejecución hay que pedirlo aparte con EXPLAIN ANALYZE directamente en PostgreSQL.

¿Activar log: ['query'] en producción tiene costo?
Agrega overhead de serialización y logging por cada query, sobre todo si el nivel emitido es stdout en vez de event con un handler liviano. La doc oficial no da una cifra exacta de ese costo, así que conviene medirlo en el ambiente propio antes de asumir que es despreciable.

¿Puedo usar el log de Prisma para detectar queries N+1?
Sí, es uno de los usos más directos: si un findMany con relaciones dispara decenas de queries individuales en el log, ahí está el N+1. Es justamente el tipo de pregunta que el log resuelve bien porque es sobre forma de SQL, no sobre rendimiento de la base.

¿pg_stat_statements reemplaza al logging de Prisma?
No lo reemplaza, lo complementa. pg_stat_statements acumula estadísticas reales de ejecución dentro de PostgreSQL a lo largo del tiempo; el log de Prisma te da la vista puntual de cada llamada desde el cliente. Sirven para preguntas distintas.

¿Por qué una query que el log marca como lenta corre rápido si la ejecuto a mano?
Porque el número del log incluye tiempo de red y espera de conexión del pool, no solo ejecución en la base. Si corrés la query aislada en un cliente SQL, te salteás esa espera y ves solo el tiempo real de PostgreSQL.

¿Sirve el logging de Prisma para diagnosticar locks o contención?
No directamente. Para eso hay que mirar pg_stat_activity en PostgreSQL, que muestra qué sesiones están corriendo y si alguna está bloqueada esperando a otra. El log de Prisma no tiene visibilidad de eso.

Fuente original: Prisma logging docs

Este artículo fue publicado originalmente en juanchi.dev

npm Dependencies: How to Evaluate a Library Before It Hits Production

Juan Torchia — Tue, 28 Jul 2026 16:28:09 +0000

I opened an old package.json recently — from a practice project, not anything in production — and counted 340 lines in the node_modules listed by pnpm. One single direct dependency. Everything else, transitive. I didn't pick any of it. Somebody, at some point, needed to solve one specific problem and reached for a library, and that single decision dragged in 340 more packages sitting in that tree. I can't tell you how many of those 340 get audited or read line by line by anyone — probably close to none — but I can tell you that whoever maintains them eventually has to patch a CVE under pressure, because that's just how the ecosystem behaves.

That's the real problem: npm install takes three seconds and the decision it represents lasts years.

My thesis is simple and not original, but almost nobody applies it with discipline: adding a dependency also means taking on maintenance. It's not "using someone else's code for free." It's signing a tacit contract where you become responsible for that code continuing to work, staying secure, and staying compatible with whatever the project needs two years from now — even if the original author abandoned the repo eighteen months ago.

Evaluating npm Dependencies: Security and Maintenance Are Not the Same Thing

The official npm documentation on packages and modules explains well what a package is, how package.json gets resolved, how the dependency tree works, and semver. It's the right reference for understanding the mechanics.

What that documentation doesn't say — because it's not its job to say it — is how to evaluate whether a library is a good idea for your project. There's no "maintenance" section in the npm docs, no trust score. The mechanics of installing a package are trivial. The criteria for deciding whether it's worth installing is a completely different problem, and that's where most people improvise.

Security and maintenance aren't synonyms either, even though they get treated as if they were. A library can have zero known vulnerabilities today and be completely abandoned — nobody reviewing issues, no releases in two years, a maintainer who stopped responding. That doesn't show up in npm audit. It shows up when you need someone to fix something and there's nobody on the other side.

Where People Get It Wrong: The Common Recipe and Its Hidden Cost

The typical recipe when a problem shows up is: search npm, filter by weekly downloads, pick the one with the most GitHub stars, install, move on. It's reasonable as a first filter — downloads and stars correlate with adoption — but as the only criteria it leaves out everything that matters after day one.

Typical counterexample: a utility library with 2 million weekly downloads, but whose last commit is 3 years old and whose maintainer answered the last issue 14 months ago. High download counts often reflect past adoption, not present health — legacy projects keep pulling it because it's already in the lockfile of thousands of repos, not because anyone's choosing it again today.

The hidden cost shows up late: Node bumps a major version, something in the runtime changes, the library doesn't get updated because there's nobody to update it, and the team ends up with two ugly options — fork it and maintain it themselves, or migrate all the code depending on it under pressure, with no planning. Neither is free, and both were avoidable if someone had looked at the last commit date before installing.

Decision Matrix: What to Check Before Installing

This is what I go through, in order, before adding a new dependency to a TypeScript project:

1. Active maintenance

Last commit: less than 6 months is a good sign, more than 18 months is a red flag.
Open vs. closed issues: a ratio heavily skewed toward open suggests nobody's triaging.
Number of maintainers: just one is a single point of failure — if that person burns out, the project dies.

2. Library surface area

Does it solve a specific problem or is it a full framework? The smaller the surface, the less it can break and the less there is to audit.
How many things does it export that you're not actually going to use? Unused surface area is risk without benefit.

3. TypeScript types

Does it have its own types or does it depend on a separate @types/package? Separate types drift out of sync with the actual implementation more often than we'd like to admit.
If you're working with strict: true and strict null checks enabled, as I discussed in the post on strict null checks in production, a library with badly done types is going to generate implicit anys that the compiler won't be able to catch.

4. Transitive dependencies

Run pnpm why <package> to see what it drags in. A "lightweight" library can bring in fifteen transitive dependencies you never chose.
The more transitives, the bigger the attack surface, and the more likely a CVE in a third-level package hits you without you knowing.

5. Exit strategy

If this library gets abandoned in two years, how much does it cost to pull it out? If it's scattered across the entire codebase with no intermediate abstraction layer, the exit cost is high.
If it's replaceable with your own code in a day, the dependency risk drops a lot.

A quick, reproducible check for point 4:

# See the transitive dependency tree of a package
pnpm why nombre-del-paquete

# Audit for known vulnerabilities
pnpm audit

# See the last publish date on the npm registry
npm view nombre-del-paquete time.modified

None of these commands give you a binary answer. They give you data to decide with judgment, which is different from having an automatic rule. That same principle — evaluating with concrete data instead of trusting a tool's general reputation — is the one I apply when reviewing integrations with external models, like I mentioned when evaluating the DeepSeek API in TypeScript: the question is never "is this tool good in general?", it's "is it good for this specific thing, with this level of maintenance?".

flowchart TD
  A[Necesito resolver X] --> B{¿Lo resuelvo en menos de un dia con codigo propio?}
  B -->|si| C[Escribo codigo propio]
  B -->|no| D{¿Mantenimiento activo y tipos propios?}
  D -->|no| E[Buscar alternativa o reconsiderar]
  D -->|si| F{¿Transitivas razonables y salida clara?}
  F -->|no| E
  F -->|si| G[Instalar con abstraccion intermedia]

The Limits of This Evaluation

This matrix doesn't replace a real experiment. Everything above is upfront reading criteria — looking at metadata, history, types — it's not the same as running the library under load, measuring its behavior in the project's specific runtime, or seeing how the maintainer reacts to a real issue reported by your own team.

You also can't conclude, from "actively maintained today," that the library is going to keep being actively maintained next year. Commit history is evidence of past behavior, not a guarantee of future behavior. Projects with lone maintainers can change status overnight — new job, burnout, personal decision — and no checklist predicts that with certainty.

And watch out with npm audit specifically: it tells you which vulnerabilities are reported and cataloged today in npm's database. It doesn't tell you which vulnerabilities exist but haven't been reported yet, and it doesn't tell you whether that reported vulnerability actually applies to the usage pattern you have in your project. It's a signal, not a verdict.

If the project is critical — handles sensitive data, runs in a regulated environment, has an uptime SLA — this matrix is the starting point, not the end. That's where a deeper review is warranted: reading the entire library's source code, not just its README, and considering your own experiment with controlled load before deciding.

FAQ

How do I know if an npm library is well maintained?
Look at the date of the last commit and the last release, the number of active maintainers, and the ratio of closed versus open issues. None of these data points alone is decisive, but together they paint a fairly clear picture.

Is npm audit enough to evaluate a dependency's security?
No. npm audit checks for already-reported, cataloged vulnerabilities. It doesn't detect unknown vulnerabilities and doesn't evaluate whether your specific usage pattern actually exposes you to a listed CVE.

Is it worth using a library without its own TypeScript types?
Depends on the surface area. If it's something small with well-maintained @types, it's acceptable. If it's something central to the architecture, well-maintained proper types should be a requirement, not a luxury.

How do I check a package's transitive dependencies before installing it?
With pnpm why <package> after installing, or by checking the package's package.json on the npm registry before deciding. Looking at the tree size with tools like npm ls in dry-run mode also helps.

What do I do if the library I need is basically abandoned?
Weigh the cost of forking it yourself versus writing your own alternative scoped to the actual problem. If the surface you're using is small, a ten-line piece of your own code is often better than an external dependency with no owner.

Does pnpm change anything about this evaluation compared to npm?
The installation mechanics change — pnpm uses a shared content store and is stricter about access to undeclared dependencies — but the criteria for evaluating maintenance, types, and surface area is the same regardless of which package manager you use.

Where I Stand

I'm not going to tell you to stop using external libraries. That'd be a ridiculous stance coming from someone who works with Next.js, Docker, and half a dozen packages in every project. But every pnpm add deserves the same question you'd ask about a hire: who's on the other side, and what happens if they disappear?

Next time you're about to install something to solve a small problem, try first whether you can solve it with a ten-line function of your own. If you can't, run pnpm why after installing and look at what you brought in the door without actually deciding to. That habit, more than any checklist, is what separates a project that's maintainable three years from now from one that turns into archaeology.

Original source: npm package documentation

This article was originally published on juanchi.dev

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Juan Torchia — Tue, 28 Jul 2026 16:28:05 +0000

Abrí un package.json viejo hace poco — de un proyecto de práctica, no de nada productivo — y conté 340 líneas en el node_modules listado por pnpm. Una sola dependencia directa. El resto, transitivas. Ninguna la elegí yo.

Y ahí me quedé pensando: en algún momento alguien eligió una librería para resolver un problema puntual, sin pensar en lo que arrastraba. Es un patrón que se repite en cualquier proyecto con un lockfile de más de un año: capas de decisiones ajenas apiladas una arriba de la otra, la mayoría invisibles hasta que un CVE las obliga a mostrarse.

Ahí está el problema real: npm install tarda tres segundos y la decisión que representa dura años.

Mi tesis es simple y no es original, pero casi nadie la aplica con disciplina: agregar una dependencia también es asumir mantenimiento. No es "usar código de otro gratis". Es firmar un contrato tácito donde vos te hacés responsable de que ese código siga funcionando, siga siendo seguro y siga siendo compatible con lo que el proyecto necesite dentro de dos años — aunque el autor original haya abandonado el repo hace dieciocho meses.

Evaluar dependencias npm: seguridad y mantenimiento no son lo mismo

La documentación oficial de npm sobre paquetes y módulos explica bien qué es un paquete, cómo se resuelve package.json, cómo funciona el árbol de dependencias y semver. Es la referencia correcta para entender la mecánica.

Lo que esa documentación no dice — porque no es su trabajo decirlo — es cómo evaluar si una librería es una buena idea para el proyecto. No hay una sección de "mantenimiento" en la doc de npm, ni un score de confiabilidad. La mecánica de instalar un paquete es trivial. El criterio para decidir si conviene instalarlo es un problema completamente distinto, y ahí es donde la mayoría improvisa.

Seguridad y mantenimiento tampoco son sinónimos, aunque se los trate como si lo fueran. Una librería puede tener cero vulnerabilidades conocidas hoy y estar completamente abandonada — sin nadie revisando issues, sin releases desde hace dos años, con un mainteiner que dejó de responder. Eso no aparece en npm audit. Aparece cuando necesitás que alguien arregle algo y no hay nadie del otro lado.

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

La receta típica cuando aparece un problema es: buscar en npm, filtrar por descargas semanales, elegir la que tiene más estrellas en GitHub, instalar, seguir. Es razonable como primer filtro — descargas y estrellas correlacionan con adopción — pero como único criterio deja afuera todo lo que importa después del día uno.

Contraejemplo típico: una librería de utilidades con 2 millones de descargas semanales, pero cuyo último commit tiene 3 años y cuyo mainteiner respondió el último issue hace 14 meses. Las descargas altas muchas veces reflejan adopción pasada, no salud presente — proyectos legacy siguen bajándola porque ya está en el lockfile de miles de repos, no porque alguien la vuelva a elegir hoy.

El costo oculto aparece tarde: Node sube de versión mayor, algo en el runtime cambia, la librería no se actualiza porque no hay quién la actualice, y el equipo termina con dos opciones feas — forkearla y mantenerla ellos mismos, o migrar todo el código que depende de ella bajo presión, sin planificación. Ninguna de las dos es gratis, y las dos eran evitables si alguien hubiera mirado la fecha del último commit antes de instalar.

Matriz de decisión: qué mirar antes de instalar

Esto es lo que reviso, en orden, antes de sumar una dependencia nueva a un proyecto TypeScript:

1. Mantenimiento activo

Último commit: menos de 6 meses es buena señal, más de 18 meses es alerta.
Issues abiertos vs. cerrados: un ratio muy desbalanceado hacia abiertos sugiere que nadie triagea.
Cantidad de mainteiners: uno solo es un punto único de falla — si esa persona se cansa, el proyecto muere.

2. Superficie de la librería

¿Resuelve un problema puntual o es un framework completo? Cuanto más chica la superficie, menos cosas puede romper y menos cosas hay que auditar.
¿Cuántas cosas exporta que en realidad no vas a usar? Superficie no usada es riesgo sin beneficio.

3. Tipos de TypeScript

¿Tiene tipos propios o depende de @types/paquete separado? Los tipos separados se desincronizan de la implementación real más seguido de lo que gustaría admitir.
Si trabajás con strict: true y strict null checks activados, como comenté en el post sobre strict null checks en producción, una librería con tipos mal hechos te va a generar any implícitos que el compilador no va a poder atajar.

4. Transitive dependencies

Corré pnpm why <paquete> para ver qué arrastra. Una librería "liviana" puede traer quince dependencias transitivas que vos nunca elegiste.
Cuantas más transitivas, más superficie de ataque y más probabilidad de que un CVE en un paquete de tercer nivel te afecte sin que lo sepas.

5. Salida (exit strategy)

Si esta librería se abandona en dos años, ¿cuánto cuesta sacarla? Si está esparcida por todo el codebase sin una capa de abstracción intermedia, el costo de salida es alto.
Si es reemplazable por código propio en un día, el riesgo de dependencia baja mucho.

Un chequeo rápido y reproducible para el punto 4:

# Ver el arbol de dependencias transitivas de un paquete
pnpm why nombre-del-paquete

# Auditoria de vulnerabilidades conocidas
pnpm audit

# Ver fecha del ultimo publish en el registro de npm
npm view nombre-del-paquete time.modified

Ninguno de estos comandos te da una respuesta binaria. Te dan datos para decidir con criterio, que es distinto a tener una regla automática. Ese mismo principio — evaluar con datos concretos en vez de confiar en la reputación general de una herramienta — es el que aplico cuando reviso integraciones de modelos externos, como conté al evaluar la API de DeepSeek en TypeScript: la pregunta nunca es "¿es buena la herramienta en general?", es "¿es buena para esto específico, con este nivel de mantenimiento?".

flowchart TD
  A[Necesito resolver X] --> B{¿Lo resuelvo en menos de un dia con codigo propio?}
  B -->|si| C[Escribo codigo propio]
  B -->|no| D{¿Mantenimiento activo y tipos propios?}
  D -->|no| E[Buscar alternativa o reconsiderar]
  D -->|si| F{¿Transitivas razonables y salida clara?}
  F -->|no| E
  F -->|si| G[Instalar con abstraccion intermedia]

Los límites de esta evaluación

Esta matriz no reemplaza un experimento real. Todo lo de arriba es criterio de lectura previa — mirar metadata, historial, tipos — no es lo mismo que correr la librería bajo carga, medir su comportamiento en el runtime específico del proyecto, o ver cómo reacciona el mainteiner ante un issue real reportado por el propio equipo.

Tampoco se puede concluir, a partir de "mantenimiento activo hoy", que la librería va a seguir manteniéndose activamente el año que viene. El historial de commits es evidencia de comportamiento pasado, no una garantía de comportamiento futuro. Proyectos con mainteiners solitarios cambian de estado de golpe — por trabajo nuevo, por burnout, por decisión personal — y no hay checklist que prediga eso con certeza.

Y ojo con npm audit en particular: te dice qué vulnerabilidades están reportadas y catalogadas hoy en la base de datos de npm. No te dice qué vulnerabilidades existen pero todavía no fueron reportadas, ni te dice si esa vulnerabilidad reportada aplica realmente al patrón de uso que tenés en el proyecto. Es una señal, no un veredicto.

Si el proyecto es crítico — maneja datos sensibles, corre en un entorno regulado, tiene SLA de disponibilidad — esta matriz es el punto de partida, no el final. Ahí corresponde una revisión más profunda: leer el código fuente de la librería entera, no solo su README, y considerar un experimento propio con carga controlada antes de decidir.

FAQ

¿Cómo sé si una librería npm está bien mantenida?
Mirá la fecha del último commit y del último release, la cantidad de mainteiners activos, y el ratio de issues cerrados versus abiertos. Ninguno de estos datos solo es determinante, pero juntos dan una foto bastante clara.

¿npm audit es suficiente para evaluar la seguridad de una dependencia?
No. npm audit chequea vulnerabilidades ya reportadas y catalogadas. No detecta vulnerabilidades desconocidas ni evalúa si el patrón de uso propio te expone realmente a un CVE listado.

¿Vale la pena usar una librería sin tipos propios de TypeScript?
Depende de la superficie. Si es algo chico y con @types bien mantenido, es aceptable. Si es algo central en la arquitectura, tipos propios y bien mantenidos deberían ser un requisito, no un lujo.

¿Cómo reviso las dependencias transitivas de un paquete antes de instalarlo?
Con pnpm why <paquete> después de instalar, o revisando el package.json del paquete en el registro de npm antes de decidir. También sirve mirar el tamaño del árbol con herramientas como npm ls en modo dry-run.

¿Qué hago si la librería que necesito está prácticamente abandonada?
Evaluá el costo de forkearla vos mismo versus escribir una alternativa propia acotada al problema real. Si la superficie que usás es chica, muchas veces conviene más código propio de diez líneas que una dependencia externa sin dueño.

¿pnpm cambia algo respecto a npm en esta evaluación?
La mecánica de instalación cambia — pnpm usa un almacén de contenido compartido y es más estricto con el acceso a dependencias no declaradas — pero el criterio de evaluación de mantenimiento, tipos y superficie es el mismo independientemente del gestor de paquetes que uses.

Mi postura

No voy a decirte que dejes de usar librerías externas. Sería una postura ridícula viniendo de alguien que labura con Next.js, Docker y media docena de paquetes en cada proyecto. Pero cada pnpm add merece la misma pregunta que le harías a una contratación: ¿quién está del otro lado, y qué pasa si desaparece?

La próxima vez que estés a punto de instalar algo para resolver un problema chico, probá primero si lo podés resolver en una función propia de diez líneas. Si no podés, corré pnpm why después de instalar y mirá qué trajiste puertas adentro sin haberlo decidido. Esa costumbre, más que cualquier checklist, es la que separa un proyecto que se puede mantener en tres años de uno que se convierte en arqueología.

Fuente original: npm package documentation

Este artículo fue publicado originalmente en juanchi.dev

Strict Null Checks in TypeScript: What the Compiler Won't Tell You and Where It Actually Hurts in Production

Juan Torchia — Thu, 23 Jul 2026 12:02:12 +0000

Strict Null Checks in TypeScript: What the Compiler Won't Tell You and Where It Actually Hurts in Production

I was reviewing a Server Action in Next.js — something that compiled without a single error, clean types, green lint — when a Cannot read properties of undefined (reading 'id') hit in runtime. Three minutes of retrospective later I understood the problem: the compiler had given me the green light and I believed it. That was a mistake.

My thesis, straight up: strict null checks is necessary but not sufficient. The TypeScript compiler is the first filter in the system, not the last. Real null safety comes from runtime validation at the edges of the system — and there are four concrete patterns where the compiler says OK and production says otherwise.

This isn't a "turn on strict: true and you're done" post. It's a map of where the compiler fails silently, using the Next.js 16 + Prisma ORM 5 + strict TypeScript stack as a concrete reference.

Strict Null Checks in TypeScript Production: What the Flag Actually Activates

When you enable strict: true in tsconfig.json, TypeScript turns on a more restrictive set of checks. According to the official docs, strict is a shorthand that includes, among others:

strictNullChecks — null and undefined are not assignable to other types without an explicit guard.
noImplicitAny — no variable can be left without an inferred type.
strictFunctionTypes — function types are checked contravariantly.

// tsconfig.json — recommended base configuration
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "lib": ["ES2022"],
    "moduleResolution": "bundler"
  }
}

What strict does not do is verify that data arriving from the outside — an API, a JSON.parse, a database response, an HTTP header — actually has the shape the type declares. The compiler works with static types; runtime works with real data. Two different worlds, and the gap between them is exactly where bugs live.

The 4 Patterns Where the Compiler Says OK and Runtime Blows Up Anyway

Pattern 1 — Badly Typed Assertion Functions

Assertion functions are functions the compiler treats as type guards. If you declare them wrong, TypeScript trusts them blindly.

// ⚠️ Assertion function that doesn't do what it promises
function assertDefined<T>(val: T | null | undefined): asserts val is T {
  // You forgot the throw — TypeScript won't catch this
  // The compiler still marks val as T after this call
  if (val === null || val === undefined) {
    console.warn("null value detected"); // log without throw
  }
}

const userId: string | null = getUserId();
assertDefined(userId);
// After this, TypeScript believes userId is string
// But if it was null, the console.warn didn't stop the flow
console.log(userId.toUpperCase()); // TypeError in runtime

The compiler accepts the asserts val is T contract without checking the function body. If the assertion doesn't throw, the type is lying. The fix is simple but not obvious:

// ✅ Correct assertion function — the throw is mandatory
function assertDefined<T>(val: T | null | undefined): asserts val is T {
  if (val === null || val === undefined) {
    throw new Error(`Required value was null or undefined`);
  }
}

Pattern 2 — Libraries with Imprecise Types or Implicit `any`

Plenty of ecosystem libraries publish types in @types/ that don't always reflect actual return values. The most common case: a function typed as string | undefined that returns null in certain codepaths, or the other way around.

// Example with a hypothetical cookie parsing library
import { parseCookie } from "some-cookie-lib";

const sessionId: string = parseCookie(req.headers.cookie, "session");
// The lib is typed as string — but it can return null at runtime
// TypeScript doesn't complain because it trusts the declared type

The warning sign is when you see as string scattered around, or when a library returns a broad type like any or Record<string, unknown>. At that point, the compiler delegates responsibility to whatever type you declare — and if that type is optimistic, you've already lost.

Checklist for external libraries:

Signal in the types	Risk	What to do
`any` return	High	Validate with Zod at point of use
Outdated `@types/` types	Medium	Check the lib's CHANGELOG
`string	undefined `when it could be` null`	Medium
Auto-generated types (OpenAPI, etc.)	Variable	Validate at the entry boundary

Pattern 3 — Optional Prisma ORM 5 Relations

This one has surprised me the most working with Prisma. When you have an optional relation in the schema — user User? — Prisma types it as User | null. So far so good. The problem shows up when you do an include and then try to access the relation without having selected that field.

// schema.prisma
// model Post {
//   id     Int   @id
//   author User?  @relation(fields: [authorId], references: [id])
//   authorId Int?
// }

// ❌ The compiler accepts this — runtime can blow up
const post = await prisma.post.findUnique({
  where: { id: 1 },
  // No include of author
});

// TypeScript infers post.author as User | null | undefined
// based on the generated type — but if you didn't include it,
// author simply doesn't exist on the returned object
if (post?.author?.name) {
  console.log(post.author.name); // undefined at runtime, not null
}

Prisma 5 generates types that reflect the schema, but not the exact shape of each query. If you don't include the relation in include, the field doesn't come back in the object — and the generated type doesn't express that with enough granularity. The fix:

// ✅ Explicit result typing with the include
const post = await prisma.post.findUnique({
  where: { id: 1 },
  include: { author: true }, // now the type correctly includes author
});

// TypeScript now knows post.author can be User | null (optional relation)
// and forces you to guard it before using it
if (post && post.author) {
  console.log(post.author.name);
}

The practical rule: in Prisma, the generated type reflects the schema, not the query. Always make your include/select match what the downstream code expects to consume.

Pattern 4 — JSON.parse Without Runtime Validation

This is the most classic one and the most underestimated. JSON.parse returns any in TypeScript — the compiler has no idea what shape that JSON has until runtime.

// ❌ The compiler accepts this completely
async function getConfiguration(): Promise<{ timeout: number; endpoint: string }> {
  const raw = await fs.readFile("config.json", "utf-8");
  return JSON.parse(raw); // returns any — TypeScript trusts the declared return type
}

const config = await getConfiguration();
// config.timeout could be undefined, string, null — the compiler doesn't know
const ms = config.timeout * 1000; // NaN or TypeError at runtime

The solution is to validate at the boundary. Zod is the tool that fits best in this stack:

// ✅ Validation with Zod at the external data entry point
import { z } from "zod";

const ConfigSchema = z.object({
  timeout: z.number().positive(),
  endpoint: z.string().url(),
});

async function getConfiguration() {
  const raw = await fs.readFile("config.json", "utf-8");
  const parsed = JSON.parse(raw);
  return ConfigSchema.parse(parsed); // throws ZodError if shape doesn't match
}

// Now the inferred type is exactly { timeout: number; endpoint: string }
// and runtime guarantees the shape before the data reaches the rest of the code
const config = await getConfiguration();
const ms = config.timeout * 1000; // safe

The same pattern applies to Server Actions in Next.js that receive form data, to external API responses, and to any data that crosses the system boundary.

Common Mistakes When Configuring Strict Null Checks

Three mistakes show up constantly when teams enable strict on an existing codebase:

1. Turning off individual checks to make it compile

// ❌ This defeats the entire purpose of strict
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": false
  }
}

If a check breaks too much existing code, the right path is to migrate progressively with annotated and dated // @ts-expect-error comments — not to disable the flag globally.

2. Using the non-null assertion operator (!) without a real guard

// ❌ The ! operator tells the compiler "trust me"
// but does zero verification at runtime
const name = user!.name; // TypeError if user is null

Every ! in the codebase is potential technical debt. If you see more than five ! in a single file, that's a signal that the types aren't accurately modeling the domain's reality.

3. Confusing strict in Next.js config with strict in tsconfig

next.config.js has a typescript.ignoreBuildErrors option that, when set to true, completely bypasses the compiler during the build. The strict in tsconfig.json means nothing if the build never fails on type errors.

Decision Checklist: Where to Validate and Where to Trust the Compiler

Before deciding whether to add runtime validation or trust the static type, run through this checklist:

Question	Yes	No
Does the data come from outside the process? (API, file, DB, form)	Validate with Zod	Compiler is enough
Does the library have `any` types or outdated `@types/`?	Add explicit guard	Compiler is enough
Are you using custom assertion functions?	Verify they throw	—
Is the Prisma relation in the `include`?	Type is precise	Add defensive guard
Does the type use `!` to suppress a null?	Revisit the domain model	—

Rule of thumb: if the data crossed a system boundary (network, disk, form, environment variable), validate at runtime. If the data is internal to the process and the type was inferred by TypeScript, the compiler is enough.

Limits of This Guide

What you can't conclude from this post without more evidence:

How many production bugs come from each pattern — that depends on the specific codebase, test coverage, and team maturity.
Whether Zod is always the best option over alternatives like Valibot or ArkType — there are bundle size and ergonomics trade-offs that deserve their own analysis.
Whether these patterns apply equally in a codebase using tRPC or GraphQL with codegen — those systems have their own validation layers that change the equation.

What you can conclude: the four patterns are reproducible, have concrete solutions, and apply directly to the Next.js 16 + Prisma 5 + strict TypeScript stack.

FAQ — Strict Null Checks TypeScript Production

With strict: true enabled, can I trust there are no nulls at runtime?
No. strict: true guarantees the compiler warns you when a type can be null or undefined — but it can't verify data coming in from outside the process. Data from APIs, forms, files, and databases needs additional runtime validation.

Does Prisma ORM generate types that exactly reflect what each query returns?
Partially. Prisma 5 infers the type from the schema and from the query's include/select. If you don't include a relation, the field won't be on the returned object — but the generated type may not express that with enough precision in all cases. The safe practice is to always make the include match what downstream code consumes.

When does it make sense to use // @ts-expect-error instead of properly fixing the type?
Only in two cases: when you're progressively migrating a legacy codebase to strict (annotated with a comment explaining why and an expected resolution date), or when you're deliberately testing an error. In stable production code, @ts-expect-error without justification is technical debt with an unknown expiry date.

Does JSON.parse always return any?
Yes, by design. TypeScript can't know the shape of the JSON until runtime. The only way to recover a concrete type is to validate the result with a library like Zod or write manual type guards. Manual guards don't scale well; Zod scales better.

Are assertion functions a bad practice?
Not necessarily. They're a legitimate tool in TypeScript's type system. The problem is using them without a real throw — in that case, the contract you declare isn't fulfilled at runtime and the compiler can't detect it. With a proper throw, they're a clean way to do imperative narrowing.

Does it make sense to migrate to strict null checks in a large codebase that doesn't have it?
Yes, but with a strategy. The practical approach is to enable strict: true and use annotated @ts-expect-error to silence existing errors, then resolve them module by module — prioritizing system boundaries first (APIs, parsers, DB adapters) — and never disable strictNullChecks individually just to make it compile faster.

The Compiler Is the First Filter, Not the Last

Working with strict TypeScript in Next.js 16 and Prisma 5 changed how I think about type safety. Not as a binary "it compiled = it's safe" but as a chain: the compiler filters static errors, runtime validation filters errors at the boundaries, and integration tests cover the rest.

The four patterns in this post — assertion functions without throw, libraries with imprecise types, optional Prisma relations without include, and JSON.parse without validation — have one thing in common: they all pass the compiler and they can all fail at runtime. The difference between teams that catch these before production and those that don't is systematic: the first group puts validation at the boundary and doesn't assume the compiler solves what it can't see.

My practical stance: every time data enters the system from outside, Zod or equivalent. Every assertion function with a real throw. Every Prisma include reflecting what the downstream code actually needs. And zero ! operators without a real guard behind them.

If you're working with a TypeScript codebase that mixes strict and legacy patterns, the concrete next step is to find every JSON.parse without validation and start there — it's the most common boundary and the easiest one to fix first.

If you want to go deeper on system boundaries with TypeScript, I have related posts that can add context: DeepSeek API in TypeScript, Node.js and the event loop as a stack component, and Docker healthchecks in production all touch on the difference between what the system promises and what it delivers.

Original sources:

TypeScript Handbook — Strict Mode: https://www.typescriptlang.org/tsconfig#strict
Zod Documentation: https://zod.dev/

This article was originally published on juanchi.dev

Strict null checks en TypeScript: lo que el compilador no te dice y dónde sí duele en producción

Juan Torchia — Thu, 23 Jul 2026 12:02:07 +0000

Strict null checks en TypeScript: lo que el compilador no te dice y dónde sí duele en producción

Estaba revisando un Server Action en Next.js — algo que compilaba sin un solo error, tipos limpios, lint verde — cuando llegó un Cannot read properties of undefined (reading 'id') en runtime. Tres minutos de retrospectiva después entendí el problema: el compilador me había dado luz verde y yo lo creí. Eso fue un error.

Mi tesis, sin rodeos: strict null checks es necesario pero insuficiente. El compilador de TypeScript es el primer filtro del sistema, no el último. La verdadera seguridad contra nulls viene de validación en runtime en los bordes del sistema — y hay cuatro patrones concretos donde el compilador dice OK y producción dice otra cosa.

No es un post de "activá strict: true y listo". Es un mapa de dónde el compilador falla en silencio, con el stack Next.js 16 + Prisma ORM 5 + TypeScript estricto como referencia concreta.

Strict null checks en TypeScript producción: qué activa la flag y qué no

Cuando habilitás strict: true en el tsconfig.json, TypeScript activa un conjunto de checks más restrictivos. Según la documentación oficial, strict es un shorthand que incluye, entre otros:

strictNullChecks — null y undefined no son asignables a otros tipos sin una guarda explícita.
noImplicitAny — ninguna variable puede quedarse sin tipo inferido.
strictFunctionTypes — los tipos de función se verifican contravariante.

// tsconfig.json — configuración base recomendada
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "lib": ["ES2022"],
    "moduleResolution": "bundler"
  }
}

Lo que strict no hace es verificar que los datos que llegan desde el exterior —una API, un JSON.parse, una respuesta de base de datos, un header HTTP— tengan la forma que el tipo declara. El compilador trabaja con tipos estáticos; runtime trabaja con datos reales. Son dos mundos distintos y la brecha entre ellos es donde aparecen los bugs.

Los 4 patrones donde el compilador dice OK y runtime te revienta igual

Patrón 1 — Assertion functions mal tipadas

Las assertion functions son funciones que el compilador trata como guardas de tipo. Si las declarás mal, TypeScript confía en ellas ciegamente.

// ⚠️ Assertion function que no hace lo que promete
function assertDefined<T>(val: T | null | undefined): asserts val is T {
  // Olvidaste el throw — TypeScript no lo detecta
  // El compilador igual marca val como T después de esta llamada
  if (val === null || val === undefined) {
    console.warn("valor null detectado"); // log sin throw
  }
}

const userId: string | null = obtenerUserId();
assertDefined(userId);
// Después de acá, TypeScript cree que userId es string
// Pero si era null, el console.warn no detuvo el flujo
console.log(userId.toUpperCase()); // TypeError en runtime

El compilador acepta el contrato de asserts val is T sin verificar el cuerpo de la función. Si la assertion no lanza un error, el tipo miente. La corrección es simple pero no obvia:

// ✅ Assertion function correcta — el throw es obligatorio
function assertDefined<T>(val: T | null | undefined): asserts val is T {
  if (val === null || val === undefined) {
    throw new Error(`Valor requerido era null o undefined`);
  }
}

Patrón 2 — Librerías sin tipos precisos o con `any` implícito

Muchas librerías del ecosistema publican tipos en @types/ que no siempre reflejan los retornos reales. El caso más común: una función tipada como string | undefined que en ciertos codepaths devuelve null, o viceversa.

// Ejemplo con una librería hipotética de parseo de cookies
import { parseCookie } from "alguna-lib-de-cookies";

const sessionId: string = parseCookie(req.headers.cookie, "session");
// La lib está tipada como string — pero puede devolver null en runtime
// TypeScript no protesta porque confía en el tipo declarado

La señal de alerta es cuando ves as string o cuando una librería retorna un tipo amplio como any o Record<string, unknown>. En ese punto, el compilador delega la responsabilidad al tipo que vos declarás — y si ese tipo es optimista, perdiste.

Checklist para librerías externas:

Señal en los tipos	Riesgo	Qué hacer
Retorno `any`	Alto	Validar con Zod en el punto de uso
Tipos en `@types/` desactualizados	Medio	Revisar el CHANGELOG de la lib
`string	undefined `cuando podría ser` null`	Medio
Tipos generados automáticamente (OpenAPI, etc.)	Variable	Validar en el borde de entrada

Patrón 3 — Relaciones opcionales de Prisma ORM 5

Este es el que más me ha sorprendido trabajando con Prisma. Cuando tenés una relación opcional en el schema — user User? — Prisma la tipea como User | null. Hasta acá bien. El problema aparece cuando hacés un include y después intentás acceder a la relación sin haber guardado ese campo en el select.

// schema.prisma
// model Post {
//   id     Int   @id
//   author User?  @relation(fields: [authorId], references: [id])
//   authorId Int?
// }

// ❌ El compilador acepta esto — runtime puede explotar
const post = await prisma.post.findUnique({
  where: { id: 1 },
  // Sin include de author
});

// TypeScript infiere post.author como User | null | undefined
// según el tipo generado — pero si no hiciste el include,
// author directamente no existe en el objeto retornado
if (post?.author?.name) {
  console.log(post.author.name); // undefined en runtime, no null
}

Prisma 5 genera tipos que reflejan el schema, pero no el shape exacto de cada query. Si no incluís la relación en el include, el campo no viene en el objeto — y el tipo generado no lo expresa con suficiente granularidad. La corrección:

// ✅ Tipado explícito del resultado con el include
const post = await prisma.post.findUnique({
  where: { id: 1 },
  include: { author: true }, // ahora el tipo incluye author correctamente
});

// TypeScript ahora sabe que post.author puede ser User | null (relación opcional)
// y lo fuerza a que lo guardes antes de usarlo
if (post && post.author) {
  console.log(post.author.name);
}

La regla práctica: en Prisma, el tipo generado refleja el schema, no la query. Siempre hacé coincidir el include/select con lo que el código downstream espera consumir.

Patrón 4 — JSON.parse sin validación de runtime

Este es el más clásico y el que más se subestima. JSON.parse retorna any en TypeScript — el compilador no puede saber qué forma tiene ese JSON hasta que llegue en runtime.

// ❌ El compilador acepta esto completamente
async function obtenerConfiguracion(): Promise<{ timeout: number; endpoint: string }> {
  const raw = await fs.readFile("config.json", "utf-8");
  return JSON.parse(raw); // retorna any — TypeScript confía en el tipo de retorno declarado
}

const config = await obtenerConfiguracion();
// config.timeout podría ser undefined, string, null — el compilador no sabe
const ms = config.timeout * 1000; // NaN o TypeError en runtime

La solución está en validar en el borde. Zod es la herramienta que mejor encaja en este stack:

// ✅ Validación con Zod en el punto de entrada del dato externo
import { z } from "zod";

const ConfigSchema = z.object({
  timeout: z.number().positive(),
  endpoint: z.string().url(),
});

async function obtenerConfiguracion() {
  const raw = await fs.readFile("config.json", "utf-8");
  const parsed = JSON.parse(raw);
  return ConfigSchema.parse(parsed); // lanza ZodError si el shape no coincide
}

// Ahora el tipo inferido es exactamente { timeout: number; endpoint: string }
// y el runtime garantiza la forma antes de que el dato llegue al resto del código
const config = await obtenerConfiguracion();
const ms = config.timeout * 1000; // seguro

El mismo patrón aplica a Server Actions en Next.js que reciben datos de formularios, a responses de APIs externas y a cualquier dato que cruce el borde del sistema.

Errores comunes al configurar strict null checks

Hay tres errores que aparecen seguido cuando equipos habilitan strict en un codebase existente:

1. Apagar checks individuales para que compile

// ❌ Esto anula el propósito de strict
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": false
  }
}

Si un check rompe demasiado código existente, el camino correcto es migrar progresivamente con // @ts-expect-error anotado y fechado — no desactivar la flag globalmente.

2. Usar non-null assertion operator (!) sin guarda real

// ❌ El operador ! le dice al compilador "confiá en mí"
// pero no hace ninguna verificación en runtime
const nombre = usuario!.nombre; // TypeError si usuario es null

Cada ! en el codebase es una deuda técnica potencial. Si ves más de cinco ! en un archivo, es una señal de que los tipos no están modelando bien la realidad del dominio.

3. Confundir que strict en Next.js config y en tsconfig son cosas distintas

next.config.js tiene una opción typescript.ignoreBuildErrors que, si está en true, bypassea completamente el compilador en el build. El strict del tsconfig.json no sirve de nada si el build nunca falla por errores de tipos.

Checklist de decisión: dónde validar y dónde confiar en el compilador

Antes de decidir si agregar validación de runtime o confiar en el tipo estático, pasá por esta checklist:

Pregunta	Sí	No
¿El dato viene de fuera del proceso? (API, archivo, DB, formulario)	Validar con Zod	El compilador alcanza
¿La librería tiene tipos `any` o tipos de `@types/` desactualizados?	Agregar guarda explícita	El compilador alcanza
¿Usás assertion functions propias?	Verificar que lancen `throw`	—
¿La relación de Prisma está en el `include`?	El tipo es preciso	Agregar guarda defensiva
¿El tipo usa `!` para suprimir un null?	Revisitar el modelo de dominio	—

Regla de dedo: si el dato cruzó un borde del sistema (red, disco, formulario, variable de entorno), validá en runtime. Si el dato es interno al proceso y el tipo fue inferido por TypeScript, el compilador alcanza.

Límites de esta guía

Lo que no podés concluir de este post sin más evidencia:

Cuántos bugs en producción vienen de cada patrón — eso depende del codebase específico, la cobertura de tests y la madurez del equipo.
Si Zod es siempre la mejor opción frente a alternativas como Valibot o ArkType — hay trade-offs de bundle size y ergonomía que merecen análisis propio.
Si estos patrones aplican igual en un codebase que usa tRPC o GraphQL con codegen — esos sistemas tienen sus propias capas de validación que cambian la ecuación.

Lo que sí podés concluir: los cuatro patrones son reproducibles, tienen solución concreta y aplican directamente al stack Next.js 16 + Prisma 5 + TypeScript estricto.

FAQ — strict null checks TypeScript producción

¿Con strict: true activado puedo confiar en que no hay nulls en runtime?
No. strict: true garantiza que el compilador te avisa cuando un tipo puede ser null o undefined — pero no puede verificar los datos que entran desde afuera del proceso. Los datos de APIs, formularios, archivos y bases de datos necesitan validación en runtime adicional.

¿Prisma ORM genera tipos que reflejan exactamente lo que retorna cada query?
Parcialmente. Prisma 5 infiere el tipo a partir del schema y del include/select de la query. Si no hacés include de una relación, el campo no va a estar en el objeto retornado — pero el tipo generado puede no expresar eso con suficiente precisión en todos los casos. La práctica segura es hacer coincidir siempre el include con lo que el código downstream consume.

¿Cuándo tiene sentido usar // @ts-expect-error en lugar de resolver el tipo correctamente?
Solo en dos casos: cuando estás migrando un codebase legacy a strict de forma progresiva (anotado con un comentario que explique el motivo y una fecha de resolución esperada), o cuando estás testeando un error deliberado. En código de producción estable, @ts-expect-error sin justificación es una deuda técnica con fecha de vencimiento desconocida.

¿JSON.parse siempre retorna any?
Sí, por diseño. TypeScript no puede saber la forma del JSON hasta runtime. La única forma de recuperar un tipo concreto es validar el resultado con una librería como Zod o escribir guardas de tipo manuales. Las guardas manuales escalan mal; Zod escala mejor.

¿Las assertion functions son una mala práctica?
No necesariamente. Son una herramienta legítima del sistema de tipos de TypeScript. El problema es usarlas sin un throw real — en ese caso, el contrato que declarás no se cumple en runtime y el compilador no puede detectarlo. Con un throw correcto, son una forma limpia de narrowing imperativo.

¿Tiene sentido migrar a strict null checks en un codebase grande que no lo tiene?
Sí, pero con estrategia. La forma práctica es habilitar strict: true y usar @ts-expect-error anotado para silenciar los errores existentes, resolverlos de a módulos priorizando los bordes del sistema primero (APIs, parsers, adapters de DB), y nunca desactivar strictNullChecks individualmente para que compile más rápido.

El compilador es el primer filtro, no el último

Trabajar con TypeScript estricto en Next.js 16 y Prisma 5 cambió cómo pienso la seguridad de tipos. No como un binario "compiló = seguro" sino como una cadena: el compilador filtra los errores estáticos, la validación de runtime filtra los errores en los bordes, y los tests de integración cubren el resto.

Los cuatro patrones de este post — assertion functions sin throw, librerías con tipos imprecisos, relaciones opcionales de Prisma sin include, y JSON.parse sin validación — tienen algo en común: todos pasan el compilador y todos pueden fallar en runtime. La diferencia entre los equipos que los atrapa antes de producción y los que no es sistemática: los primeros ponen validación en el borde y no asumen que el compilador resuelve lo que no puede ver.

Mi postura práctica: cada vez que un dato entra al sistema desde afuera, Zod o equivalente. Cada assertion function con un throw real. Cada include de Prisma reflejando lo que el código downstream necesita. Y cero operadores ! sin guarda real detrás.

Si trabajás con una codebase TypeScript que mezcla strict y patrones legacy, el siguiente paso concreto es buscar todos los JSON.parse sin validación y empezar ahí — es el borde más común y el más fácil de resolver primero.

Si te interesa profundizar en los bordes del sistema con TypeScript, tengo posts relacionados que pueden sumar contexto: DeepSeek API en TypeScript, Node.js y el event loop como pieza del stack y Docker healthchecks en producción también tocan la diferencia entre lo que el sistema promete y lo que entrega.

Fuentes originales:

TypeScript Handbook — Strict Mode: https://www.typescriptlang.org/tsconfig#strict
Zod Documentation: https://zod.dev/

Este artículo fue publicado originalmente en juanchi.dev

DeepSeek API in TypeScript: secure integration and honest model evaluation for code

Juan Torchia — Wed, 22 Jul 2026 12:00:15 +0000

DeepSeek API in TypeScript: secure integration and honest model evaluation for code

For months I was convinced that integrating a new model into a TypeScript pipeline was the hard part. Then I realized it never was. The hard part is deciding whether that model is actually worth it for what you need — without buying the hype or trashing it because Twitter moved on. I learned that lesson again with DeepSeek.

My thesis before starting: DeepSeek's API is compatible with the OpenAI SDK, which makes integration almost trivial in any existing TypeScript pipeline. The real differentiator isn't the plumbing — it's the model. DeepSeek-Coder is competitive for code tasks, but the decision criterion depends on your specific use case, not on Twitter enthusiasm.

What the official docs say — and what they don't

The official DeepSeek documentation has two facts that completely change the integration conversation:

OpenAI SDK compatibility: DeepSeek exposes its API under the same message format as OpenAI. That means if you're already using the openai npm package in a TypeScript pipeline, you can point it at DeepSeek's base URL with minimal changes.

Available models: As of this post, the main models are deepseek-chat (general purpose) and deepseek-coder (code-focused). The docs list the base endpoint as https://api.deepseek.com.

What the documentation doesn't say: independent benchmarks, real production latency comparisons, or SLA guarantees. That's your own work — or someone willing to run the experiment under real load. I'm not going to make up those numbers here.

How to integrate in TypeScript without exposing the API key

Core decision: the DeepSeek API key, like any LLM provider credential, cannot live on the client. Ever. In Next.js App Router that has a concrete answer: the logic that calls the API lives in a Route Handler (server-side), and the key travels exclusively via server environment variable.

Step 1: environment variable in `.env.local`

# .env.local — NEVER commit this file
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Add it to .gitignore if it isn't already. On Railway, Vercel, or any deploy platform, you configure the variable from the dashboard — never from the repository.

Step 2: TypeScript client with OpenAI SDK compatibility

// lib/deepseek-client.ts
import OpenAI from "openai";

// Instance pointing to DeepSeek's endpoint
// Compatible with openai@^4 — same type contract
const deepseek = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY, // only available server-side
  baseURL: "https://api.deepseek.com",
});

export default deepseek;

The key is in baseURL: the OpenAI SDK accepts endpoint override, and DeepSeek respects the same message contract. You don't need a proprietary SDK.

Step 3: Route Handler in Next.js App Router

// app/api/code-review/route.ts
import { NextRequest, NextResponse } from "next/server";
import deepseek from "@/lib/deepseek-client";

export async function POST(req: NextRequest) {
  const { code } = await req.json();

  // Minimal validation before calling the model
  if (!code || typeof code !== "string" || code.length > 8000) {
    return NextResponse.json({ error: "Invalid payload" }, { status: 400 });
  }

  const completion = await deepseek.chat.completions.create({
    model: "deepseek-coder", // code-focused model
    messages: [
      {
        role: "system",
        content: "Review the code and flag concrete issues with justification.",
      },
      { role: "user", content: code },
    ],
    max_tokens: 1024,
  });

  return NextResponse.json({
    review: completion.choices[0]?.message?.content ?? "",
  });
}

The client never sees the key. The browser calls /api/code-review; the Route Handler calls DeepSeek. That's the pattern.

Where people get it wrong — and what it costs

There are three common mistakes that show up in quick LLM API integrations. I'm listing them as practical criteria, because the patterns are reproducible even if the specific experience is generic:

Mistake 1: exposing the key on the client
The typical case is a dev who copies the documentation snippet directly into a React component. process.env.DEEPSEEK_API_KEY on the client is undefined in Next.js by default — but if someone prefixes the variable with NEXT_PUBLIC_, it gets exposed in the browser bundle. Cost: the key is accessible in DevTools and in any scraper that inspects the public JS.

Mistake 2: treating deepseek-chat and deepseek-coder as synonyms
They're different models with different biases. deepseek-coder was trained specifically for code generation and review tasks; deepseek-chat is more general. Using the wrong model doesn't break the API — it breaks the quality of the response. The documentation distinguishes them explicitly.

Mistake 3: assuming OpenAI SDK compatibility is total
The compatibility is at the message format and response structure level. It doesn't mean DeepSeek supports every OpenAI API feature: function calling, embeddings, fine-tuning, and advanced tooling may have differences or limitations. Before assuming full parity, check the DeepSeek documentation for the specific feature you need.

Decision matrix: DeepSeek-Coder vs Claude for code tasks

This is the part where most posts hand you a winner and call it done. I'm not going to do that — because the honest answer depends on variables I can't measure for you.

What I can give you is the decision framework:

Criterion	DeepSeek-Coder	Claude (Sonnet/Opus)
API cost	Lower as of publication date	Higher on powerful models
Long context	Check official documentation	Claude has 200k tokens on Opus/Sonnet
OpenAI SDK integration	Native, same contract	Requires Anthropic SDK or wrapper
Multi-step reasoning	Competitive on code	Stronger on general reasoning
Availability / uptime	Newer provider, shorter track record	Anthropic has a longer track record
Content restrictions	Less detailed documentation	Better documented and more predictable

When it's worth trying DeepSeek-Coder first:

The pipeline is exclusively code generation or review
API cost is a relevant variable in the design
You're already on the OpenAI SDK and want minimal friction to evaluate

When to stick with Claude:

You need multi-step reasoning or very long context
Model behavior predictability matters more than cost
The pipeline mixes code tasks with general reasoning or analysis

What you can't decide without your own experiment: perceived response speed in production, quality on your specific code domain, and behavior under load. That data doesn't exist in any post — it exists in your own logs.

What this guide can't conclude

Being honest here is part of the job:

No first-party benchmarks: I didn't run systematic comparisons between DeepSeek-Coder and Claude against real use cases. The public benchmarks circulating out there have different methodologies and aren't always reproducible.
DeepSeek's documentation can change: it's an actively growing platform. What's available today may change. Always check https://platform.deepseek.com/api-docs/ before making architecture decisions.
OpenAI SDK compatibility is not a parity guarantee: it's an entry point, not a complete contract. Test the specific feature you need.
Relative API costs fluctuate: don't anchor architecture decisions to pricing numbers that change every quarter.

FAQ — Common questions about DeepSeek API in TypeScript

Do I need a special SDK to use DeepSeek in TypeScript?
No. You can use the official openai npm package pointing baseURL at https://api.deepseek.com. DeepSeek respects the same message format, so the OpenAI SDK's TypeScript types work without modifications.

What's the real difference between deepseek-chat and deepseek-coder?
According to the official documentation, deepseek-coder was trained specifically for code tasks: generation, explanation, debugging, and review. deepseek-chat is the general-purpose model. For a code-focused pipeline, deepseek-coder is the logical starting point.

How do I protect the API key in a Next.js project?
The key lives in .env.local (never in the repository) and is used exclusively in server-side code: Route Handlers or Server Actions. Never prefix the variable with NEXT_PUBLIC_ — that exposes it in the browser bundle. In production, configure it from your deploy platform's dashboard.

Can I use DeepSeek and Claude in the same pipeline?
Yes, and it's a reasonable pattern: use DeepSeek-Coder for mechanical code tasks (boilerplate generation, conversions, snippets) and Claude for more complex reasoning or long context. The router between models is logic you write yourself. This connects to the same design decision that comes up in rate limiting in web applications: deciding which layer you protect and with what tool.

Does OpenAI SDK compatibility guarantee all features will work the same?
No. Compatibility is at the basic chat completions level. Features like function calling, embeddings, batch API, or fine-tuning may have differences or simply not be available in DeepSeek. Before assuming parity, verify the specific feature you need in the official documentation.

Does it make sense to use DeepSeek in a pipeline that already uses Claude or GPT-4?
Depends on the case. If API cost is relevant and the tasks are mechanical (repetitive code generation, formatting, short snippets), it's worth evaluating. If the pipeline depends on multi-step reasoning or very long context, the switch may degrade response quality. The honest decision comes from running the experiment in your own domain, not from general benchmarks.

The real decision, no decoration

Integrating DeepSeek in TypeScript is easy — intentionally easy. The OpenAI SDK compatibility is a product decision that brings adoption friction down to nearly zero. That's a real advantage and it deserves acknowledgment.

What isn't easy is the model decision. And here my position is clear: I'm not buying anyone's claim that DeepSeek-Coder is better than Claude for code "in general" — because "in general" doesn't exist in production. What exists is the specific domain, the type of task, the token volume, and the project budget.

What I do accept as a starting point: if you already have a pipeline on the OpenAI SDK and want to evaluate DeepSeek-Coder, the cost of the test is minimal. Change the baseURL, change the model, run the same set of prompts you already have, and look at the results. That's the only honest way to compare.

Twitter hype doesn't replace that experiment. Neither do I.

If pipeline architecture interests you, the post on Node.js and the event loop has useful context on how to think about the runtime behind these integrations. And if you're thinking about how to protect these endpoints before exposing them, the rate limiting post is the next step.

Original source:

DeepSeek API Documentation: https://platform.deepseek.com/api-docs/

This article was originally published on juanchi.dev

DeepSeek API en TypeScript: integración segura y evaluación honesta del modelo para código

Juan Torchia — Wed, 22 Jul 2026 12:00:10 +0000

DeepSeek API en TypeScript: integración segura y evaluación honesta del modelo para código

Estuve meses convencido de que integrar un modelo nuevo al pipeline de TypeScript era la parte difícil. Después me di cuenta de que nunca lo fue. La parte difícil es decidir si ese modelo vale para lo que necesitás — sin comprar el hype ni descartarlo por moda. Con DeepSeek lo aprendí de nuevo.

Mi tesis antes de arrancar: la API de DeepSeek es compatible con el SDK de OpenAI, lo que hace la integración casi trivial en cualquier pipeline TypeScript existente. El diferenciador real no está en la plomería — está en el modelo. DeepSeek-Coder es competitivo en tareas de código, pero el criterio de elección depende del caso de uso específico, no del entusiasmo de Twitter.

Qué dice la documentación oficial — y qué no dice

La documentación oficial de DeepSeek tiene dos datos que cambian completamente la conversación sobre integración:

Compatibilidad con el SDK de OpenAI: DeepSeek expone su API bajo el mismo formato de mensajes que OpenAI. Eso significa que si ya usás openai npm package en un pipeline TypeScript, podés apuntar a la base URL de DeepSeek con mínimos cambios.

Modelos disponibles: A la fecha de este post, los modelos principales son deepseek-chat (propósito general) y deepseek-coder (orientado a código). La documentación lista el endpoint base como https://api.deepseek.com.

Lo que la documentación no dice: benchmarks independientes, comparaciones de latencia en producción real, ni garantías de SLA. Eso es trabajo propio — o de alguien que quiera correr el experimento con carga real. Yo no voy a inventar esos números acá.

Cómo se integra en TypeScript sin exponer la API key

Spine de la decisión: la API key de DeepSeek, como cualquier credential de un proveedor LLM, no puede vivir en el cliente. Nunca. En Next.js App Router eso tiene una respuesta concreta: la lógica que llama a la API vive en un Route Handler (server-side), y la key viaja exclusivamente via variable de entorno del servidor.

Paso 1: variable de entorno en `.env.local`

# .env.local — NUNCA commitear este archivo
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Agregalo a .gitignore si no está. En Railway, Vercel o cualquier plataforma de deploy, configurás la variable desde el panel — nunca desde el repositorio.

Paso 2: cliente TypeScript con compatibilidad OpenAI SDK

// lib/deepseek-client.ts
import OpenAI from "openai";

// Instancia apuntando al endpoint de DeepSeek
// Compatible con openai@^4 — mismo contrato de tipos
const deepseek = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY, // solo disponible server-side
  baseURL: "https://api.deepseek.com",
});

export default deepseek;

La clave está en baseURL: el SDK de OpenAI acepta override del endpoint, y DeepSeek respeta el mismo contrato de mensajes. No necesitás un SDK propietario.

Paso 3: Route Handler en Next.js App Router

// app/api/code-review/route.ts
import { NextRequest, NextResponse } from "next/server";
import deepseek from "@/lib/deepseek-client";

export async function POST(req: NextRequest) {
  const { code } = await req.json();

  // Validación mínima antes de llamar al modelo
  if (!code || typeof code !== "string" || code.length > 8000) {
    return NextResponse.json({ error: "Payload inválido" }, { status: 400 });
  }

  const completion = await deepseek.chat.completions.create({
    model: "deepseek-coder", // modelo orientado a código
    messages: [
      {
        role: "system",
        content: "Revisá el código y señalá problemas concretos con justificación.",
      },
      { role: "user", content: code },
    ],
    max_tokens: 1024,
  });

  return NextResponse.json({
    review: completion.choices[0]?.message?.content ?? "",
  });
}

El cliente nunca ve la key. El browser llama a /api/code-review; el Route Handler llama a DeepSeek. Ese es el patrón.

Dónde se equivoca la gente — y cuánto cuesta

Hay tres errores comunes que aparecen en integraciones rápidas de APIs LLM. Los listo como criterio prudente, porque los patrones son reproducibles aunque la experiencia sea genérica:

Error 1: exponer la key en el cliente
El caso típico es un dev que copia el snippet de la documentación directamente en un componente React. process.env.DEEPSEEK_API_KEY en el cliente es undefined en Next.js por defecto — pero si alguien prefija la variable con NEXT_PUBLIC_, la expone en el bundle del browser. Costo: la key queda accesible en DevTools y en cualquier scraper que revise el JS público.

Error 2: tratar deepseek-chat y deepseek-coder como sinónimos
Son modelos distintos con sesgos distintos. deepseek-coder fue entrenado específicamente para tareas de generación y revisión de código; deepseek-chat es más general. Usar el modelo equivocado no rompe la API — rompe la calidad de la respuesta. La documentación los distingue explícitamente.

Error 3: asumir que la compatibilidad con OpenAI SDK es total
La compatibilidad es a nivel de formato de mensajes y estructura de respuesta. No significa que DeepSeek soporte todas las features del API de OpenAI: function calling, embeddings, fine-tuning y herramientas avanzadas pueden tener diferencias o limitaciones. Antes de asumir paridad completa, revisá la documentación de DeepSeek para el feature específico que necesitás.

Matriz de decisión: DeepSeek-Coder vs Claude para tareas de código

Esta es la parte donde la mayoría de posts te da un winner y cierra el tema. Yo no voy a hacer eso — porque la respuesta honesta depende de variables que no puedo medir por vos.

Lo que sí puedo darte es el criterio de decisión:

Criterio	DeepSeek-Coder	Claude (Sonnet/Opus)
Costo de API	Más bajo a fecha de publicación	Más alto en modelos potentes
Contexto largo	Revisar documentación oficial	Claude tiene 200k tokens en Opus/Sonnet
Integración con SDK OpenAI	Nativa, mismo contrato	Requiere SDK de Anthropic o wrapper
Razonamiento multi-paso	Competitivo en código	Más fuerte en razonamiento general
Disponibilidad / uptime	Proveedor más nuevo, historial más corto	Anthropic tiene historial más largo
Restricciones de contenido	Documentación menos detallada	Más documentada y predecible

Cuándo vale probar DeepSeek-Coder primero:

El pipeline es exclusivamente de generación o revisión de código
El costo de API es una variable relevante en el diseño
Ya usás el SDK de OpenAI y querés mínima fricción para probar

Cuándo quedarse con Claude:

Necesitás razonamiento multi-paso o contexto muy largo
La predictibilidad del comportamiento del modelo importa más que el costo
El pipeline mezcla tareas de código con razonamiento general o análisis

Lo que no podés decidir sin vos propio experimento: velocidad de respuesta percibida en producción, calidad en el dominio específico del código que generás, y comportamiento bajo carga. Esos datos no existen en ningún post — existen en logs propios.

Lo que esta guía no puede concluir

Ser honesto acá es parte del trabajo:

No hay benchmarks propios: no corrí comparaciones sistemáticas entre DeepSeek-Coder y Claude con casos de uso reales. Los benchmarks públicos que circulan tienen metodologías distintas y no siempre son reproducibles.
La documentación de DeepSeek puede cambiar: es una plataforma en crecimiento activo. Lo que está disponible hoy puede cambiar. Revisá siempre https://platform.deepseek.com/api-docs/ antes de tomar decisiones de arquitectura.
La compatibilidad con OpenAI SDK no es garantía de paridad: es un punto de entrada, no un contrato completo. Testeá el feature específico que necesitás.
El costo relativo de las APIs fluctúa: no pongas decisiones de arquitectura en números de pricing que cambian cada trimestre.

FAQ — Preguntas frecuentes sobre DeepSeek API en TypeScript

¿Necesito un SDK especial para usar DeepSeek en TypeScript?
No. Podés usar el paquete oficial openai de npm apuntando el baseURL a https://api.deepseek.com. DeepSeek respeta el mismo formato de mensajes, así que el tipado TypeScript del SDK de OpenAI funciona sin modificaciones.

¿Cuál es la diferencia real entre deepseek-chat y deepseek-coder?
Según la documentación oficial, deepseek-coder fue entrenado específicamente para tareas de código: generación, explicación, debugging y revisión. deepseek-chat es el modelo de propósito general. Para un pipeline enfocado en código, deepseek-coder es el punto de partida lógico.

¿Cómo protejo la API key en un proyecto Next.js?
La key vive en .env.local (nunca en el repositorio) y se usa exclusivamente en código server-side: Route Handlers o Server Actions. Nunca prefijés la variable con NEXT_PUBLIC_ porque eso la expone en el bundle del browser. En producción, configurala desde el panel de la plataforma de deploy.

¿Puedo usar DeepSeek y Claude en el mismo pipeline?
Sí, y es un patrón razonable: usar DeepSeek-Coder para tareas mecánicas de código (generación de boilerplate, conversiones, snippets) y Claude para razonamiento más complejo o contexto largo. El router entre modelos es lógica que escribís vos. Esto conecta con la misma decisión de diseño que aparece en rate limiting en aplicaciones web: decidir qué capa protegés y con qué herramienta.

¿La compatibilidad con OpenAI SDK garantiza que todas las features van a funcionar igual?
No. La compatibilidad es a nivel de chat completions básico. Features como function calling, embeddings, batch API o fine-tuning pueden tener diferencias o directamente no estar disponibles en DeepSeek. Antes de asumir paridad, verificá en la documentación oficial el feature específico que necesitás.

¿Tiene sentido usar DeepSeek en un pipeline que ya usa Claude o GPT-4?
Depende del caso. Si el costo de API es relevante y las tareas son mecánicas (generación de código repetitivo, formateo, snippets cortos), vale evaluarlo. Si el pipeline depende de razonamiento multi-paso o contexto muy largo, el cambio puede deteriorar la calidad de las respuestas. La decisión honesta viene de correr el experimento en el propio dominio, no de benchmarks generales.

La decisión real, sin adornos

La integración de DeepSeek en TypeScript es fácil — intencionalmente fácil. La compatibilidad con el SDK de OpenAI es una decisión de producto que baja la fricción de adopción a casi cero. Eso es una ventaja real y vale reconocerla.

Lo que no es fácil es la decisión de modelo. Y acá mi postura es clara: no le compro a nadie la idea de que DeepSeek-Coder es mejor que Claude para código "en general" — porque "en general" no existe en producción. Existe el dominio específico, el tipo de tarea, el volumen de tokens y el presupuesto del proyecto.

Lo que sí acepto como punto de partida: si ya tenés un pipeline con el SDK de OpenAI y querés evaluar DeepSeek-Coder, el costo de la prueba es mínimo. Cambiás el baseURL, cambiás el modelo, corrés el mismo conjunto de prompts que ya tenés y mirás los resultados. Esa es la única forma honesta de comparar.

El hype de Twitter no reemplaza ese experimento. Yo tampoco.

Si el tema de arquitectura de pipelines te interesa, el post sobre Node.js y el event loop tiene contexto útil sobre cómo pensar el runtime detrás de estas integraciones. Y si estás pensando en cómo proteger estos endpoints antes de exponerlos, el post de rate limiting es el paso siguiente.

Fuente original:

DeepSeek API Documentation: https://platform.deepseek.com/api-docs/

Este artículo fue publicado originalmente en juanchi.dev

DEV Community: Juan Torchia

The Complete Guide to Docker HEALTHCHECK: Dockerfile vs Compose vs Orchestrator

The real pain before you write a single line of HEALTHCHECK

What the official source says (and what it doesn't)

Dockerfile vs Compose vs orchestrator: not the same question

Where people get it wrong: the common recipe and its hidden cost

Decision matrix: what to look at before writing the CMD

Common mistakes / gotchas

Limits of this guide

FAQ

Closing: the position

Guía completa de HEALTHCHECK en Docker: Dockerfile vs Compose vs orquestador

El dolor real antes de escribir una línea de HEALTHCHECK

Qué dice la fuente oficial (y qué no dice)

Dockerfile vs Compose vs orquestador: no es la misma pregunta

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

Matriz de decisión: qué mirar antes de escribir el CMD

Errores comunes / gotchas

Límites de esta guía

FAQ

Cierre: la postura

Qwen3 locally with Ollama: what changed in the architecture and whether it's worth switching

Qwen3 locally with Ollama: what changed in the architecture and whether it's worth switching

Qwen3 in Ollama: what the architecture actually says (and what it doesn't)

Where people go wrong when adopting a new model

Decision matrix: when does switching to Qwen3 actually make sense

Honest limits: what you can't conclude from this evidence

FAQ: Qwen3, Ollama, and local inference

The decision that actually matters

Qwen3 en local con Ollama: qué cambió en la arquitectura y si vale el cambio

Qwen3 en local con Ollama: qué cambió en la arquitectura y si vale el cambio

Qwen3 en Ollama: qué dice la arquitectura (y qué no dice)

Dónde se equivoca la gente al adoptar un modelo nuevo

Matriz de decisión: cuándo tiene sentido cambiar a Qwen3

Límites honestos: qué no podés concluir con esta evidencia

FAQ: Qwen3, Ollama e inferencia local

Cierre: la decisión que importa

Prisma Query Logging and PostgreSQL: Where the ORM Ends and the Database Begins

Prisma query logging PostgreSQL: what the ORM's log actually solves

Where people get it wrong: using the log as if it were a database profiler

Decision checklist: when the log is enough and when to look at PostgreSQL

Limits: what this evidence doesn't let you conclude

My take and the next step

FAQ

Prisma Query Logging y PostgreSQL: dónde termina el ORM y empieza la base

Prisma query logging PostgreSQL: qué resuelve el log del ORM

Dónde se equivoca la gente: usar el log como si fuera un profiler de base

Checklist de decisión: cuándo alcanza el log y cuándo mirar PostgreSQL

Límites: lo que esta evidencia no permite concluir

Mi postura y el próximo paso

FAQ

npm Dependencies: How to Evaluate a Library Before It Hits Production

Evaluating npm Dependencies: Security and Maintenance Are Not the Same Thing

Where People Get It Wrong: The Common Recipe and Its Hidden Cost

Decision Matrix: What to Check Before Installing

The Limits of This Evaluation

FAQ

Where I Stand

Dependencias npm: cómo evaluar una librería antes de meterla en producción

Evaluar dependencias npm: seguridad y mantenimiento no son lo mismo

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

Matriz de decisión: qué mirar antes de instalar

Los límites de esta evaluación

FAQ

Mi postura

Strict Null Checks in TypeScript: What the Compiler Won't Tell You and Where It Actually Hurts in Production

Strict Null Checks in TypeScript: What the Compiler Won't Tell You and Where It Actually Hurts in Production

Strict Null Checks in TypeScript Production: What the Flag Actually Activates

The 4 Patterns Where the Compiler Says OK and Runtime Blows Up Anyway

Pattern 1 — Badly Typed Assertion Functions

Pattern 2 — Libraries with Imprecise Types or Implicit any

Pattern 3 — Optional Prisma ORM 5 Relations

Pattern 4 — JSON.parse Without Runtime Validation

Common Mistakes When Configuring Strict Null Checks

Decision Checklist: Where to Validate and Where to Trust the Compiler

Limits of This Guide

FAQ — Strict Null Checks TypeScript Production

The Compiler Is the First Filter, Not the Last

Strict null checks en TypeScript: lo que el compilador no te dice y dónde sí duele en producción

Strict null checks en TypeScript: lo que el compilador no te dice y dónde sí duele en producción

Pattern 2 — Libraries with Imprecise Types or Implicit `any`

Patrón 2 — Librerías sin tipos precisos o con `any` implícito

Step 1: environment variable in `.env.local`

Paso 1: variable de entorno en `.env.local`