⚡ Rapiserver – APIs ultrarrápidas con Bun + Hono + Routing por archivos

Rapiserver es una librería minimalista para crear APIs modernas con Bun y Hono, sin routers manuales ni configuración innecesaria.
Sólo define archivos y carpetas. Nosotros hacemos el resto. 🙌

📚 Tabla de contenido

• 🚀 ¿Qué hace Rapiserver?
• 🧰 Instalación
• 📁 Estructura mínima recomendada
• ✨ Crear una ruta
• 🔐 ¿Qué es un middleware?
• 🛡️ Ejemplo de middleware
• 📦 Aplicar un middleware a una carpeta
• 📌 Rutas dinámicas
• 🧠 Tipos incluidos
• 🧪 Iniciar el servidor
• 📚 ¿Cómo generar openapi.json?
• 🧩 Comandos útiles
• 🚀 Empezar rápido
• 🙋‍♂️ ¿Dudas?
• 📄 Licencia

🚀 ¿Qué hace Rapiserver?

• 📁 Cada archivo .ts es una ruta HTTP (get.ts, post.ts, etc.)
• 🧱 Cada carpeta puede tener su propio middleware (_middleware.ts)
• 🧠 OpenAPI se genera automáticamente
• 🏁 Servidor arranca en menos de 3 ms
• ✅ 100% compatible con TypeScript
• 🪄 Routing automático con soporte para rutas dinámicas como [id]

🧰 Instalación

bun add rapiserver

Requiere tener Bun instalado

📁 Estructura mínima recomendada

src/
├── api/                     # Aquí defines tus endpoints
│   ├── ping/get.ts          # GET /ping
│   └── user/[id]/get.ts     # GET /user/:id
├── middleware/              # Middlewares reutilizables opcionales
│   └── auth.ts              # Puedes importarlos en cualquier _middleware.ts
├── scripts/                 # Scripts útiles (como openapi)
└── index.ts                 # Punto de entrada del servidor

• api/: contiene todos tus endpoints organizados por carpeta. Cada archivo representa un método HTTP.
• middleware/: no necesita configuración. Úsala para mantener middlewares reutilizables y luego impórtalos desde los _middleware.ts en cada carpeta de api/.
• scripts/: para utilidades como generación de OpenAPI.
• index.ts: inicializa el servidor llamando a createServer.

✨ Crear una ruta

// src/api/ping/get.ts
import type { Context } from 'rapiserver';

export default async function handler(ctx: Context) {
  return ctx.text('pong');
}

• El nombre del archivo define el método HTTP.
• La ubicación define el path.
• handler viene tipado desde Rapiserver.

🔐 ¿Qué es un middleware?

Un middleware es una función que se ejecuta antes del handler de la ruta. Sirve para tareas como:

• Autenticación
• Validación de datos
• Agregar cabeceras
• Logging

🛡️ Ejemplo de middleware

// src/middleware/auth.ts
import type { Context, Next, Middleware } from 'rapiserver';

export default async function auth(ctx: Context, next: Next) {
  console.log('🔐 Usuario autenticado');
  return await next();
}

📦 Aplicar un middleware a una carpeta

// src/api/private/_middleware.ts
import auth from '../../middleware/auth';

export default [auth]; // se aplicará a todas las rutas dentro de /private

// src/api/private/profile/get.ts
import type { Context } from 'rapiserver';

export default async function handler(ctx: Context) {
  return ctx.json({ message: 'Perfil privado' });
}

📌 Rutas dinámicas

Puedes usar rutas como [id], que se transforman automáticamente en :id.

// src/api/user/[id]/get.ts
import type { Context } from 'rapiserver';

export default async function handler(ctx: Context) {
  const id = ctx.req.param('id');
  return ctx.json({ userId: id });
}

🧠 Tipos incluidos

Rapiserver exporta los tipos necesarios para que no tengas que importar nada desde hono:

import type { Context, Next, Middleware } from 'rapiserver';

• Context: el objeto de la petición/respuesta
• Next: función para continuar al siguiente middleware
• RouteHandler: tipo para handlers de rutas
• Middleware: tipo para middlewares

🧪 Iniciar el servidor

// src/index.ts
import { createServer } from 'rapiserver';

export default async function start() {
  createServer({
    production: process.env.NODE_ENV,
    port: 3000,
    apiFolder: 'src/api',
  });
}

start();

Ejecuta en modo desarrollo:

bun src/index.ts

📚 ¿Cómo generar openapi.json?

Rapiserver expone una función generateOpenAPI() que puedes usar desde tu proyecto para generar documentación automática.

1. Crea el archivo scripts/openapi.ts:

// scripts/openapi.ts
import { generateOpenAPI } from 'rapiserver';

export default async function gen() {
  await generateOpenAPI('src/api');
}

2. Añade el script en tu package.json:

"scripts": {
  "generate:openapi": "bun scripts/openapi.ts"
}

3. Ejecuta el script:

bun run generate:openapi

✨ Personalización por handler

Dentro de cualquier ruta, puedes exportar un objeto openapi:

export const openapi = {
  summary: 'Obtener perfil del usuario',
  responses: {
    200: {
      description: 'Perfil cargado correctamente',
    },
  },
};

Esto se incluirá automáticamente en el archivo generado.

🧩 Comandos útiles

bun dev                     # Modo desarrollo con hot reload
bun run build               # Compilar para producción
bun run serve               # Iniciar en modo producción
bun run generate:openapi    # Generar openapi.json para Swagger

🚀 Empezar rápido

bun add rapiserver

// src/index.ts
import { createServer } from 'rapiserver';

export default async function start() {
  createServer({
    port: 3000,
    apiFolder: 'src/api',
  });
}

start();

// src/api/hello/get.ts
import type { Context } from 'rapiserver';

export default async function handler(ctx: Context) {
  return ctx.text('Hola mundo');
}

bun src/index.ts

Accede a: http://localhost:3000/hello ✅

🙋‍♂️ ¿Dudas frecuentes?

• ¿Qué pasa si tengo rutas dinámicas como [id]? → Rapiserver las convierte automáticamente en :id.

• ¿Puedo usar middlewares por ruta? → No directamente, pero puedes componerlos dentro del mismo archivo o handler.

• ¿Puedo añadir validaciones? → Sí, puedes usar zod, valibot, yup o cualquier librería dentro de tus handlers o middlewares.

• ¿Puedo usar Rapiserver con Node.js? → No. Está diseñado para correr solo en el runtime Bun.

📄 Licencia

MIT © 2025 – David Dávila

Disfruta creando APIs en segundos con ⚡ Rapiserver

---