Better Auth Usage Plugin: La Revolución en Autenticación

Better Auth Usage plugin es un plugin oficial del ecosistema Better Auth que agrega control granular de consumo de features por usuario o plan, con soporte para límites máximos, estrategias de reset y hooks de lógica personalizada. Está disponible como paquete npm (@eggermarc/better-auth-usage) desde la versión 0.1.17, actualmente en desarrollo activo con breaking changes posibles.

¿Qué es Better Auth y por qué su plugin Usage es relevante?

Better Auth es la librería de autenticación para Node.js que en 2026 se consolidó como el nuevo estándar en proyectos Next.js modernos, desplazando a Auth.js y next-auth en muchos stacks. Si alguna vez intentaste implementar auth con next-auth en un proyecto con planes de suscripción, sabés el dolor de cabeza que es cuando empezás a necesitar controlar qué puede hacer cada usuario según su plan. Better Auth resuelve la autenticación base, pero el control granular de uso quedaba como tarea del desarrollador.

Acá entra el plugin Better Auth Usage. No es un plugin de seguridad en el sentido tradicional, sino una capa de control de negocio que se integra directo en la configuración del servidor de Better Auth. Definís features, les asignás límites, configurás cómo se resetean, y el plugin se encarga del tracking por vos.

Lo interesante es que este tipo de solución antes implicaba armar tablas custom, lógica propia de conteo y algún middleware artesanal que terminaba siendo un desastre de mantener.

Características principales del plugin Better Auth Usage

Según la documentación en el repositorio oficial de EggerMarc en GitHub, el plugin tiene un modelo bastante claro:

• Definición de features: cada feature tiene un nombre, un maxLimit global y una estrategia de reset (por ejemplo, mensual).
• Overrides por cliente o plan: podés sobreescribir el límite global para un cliente específico, asignándole un maxLimit distinto, un stripeId para vincular con Stripe, o campos custom.
• Hooks before/after: lógica que corre antes o después de registrar uso, ideal para validaciones o logging.
• authorizeReference: control de qué referencias puede usar un cliente determinado para registrar consumo.
• Tracking de consumo: el plugin mantiene el conteo por usuario/cliente y feature, con comparación contra el límite configurado.

El diseño es razonablemente limpio. No es un golazo de arquitectura, pero zafa bien para la mayoría de los casos de uso de SaaS con planes tiered. Esto se conecta con lo que analizamos en nuestra guía sobre firewalls y microsegmentación.

Instalación y configuración inicial paso a paso

La instalación es directa. Desde npm:

npm add @eggermarc/better-auth-usage

El paquete está publicado en el registro oficial de npm bajo el scope @eggermarc. Una vez instalado, se agrega como plugin en la configuración del servidor de Better Auth, dentro del array de plugins:

La estructura básica requiere definir el objeto usage con al menos una feature. La configuración va en el lado del servidor, no en el cliente. Eso es importante: todo el control de límites y overrides se define server-side, lo que tiene sentido porque no querés que el cliente pueda manipular sus propios límites (sería trivial hacerlo si estuviera expuesto al frontend).

Dicho esto, la documentación actual es escueta. Si estás arrancando desde cero con Better Auth, el blog de referencia en web-developer-blog.vercel.app da un contexto útil sobre el ecosistema general antes de meterte con los plugins.

Cómo definir features y límites por plan (ejemplo práctico)

El ejemplo más ilustrativo del README trabaja con una feature llamada token-feature. El límite global se configura en 1,000 tokens por mes. Luego, mediante overrides:

• Plan starter: 10,000 tokens por mes.
• Plan pro: 1,000,000 tokens por mes.

Cada override tiene un identificador de cliente, el maxLimit correspondiente y opcionalmente el stripeId. La estrategia de reset se define a nivel de feature, no por cliente (al menos en la versión actual), lo que es una limitación a tener en cuenta si necesitás reset diferenciado por plan.

Ponele que tenés un cliente en plan pro que consume 800,000 tokens en una semana. El plugin trackea ese consumo contra el límite de 1,000,000 definido en su override. Cuando llega al límite, la autorización falla y el hook before puede usarlo para retornar un error descriptivo antes de que llegue a tu lógica de negocio.

Uso de hooks y eventos para lógica personalizada

Los hooks before y after son donde el plugin gana flexibilidad real. Lo explicamos a fondo en los plugins gratuitos de WordPress recomendados.

