Blue Bird Framework

El Framework JS para
Desarrolladores Modernos.

Una estructura potente basada en Express y React, diseñada para crear aplicaciones rápidamente y todo lo que necesitas pre-configurado.

Ver Documentación
npm install @seip/blue-bird

La Filosofía Blue Bird

¿Cansado de configurar CORS, Cookies y Routing,etc cada vez que inicias un proyecto? Blue Bird provee una base sólida y pre-configurada para que vayas directo a la lógica, sin perder la extensibilidad pura de Express.

⚡ Todo Incluido

Express, React , Validaciones, JWT Auth y Uploads listos para usar.

💎 Flexible

Usa el método `.use()` para configurar middleware de Express tal como lo haces siempre.

Características Principales

Diseñado para escalar con elegancia.

JWT Auth Integrado

Generación y validación de tokens con middleware listo para proteger tus rutas API o Web.

Validación de Datos

Motor de validación multi-idioma con reglas predefinidas y mensajes automáticos.

Upload Helpers

Subida de archivos a disco facilitada por Multer, configurada para tu carpeta pública.

React

React y React Router pre-configurados para SPA, o páginas tradicionales.

Vite

Vite listo para usar, optimizado para desarrollo y producción.

Ex

Express

Express pre-configurado para modo API o modo Web tradicional.

Referencia Técnica

Todo sobre la API Core de Blue Bird.

Init Inicializar App

Inicializa tu aplicación Blue Bird.

npx blue-bird

React Configuración React

Configura React para tu aplicación Blue Bird.

npm run react

Dev Configuración Dev (Express + Vite)

Editar package.json para soporte "module" y "type": "module"

{
  "type": "module",....
}

Inicia el servidor backend:

npm run dev

Inicia el servidor frontend (Vite): 

npm run vite:dev

App Clase App principal

Configuración central de tu servidor Express. 

import App from "@seip/blue-bird/core/app.js";
import routerUsers from "./routes/users.js";

const app = new App({
    port: 3000,
    routes: [routerUsers],
    cors:[],\\ [{ origin: '*' }],
    rateLimit:{
          windowMs: 10 * 60 * 1000, 
           max: 300
        }
});

app.use(myCustomMiddleware);

app.run();
Opción Tipo Default
routes Array []
middlewares Array []
port Number 3000
host String "http://localhost"
cors Object {}
static Object { path: null, options: {} }
rateLimit Boolean | Object false
logger Boolean true
notFound Boolean true
json Boolean true
urlencoded Boolean true
cookieParser Boolean true
helmet Boolean | Object true
xssClean Boolean true
swagger Boolean true

Seguridad Integrada

🛡️ Helmet

Activa automáticamente headers HTTP seguros para proteger contra ataques comunes como clickjacking, MIME sniffing y más. 

new App({
  helmet: true
});

También acepta configuración personalizada.

🧼 XSS Clean

Sanitiza automáticamente el body de las requests para prevenir inyección de scripts maliciosos (XSS). 

new App({
  xssClean: true
});

R Router

Maneja tus rutas de forma modular y límpia.

import Router from "@seip/blue-bird/core/router.js";
import Template from "@seip/blue-bird/core/template.js";

const routerUsers = new Router("/")

routerUsers.get("/users", (req, res) => {
    const users = [
        {
            name: "John Doe",
            email: "john.doe@example.com",
        },
        {
            name: "Jane Doe2",
            email: "jane.doe2@example.com",
        },
    ]
    res.json(users)
})

const loginSchema = {
    email: { required: true, email: true },
    password: { required: true, min: 6 }
};

const loginValidator = new Validator(loginSchema, 'es');

routerUsers.post('/login', loginValidator.middleware(), (req, res) => {
    res.json({ message: 'Login successful' });
});

//Ejemplo de renderReact con meta Tags modificados
routerUsers.get("/about", (req, res) => {
    const response = Template.renderReact(res, "About", { title: "About Example title" }, {
        metaTags: {
            titleMeta: "About Title",
            descriptionMeta: "About description",
            keywordsMeta: "About,express, react, framework",
            authorMeta: "Blue Bird",
            langMeta: "es"
        }
    });
    return response;
})


routerUsers.get("*", (req, res) => {
    // Renderizado SPA con React
    return Template.renderReact(res, "App", { title: "Mi Proyecto" });
})

export default routerUsers;

T Template & SEO

Renderiza componentes React con soporte automatizado para SEO y multi-idioma.

Routing SEO Práctico

El método router.seo() permite registrar múltiples rutas con metadatos y props en una sola llamada. Soporta configuraciones de idioma único y multi-idioma.

import Router from "@seip/blue-bird/core/router.js";

const frontendRouter = new Router();

