Total.js Forge: un recetario donde cada receta se ejecuta, pensado para desarrolladores y asistentes de IA

La documentación tiene un problema que conocemos todos: el ejemplo de la página funcionó una vez, para alguien, en alguna versión. Luego el framework avanzó y nadie se dio cuenta.

Somos el equipo de Total.js y queríamos un sitio donde eso no pudiera pasar. Así que hemos creado Total.js Forge: un recetario para Total.js 5 y jComponent 20 donde cada receta se ejecuta antes de publicarse.

👉 https://forge.totaljs.es

Qué es Total.js, en un párrafo

Total.js 5 es un framework de Node.js con un núcleo sin dependencias. Rutas, WebSocket, autenticación, sesiones, subida de archivos, tareas programadas, correo, vistas, proxy, localización y una base de datos NoSQL embebida vienen incluidos, así que un proyecto típico no empieza con un npm install interminable ni con una pila de decisiones. Es ligero, se aprende rápido y el código se mantiene legible porque hay una sola manera de hacer cada cosa.

Cada receta se ejecuta

Una receta de Forge es una página Markdown con el código, las rutas de los archivos y un bloque test oculto. npm run validate hace esto con cada una:

• Recetas de Total.js 5: crea una app temporal, escribe los archivos, la arranca y lanza las comprobaciones contra ella (HTTP, WebSocket, transacciones reales de SQLite, OpenLDAP, subidas...).
• Recetas de jComponent: se ejecutan en Chromium sin interfaz.

Si una receta falla, no se publica. El resultado de cada ejecución queda guardado como recibo legible por máquinas.

Así se ve una página, una ruta con validación en Total.js 5:

// actions/users.js
NEWACTION('Users_create', {
    name: 'Create a user',
    input: '*name:String, *email:Email, age:Number',
    action: async function($, model) {
        // model ya está validado, una petición incorrecta nunca llega aquí
        $.callback({ success: true, name: model.name });
    }
});

// controllers/users.js
exports.install = function() {
    ROUTE('+API    /api/    +users_create  *Users_create');
};

Corto, sin paquetes extra, y la página que lo acompaña dice exactamente qué necesita y que está probado.

Qué hay dentro

• Más de 100 recetas de Total.js 5: rutas, acciones, WebSocket, autenticación, subidas, SQL y NoSQL, Flow, bundles, modo release, LDAP y más
• 30 recetas de jComponent, con editor y vista previa en vivo en el navegador
• Más de 330 páginas de componentes del catálogo de Componentator, cada una con su autor y su fuente
• Páginas de referencia: cada global, cada clave de CONF, cada opción de NEWACTION, sintaxis de rutas, tipos de entrada, una guía de Express a Total.js y una página de errores comunes (código incorrecto junto al correcto)
• 15 idiomas: inglés más 14 traducciones. Solo se traduce la prosa; el código es el mismo que se ejecutó
• Benchmarks repetibles: Total.js 5 frente a Total.js 4, Node.js, Express, Fastify, Koa, Hapi, Hono, Polka, Restify, NestJS, AdonisJS y Meteor. Las apps, los lock files, el runner y los resultados en bruto están en el repo, y npm run verify comprueba que las páginas coinciden con los datos

Hecho también para asistentes de IA

Muchos preguntamos ya a un asistente antes de abrir la documentación. Por eso Forge está hecho para que los modelos lo lean sin scraping:

Endpoint	Qué ofrece
/llms.txt, /llms-full.txt	Índice y contenido completo, en texto plano
/{lang}/{section}/{slug}.md	Cualquier página en Markdown
/dataset.jsonl, /benchmark.jsonl, /preferences.jsonl	Pares pregunta-respuesta, tareas con test, código incorrecto frente a correcto
POST /mcp/	Un servidor MCP de solo lectura: búsqueda, página, test, productos y Forge_verify_api
/.well-known/...	Tarjeta del servidor MCP, agent skills, catálogo de API

Forge_verify_api es mi favorita: le envías un trozo de código y comprueba cada nombre global y cada miembro contra las páginas, así un asistente puede saber antes de responder que ALGO_QUE_NO_EXISTE no forma parte del framework. Solo lee el código, nunca lo ejecuta, y avisa de lo que no puede ver.

El contenido es CC-BY-4.0, así que puedes usarlo para entrenar, evaluar o dar contexto a tus propias herramientas.

Una pequeña historia de los benchmarks

Midiendo a decenas de miles de peticiones por segundo encontramos un punto de total5 0.0.19 donde limpiar la lista de peticiones terminadas se volvía costoso a tasas muy altas. Lo documentamos con una reproducción que se ejecuta en un minuto, un parche pequeño y los números antes y después (con el cambio, un proceso sostiene el objetivo hasta 80.000 peticiones por segundo en nuestra máquina). Está en benchmarks/FINDINGS.md, como sugerencia para que los autores la revisen. Esa es la idea de Forge: medir, escribir lo que ves y hacerlo repetible.

Ven a verlo

Si escribes Node.js y te gustan los frameworks que te dan el kit completo sin cien dependencias, prueba Total.js y cuéntanos qué falta en el recetario. Las recetas son Markdown plano.

• 🌐 https://forge.totaljs.es

¡Gracias por leer!