El hook before corre antes de registrar el consumo. Útil para validaciones adicionales: verificar que el cliente esté activo, que su suscripción en Stripe no esté vencida, o simplemente loggear el intento. El hook after corre post-registro. El ejemplo del README lo usa para loggear el uso actual, algo tan simple como imprimir en consola cuántos tokens lleva consumidos el cliente en esa sesión de billing.

También podés agregar campos custom en los overrides. Si tu lógica de negocio necesita guardar el stripeId, el planName o cualquier metadata relevante junto con el override, el plugin lo permite sin restricciones de esquema rígido (dentro de lo que soporta la versión actual, claro).

Integración con sistemas externos como Stripe

El soporte para Stripe está presente pero no está desarrollado como una integración bidireccional automática. Lo que tenés es el campo stripeId en el objeto de override de cada cliente. Con eso, tu lógica de sincronización puede:

• Leer el plan activo desde Stripe via webhook o API.
• Actualizar el override correspondiente en Better Auth Usage cuando cambia el plan.
• Usar el stripeId para correlacionar eventos de facturación con límites de uso.

No esperes un conector plug-and-play. La integración la construís vos. El plugin te da el campo y los hooks para que lo implementes como necesites. Para un proyecto mediano con plans simples, eso alcanza. Para algo más complejo con decenas de features y sync en tiempo real, vas a necesitar bastante código de pegamento.

Si tu stack corre en un VPS o servidor dedicado y necesitás algo sólido de base para este tipo de proyectos, donweb.com tiene opciones de cloud y VPS donde podés levantar este tipo de setup sin restricciones de hosting compartido que te limiten a mitad de camino.

Limitaciones actuales y roadmap del plugin

Ojo con esto: el plugin está en v0.1.17 y el propio autor advierte breaking changes en el futuro próximo. No es un proyecto maduro. Usarlo en producción hoy implica aceptar que vas a tener que adaptar código cuando salgan versiones nuevas. Tema relacionado: los parches de seguridad para AWS en marzo.

Del roadmap público en el repositorio se destacan items pendientes relevantes:

• Tabla de customers dedicada (actualmente el almacenamiento de overrides tiene limitaciones de esquema).
• Sincronización no bloqueante (hoy el sync puede afectar el tiempo de respuesta en ciertas operaciones).
• Mejoras en la API de hooks para soportar casos de uso más complejos.

El issue #231 en el repositorio principal de Better Auth toca precisamente la discusión sobre cómo los plugins de usage deberían integrarse con el core. Todavía no hay consenso cerrado (spoiler: el ecosistema está en movimiento y la API puede cambiar).

Diferencias con otras soluciones de auth

Auth.js y next-auth resuelven autenticación. Punto. No tienen nada parecido a un sistema de tracking de features por plan. Si lo necesitabas, lo construías vos o usabas un servicio externo de metering como Lago o Orb.

Better Auth, como ecosistema, apostó a ser extensible vía plugins desde el inicio. Usage es uno de esos plugins que cubre un caso de uso concreto y frecuente en SaaS: limitar qué puede hacer cada tier de usuario. La diferencia con una solución custom es que ya tenés el modelo de datos y los hooks definidos, no partís de cero.

Lo que no te da Better Auth Usage que sí dan soluciones de metering dedicadas es analytics avanzado, dashboards de consumo, o alertas automáticas cuando un cliente está cerca del límite. Para eso, igual necesitás construir algo encima o integrar una herramienta específica.

Tabla comparativa

Qué está confirmado y qué no

Confirmado

• El paquete está publicado en npm como @eggermarc/better-auth-usage, versión 0.1.17.
• Soporta features con maxLimit, overrides por cliente y hooks before/after.
• El campo stripeId está disponible en overrides para vincular con Stripe.
• El autor advierte explícitamente breaking changes en versiones futuras.
• El roadmap incluye tabla de customers y sync no bloqueante como items pendientes.

No confirmado / pendiente

• No hay fecha pública para la versión estable 1.0.
• La integración bidireccional con Stripe no está documentada oficialmente, más allá del campo stripeId.
• El comportamiento exacto del sync en versiones futuras puede cambiar según la discusión abierta en el issue #231 de Better Auth.
• No está claro si el plugin tendrá soporte para reset diferenciado por plan en versiones próximas.

Errores comunes al implementar Better Auth Usage

Usar el plugin en producción sin plan de migración