frontendRouter.seo([
    {
        path: "/",
        component: "Home",
        // Soporte multi-idioma (se crearán rutas con prefijo como /es/)
        en: { title: "Home - Blue Bird", desc: "Welcome to our framework" },
        es: { title: "Inicio - Blue Bird", desc: "Bienvenido a nuestro framework" },
        props: { id: 1 }
    },
    {
        path: "/about",
        component: "About",
        // Soporte de meta directo para un solo idioma
        meta: { titleMeta: "Sobre Nosotros", descriptionMeta: "Conoce más sobre Blue Bird" },
        props: { id: 2 }
    }
], { 
    languages: ["en", "es"], 
    defaultLanguage: "en" 
});

// IMPORTANTE: Ruta comodín para soportar SPA
routerFrontendExample.get("*", (req, res) => {
    return Template.renderReact(res, "App");
});
💡 Buenas Prácticas y SEO
  • Coincidencia de Rutas: Las rutas definidas en router.seo() deben coincidir exactamente con las rutas de tu App.jsx (React Router). De lo contrario, React cargará la ruta por defecto al hidratarse.
  • Ruta Comodín (*): Es esencial incluir una ruta * al final para asegurar que cualquier sub-ruta no definida específicamente sea manejada por la SPA (App).
  • Beneficio SEO/IA: Este método es ideal para el SEO, ya que los bots e IA detectan el renderizado inicial del servidor con los meta tags correctos (title, description, keywords) antes de que el JavaScript de React tome el control.

Renderizado Manual

Si necesitas más control, puedes usar Template.renderReact directamente. Maneja automáticamente el atributo <html lang="..."> si se proporciona langMeta. 

import Template from "@seip/blue-bird/core/template.js";

router.get("/personalizado", (req, res) => {
    return Template.renderReact(res, "Custom", { some: "prop" }, {
        metaTags: {
            titleMeta: "Página Personalizada",
            descriptionMeta: "Descripción personalizada",
            langMeta: "es" // Configura automáticamente 
        },
        skeleton: true // [NUEVO] Activa pantallas de carga (loading loaders) automáticamente
    });
});

V Validación 

import Validator from "@seip/blue-bird/core/validate.js";

const schema = {
    email: { required: true, email: true },
    password: { required: true, min: 6 }
};

const validate = new Validator(schema, 'es');

router.post("/register", validate.middleware(), (req, res) => {
    res.json({ message: "OK" });
});

Auth (JWT)

import Auth from "@seip/blue-bird/core/auth.js";
const token =Auth.generateToken(payload);
res.cookie("token", token, {
  httpOnly: true,          
  secure: process.env.NODE_ENV === "production", 
  sameSite: "strict",
  maxAge: 24 * 60 * 60 * 1000
});
Auth.verifyToken(token) //Forma manual                
Auth.protect(); // Middleware
                        
//Obtener valor
 routerApiExample.get("/user", Auth.protect(), (req, res) => {
    const currentUser = req.user;
    console.log(`Petición realizada por: ${currentUser.name} (ID: ${currentUser.id})`);
....});

Uploads

import Upload from "...";
Upload.disk({ folder: 'img' });
// Basado en Multer

UI Frontend & Componentes

Soporte Multilenguaje

Lila integra soporte nativo para múltiples idiomas en el frontend mediante un Context Provider, usando la clave blue_bird_lang en el localStorage para mantener la preferencia del usuario.

Nota: Por defecto, Blue Bird ya incluye LanguageProvider en App.jsx para gestionar aplicaciones multiidioma de forma nativa. Si deseas removerlo, simplemente edita App.jsx y elimina el wrapping del provider. 

import { LanguageProvider } from './blue-bird/contexts/LanguageContext.jsx';

export default function App() {
  return (
    <LanguageProvider>
      <Router>
        {/* Tus rutas */}
      </Router>
    </LanguageProvider>
  );
}

Luego, dentro de cualquier componente o página puedes utilizar el hook useLanguage(): 

import { useLanguage } from '../../blue-bird/contexts/LanguageContext.jsx';

export default function Login() {
  const { t, lang, setLang } = useLanguage();

  return (
    <div>
      {/* Las traducciones están en frontend/resources/js/blue-bird/locales/[lang].json */}
      <p className="error">{t('error_general')}</p>
    </div>
  );
}

Componentes Pre-construidos

Para acelerar el desarrollo, incluimos componentes React elegantes y listos para usar. Están estilizados con Tailwind CSS (el cual ahora se integra nativamente vía Vite en vite.config.js, asegurando un rendimiento óptimo). Destacan:

  • Button: Botones con diversas variantes y estados.
  • Input: Campos de texto accesibles y estandarizados.
  • Card: Contenedores limpios.
  • Snackbar / SnackbarContext: Notificaciones flotantes (toasts) para feedback rápido.
  • Typography: Estilos base unificados para tus textos.

Auth Auth Scaffolding

Blue Bird incluye una herramienta para generar de principio a fin todo el sistema de autenticación completo, listo para producción. 

npm run scaffolding-auth