La advertencia de breaking changes no es decorativa. Si pinás la versión en tu package.json pero no tenés tests de integración cubriendo el flujo de usage, la próxima actualización te puede romper el control de límites sin que te enteres hasta que un cliente te avisa que consumió el doble de lo que debería. Pinás la versión, sí, pero también armás al menos un test básico del flujo completo. Para más detalles técnicos, mirá el incidente de hackeo en GitHub Actions.

Confundir overrides con sincronización automática de Stripe

El stripeId en el override no hace nada solo. Alguien tiene que escribir el código que escucha el webhook de Stripe, detecta el cambio de plan, y actualiza el override en Better Auth Usage. Si asumís que el plugin lo maneja automáticamente, te vas a encontrar con clientes en plan pro que siguen con el límite del plan starter porque nadie conectó los puntos. El plugin te da la estructura, la lógica de sincronización es tuya.

No manejar el caso de límite alcanzado en el frontend

Ponete en el lugar del usuario: llega al límite de tokens, la request falla, y no ve ningún mensaje claro. Muchos devs implementan el hook before para el backend pero se olvidan de manejar el error en el cliente de forma útil. El hook tiene que retornar un error estructurado que tu frontend pueda interpretar y mostrar algo como «alcanzaste tu límite mensual, pasá al plan pro». Sin eso, la experiencia de usuario es terrible y el soporte se llena de tickets confusos.

Preguntas Frecuentes

¿Qué es el plugin Better Auth Usage exactamente?

Es un plugin para el ecosistema Better Auth que agrega un sistema de tracking y limitación de uso de features por usuario o cliente. Permite definir qué puede hacer cada tier de suscripción (cuántas llamadas a una API, cuántos tokens, cuántos documentos) con límites configurables, overrides por cliente y hooks de lógica personalizada. Está disponible en npm como @eggermarc/better-auth-usage.

¿Cómo se instala y configura Better Auth Usage?

La instalación es npm add @eggermarc/better-auth-usage. La configuración va en el servidor de Better Auth, dentro del array de plugins, donde definís las features con sus maxLimit y estrategias de reset. Los overrides por cliente se configuran en el mismo objeto, con la posibilidad de agregar campos custom como stripeId. Toda la configuración es server-side.

¿Cómo se integra Better Auth Usage con Stripe?

La integración no es automática. El plugin provee el campo stripeId en los overrides de cliente para que puedas correlacionar cada cliente con su suscripción en Stripe. La lógica de sincronización, escuchar webhooks de Stripe y actualizar los overrides cuando cambia el plan, la construís vos. El plugin te da la estructura de datos, no el conector.

¿Está listo para usar en producción?

En la versión 0.1.17, con advertencia explícita de breaking changes, el riesgo es real. Para proyectos en producción, lo recomendable es pinár la versión en package.json, armar tests de integración sobre el flujo de usage, y monitorear el repositorio para estar al tanto de cambios en la API antes de actualizar. No es que no se pueda usar, pero lo hacés con los ojos abiertos.

Conclusión

Better Auth Usage plugin cubre un hueco real que las soluciones de auth tradicionales ignoran: el control granular de lo que cada tier de usuario puede hacer. El modelo de features con overrides y hooks es coherente y suficiente para la mayoría de los casos de uso de SaaS en 2026.

El tema es que estás trabajando con software en beta activa. El autor no oculta que hay breaking changes en el horizonte y el roadmap muestra que todavía falta trabajo en el core del plugin. Si necesitás estabilidad de API hoy y no tenés tiempo para adaptarte a cambios, quizás vale la pena esperar una versión más madura o evaluar una solución de metering dedicada.

Si en cambio estás construyendo un proyecto nuevo con Better Auth, tiene todo el sentido probarlo ahora, contribuir al repositorio si encontrás problemas, y estar en el loop del desarrollo. El ecosistema Better Auth está creciendo rápido y este plugin tiene chances reales de convertirse en la solución estándar para usage metering en ese stack. Safo por poco de quedarse sin opciones razonables en el ecosistema Node.js para este caso de uso.

Fuentes

• GitHub EggerMarc/better-auth-usage – Repositorio oficial del plugin con README, ejemplos y roadmap
• npm @eggermarc/better-auth-usage – Página oficial del paquete en el registro de npm
• Web Developer Blog – Contexto sobre autenticación con Better Auth en proyectos Next.js
• GitHub better-auth/better-auth issue #231 – Discusión sobre integración de plugins de usage con el core de Better Auth