¿Qué se incluye?

  • Rutas backend integrales (routes/auth.js, routes/authenticated.js) con flujos de login, registro, logout y recuperación de contraseñas.
  • Un servicio de base de datos extraído a backend/databases/services/auth.service.js. Esto aisla las consultas, permitiendo que reemplaces fácilmente el SQL nativo por ORMs como Prisma si así lo deseas.
  • Todas las interfaces para React dentro de frontend/resources/js/pages/auth (Login, Register, Dashboard protegido y restablecimiento de claves).
  • Vistas totalmente localizadas y enlazadas a los diccionarios de traducciones (Multi-idioma por defecto).

C Cache Middleware

Middleware simple de cache en memoria para respuestas JSON. Permite mejorar el rendimiento evitando ejecutar el controlador repetidamente durante un período definido.

Uso Básico

import Cache from "@seip/blue-bird/core/cache.js";
import Router from "@seip/blue-bird/core/router.js"
                        
const routerStats = new Router("/")
                        
routerStats("/stats",
  Cache.middleware(120), // 120 segundos
  controller.stats
);
//Testing                    
routerStats("/stats_",
  Cache.middleware(120),
  async (req, res) => {  
    await new Promise(resolve => setTimeout(resolve, 2000));

    res.json({ 
      message: 'Login successful',
      note: 'Esta respuesta tardó 2 segundos en llegar.'
    });
  }
);

Parámetro

Parámetro Tipo Default Descripción
seconds Number 60 Tiempo en segundos que la respuesta permanece en cache.

Cómo Funciona

  • Usa req.originalUrl como clave de cache.
  • Intercepta res.json() para almacenar la respuesta.
  • Si la clave existe y no expiró, devuelve el JSON cacheado.
  • Si expira, ejecuta nuevamente el controlador.
  • El cache se pierde al reiniciar el servidor.

S Swagger Integration

Integración de documentación automática utilizando Swagger (OpenAPI 3). Permite visualizar y probar endpoints directamente desde el navegador.

Primero instala swagger con npm o cli blue-bird : 

    
        npm run swagger-install

Configuración Básica


const app = new App({
    routes: [routerUsers],
    cors: [],
    middlewares: [],
    port: 3000,
    host: "http://localhost",
    swagger:{
        info: {
            title: "Blue Bird API",
            version: "1.0.0",
            description: "Blue Bird Framework API Documentation"
        },
        url : "http://localhost:8000"
    }
})

Uso en Rutas

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     tags: [Users]
 *     responses:
 *       200:
 *         description: List of users
 */
router.get("/users", controller.getUsers);

Schemas Reutilizables

/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         name:
 *           type: string
 *         email:
 *           type: string
 */

Acceso

  • La documentación estará disponible en /docs.
  • Permite probar endpoints directamente desde el navegador.
  • Soporta autenticación si se define en components.securitySchemes.

⚠️ Consideraciones

  • Los comentarios @swagger deben estar correctamente indentados.
  • Las rutas deben coincidir exactamente con las definidas en Express.
  • En producción se recomienda proteger /docs.

D Debug & Métricas

El módulo Debug permite monitorear el rendimiento de tu aplicación en tiempo real. Registra métricas como tiempo de respuesta, uso de memoria RAM, consumo de CPU y estadísticas por ruta. Cuando en .env es Debug=true queda activada la ruta.

Luego accede al panel visual en: 

http://localhost:3000/debug

Características

📊 Métricas Registradas
  • Tiempo de respuesta (ms)
  • Uso de memoria (RSS)
  • Consumo de CPU
  • Status HTTP
  • Historial de últimas 50 requests
⚙️ Funcionalidades
  • Auto actualización con fetch
  • Endpoint JSON: /debug?fetch=true
  • Botón de reset de métricas
  • No registra archivos estáticos
  • No registra la ruta /debug

Endpoint JSON

GET /debug?fetch=true

Devuelve las métricas en formato JSON: 

{
  "requests": [
    {
      "method": "GET",
      "url": "/users",
      "status": 200,
      "responseTime": 32.14,
      "ramUsedMB": 45.21,
      "cpuUsedMS": 1.23,
      "date": "2026-02-27T12:00:00.000Z"
    }
  ],
  "routes": {
    "GET /users": {
      "count": 5,
      "totalTime": 160.5
    }
  }
}

Producción

Blue Bird está diseñado para producción. Con características como caching, compresión gzip, y manejo de errores robusto, puedes estar seguro de que tu aplicación funcionará correctamente.

Para producción, se recomienda usar un servidor proxy como Nginx para manejar el SSL, la compresión gzip, y el balanceo de carga.

Primero edita .env , poniendo DEBUG=false 

DEBUG=false

Luego ejecuta el comando para generar la build de react con vite: 

npm run vite:build

Para ejecutar en producción se utiliza "npm run start" , por lo que con PM2 haremos: 

pm2 start npm --name "blue-bird" -- run start
Esto iniciará la aplicación en producción y la mantendrá viva . 
pm2 save
Esto guardará la configuración de PM2 para que se inicie automáticamente al reiniciar el servidor.