El Framework JS para
Desarrolladores Modernos.

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

E Configuración (.env)

Configura las variables de entorno para tu aplicación.

# URL Pública (SEO, Sitemap, Swagger)
APP_URL="https://blue-bird.com"

# Configuración del Servidor
HOST="localhost"
PORT=3000

# Metadatos Globales (Fallback)
TITLE_META="Blue Bird"
DESCRIPTION_META="Mi increíble proyecto"

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:{},
    rateLimit:{
          windowMs: 10 * 60 * 1000, 
           max: 300
        }
});

app.use(myCustomMiddleware);

app.run();

R Router

Gestiona tus rutas de forma modular y limpia.

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)
})

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 SEO automatizado y soporte multi-idioma.

SEO Routing Práctico

El método router.seo() permite registrar múltiples rutas con sus metadatos y props en una sola llamada.

import Router from "@seip/blue-bird/core/router.js";
import seoData from "./seo.js"; // Archivo externo de datos SEO

const frontendRouter = new Router();

// Opción A: Meta simple (sin i18n)
frontendRouter.seo([
    { path: "/", component: "Home", meta: { titleMeta: "Home", descriptionMeta: "Bienvenido" }, props: { id: 1 } }
]);

// Opción B: Multilenguaje con archivo externo seoData (recomendado)
frontendRouter.seo([
    { path: "/", component: "Home", seoKey: "home", props: { id: 1 } },
    { path: "/about", component: "About", seoKey: "about", props: { id: 2 } }
], { languages: ["en", "es"], defaultLanguage: "en", seoData });
// Genera: /, /en, /es, /about, /en/about, /es/about

// Opción C: Multilenguaje inline
frontendRouter.seo([
    {
        path: "/",
        component: "Home",
        meta: {
            en: { titleMeta: "Home", descriptionMeta: "Welcome" },
            es: { titleMeta: "Inicio", descriptionMeta: "Bienvenido" }
        }
    }
], { languages: ["en", "es"], defaultLanguage: "en" });

Archivo SEO Externo (seo.js)

Similar al patrón seo.php, centraliza los meta tags multilenguaje:

// backend/routes/seo.js
export default {
  home: {
    en: { titleMeta: "Home - Blue Bird", descriptionMeta: "Welcome", keywordsMeta: "home" },
    es: { titleMeta: "Inicio - Blue Bird", descriptionMeta: "Bienvenido", keywordsMeta: "inicio" }
  },
  about: {
    en: { titleMeta: "About", descriptionMeta: "About us" },
    es: { titleMeta: "Acerca", descriptionMeta: "Acerca de nosotros" }
  }
};

SEO Avanzado (Social & Automatización)

El framework ahora soporta etiquetas para redes sociales y generación automática de archivos esenciales para buscadores.

// Navegación SPA: cuando ?source=frontend se detecta, renderReact
// devuelve JSON {meta, props, component, lang} en vez de HTML.
fetch('/about?source=frontend')
  .then(r => r.json())
  .then(data => {
    // data = { meta: {titleMeta, descriptionMeta, ...}, props: {...}, component: "About", lang: "en" }
  });

Plantillas HTML & Estrategia Híbrida

Ideal para Landing Pages, Términos y Condiciones o Políticas de Privacidad que requieren una carga instantánea sin el peso de React.

router.get("/", (req, res) => {
    // Carga frontend/landing.html, aplica SEO de .env y lo guarda en caché RAM
    return Template.renderHtml(res, "landing", { 
        withAssets: false, // Zero JavaScript para máxima velocidad
        metaTags: { titleMeta: "Oferta Exclusiva" } 
    });
});

Renderizado Manual

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

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

router.get("/custom", (req, res) => {
    return Template.renderReact(res, "Custom", { some: "prop" }, {
        metaTags: {
            titleMeta: "Página Custom",
            descriptionMeta: "Descripción custom",
            langMeta: "es" // Setea automáticamente 
        },
        skeleton: true // Habilita el skeleton loading automáticamente
    });
});

V Validator

Valida datos de entrada con prevención automática de XSS.

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

const schema = {
    // La sanitización XSS se aplica por defecto a todos los campos string.
    email: { required: true, email: true },
    password: { required: true, min: 6 },
    // Puedes desactivarla explícitamente para permitir contenido HTML/React
    html_content: { required: true, xss: false }
};

const validate = new Validator(schema, 'es');
// El segundo parámetro permite devolver errores localizados según el idioma del cliente.

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

Localización de Errores (API)

El validador detecta automáticamente el idioma para los mensajes de error en este orden: Body, Query String, Cookies o el Header Accept-Language.

fetch('/api/register', {
    method: 'POST',
    headers: { 
        'Content-Type': 'application/json',
        'Accept-Language': 'es' // El validador devolverá errores en español
    },
    body: JSON.stringify(data)
});

// Útil para pruebas rápidas o links directos
fetch('/api/register?lang=esp', { 
    method: 'POST',
    body: JSON.stringify(data)
});

fetch('/api/register', {
    method: 'POST',
    body: JSON.stringify({
        ...data,
        lang: 'pt' // Prioridad máxima sobre el resto
    })
});

H Helmet (Seguridad)

Helmet no se aplica globalmente por defecto. Aplícalo por router donde sea necesario usando App.helmet().

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

// Aplicar helmet a un router específico
const webRouter = new Router("/web");
webRouter.use(App.helmet()); // Helmet con defaults
webRouter.use(App.helmet({ contentSecurityPolicy: false })); // Opciones custom

// O habilitar globalmente en el constructor de App (no recomendado)
new App({ helmet: true });

// Helmet con CSP personalizado
new App({
    helmet: {
        contentSecurityPolicy: {
            directives: {
                "script-src": ["'self'", "'unsafe-inline'"],
                "style-src": ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
            }
        }
    }
});

S SPA Navigation (SPAProvider)

El framework incluye un SPAProvider que conecta la navegación de React Router con los datos SEO del backend. En cada navegación por <Link>, hace un fetch al backend y actualiza document.title + meta tags automáticamente.

Configuración en App.jsx

import { SPAProvider } from './blue-bird/contexts/SPAContext.jsx';

// Envolver las rutas con SPAProvider
<SPAProvider languages={["en", "es"]} defaultLanguage="en">
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="/about" element={<About />} />
    {/* Las rutas con prefijo de idioma se generan automáticamente */}
    <Route path="/en" element={<Home />} />
    <Route path="/es" element={<Home />} />
    <Route path="/en/about" element={<About />} />
    <Route path="/es/about" element={<About />} />
  </Routes>
</SPAProvider>

Componentes de Navegación (Recomendado)

El framework provee componentes que encapsulan la lógica de localización para una sintaxis más limpia.

1. Componente <Link />

Reemplaza el Link de react-router-dom para persistir el idioma automáticamente.

import Link from "../blue-bird/components/Link";

// El componente añade el prefijo /es/ o /en/ automáticamente según la sesión
<Link to="/about">Sobre nosotros</Link>

2. Componente <LanguageButton />

Encapsula la lógica de navigateToLang.

import LanguageButton from "../blue-bird/components/LanguageButton";

<LanguageButton lang="es" variant="outline">Español</LanguageButton>
<LanguageButton lang="en" variant="outline">English</LanguageButton>

Soporte Monolingüe

Si tu aplicación solo usa un idioma, simplemente deja el array LANGUAGES vacío en App.jsx. El framework desactivará automáticamente toda la lógica de prefijos.

// App.jsx
const LANGUAGES = []; // Aplicación monolingüe
const DEFAULT_LANGUAGE = "es";

M Router Middlewares

Cada Router soporta el método use() para aplicar middlewares a todas las rutas de ese router. Esto es ideal para proteger grupos de rutas sin repetir el middleware en cada una.

Helmet por Router

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

const routerFrontend = new Router();
routerFrontend.use(App.helmet()); // Helmet solo para este router

// Todas las rutas de este router están protegidas por Helmet
routerFrontend.get("/", (req, res) => { ... });
routerFrontend.get("/about", (req, res) => { ... });

Router Protegido con Auth

Perfecto para crear routers de admin, dashboard o rutas autenticadas. El middleware se aplica una sola vez y protege todas las rutas del router.

import Router from "@seip/blue-bird/core/router.js";
import Middleware from "@seip/blue-bird/core/middleware.js";
import Auth from "@seip/blue-bird/core/auth.js";

// Opción 1: Usando Middleware pre-configurado
const routerAdmin = new Router("/admin");
routerAdmin.use(Middleware.auth); // Todas las rutas requieren JWT

routerAdmin.get("/dashboard", (req, res) => {
    res.json({ user: req.user }); // req.user disponible en todas
});
routerAdmin.get("/settings", (req, res) => {
    res.json({ settings: {} });
});

// Opción 2: Usando Auth.protect() con redirect
const routerDashboard = new Router("/dashboard");
routerDashboard.use(Auth.protect({ redirect: "/login" }));

routerDashboard.get("/", (req, res) => {
    return Template.renderReact(res, "Dashboard");
});

Middleware Personalizado

const routerApi = new Router("/api");

// Middleware personalizado de logging
routerApi.use((req, res, next) => {
    console.log(`[API] ${req.method} ${req.url}`);
    next();
});

// Múltiples middlewares
routerApi.use(Middleware.auth);
routerApi.use(App.helmet());

routerApi.get("/users", (req, res) => { ... });

A Auth Middleware (JWT)

Protege rutas API y React con autenticación JWT. Los tokens se leen de Cookies o del header Authorization.

import Auth from "@seip/blue-bird/core/auth.js";

// Proteger ruta API (retorna 401 si falla):
router.get("/profile", Auth.protect(), (req, res) => {
    res.json({ user: req.user });
});

// Proteger ruta React (redirige a login):
router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => {
    return Template.renderReact(res, "Dashboard");
});

// Generar token:
const token = Auth.generateToken({ id: user.id, email: user.email });

// Verificar token:
const decoded = Auth.verifyToken(token);

Middleware Pre-configurado

import Middleware from "@seip/blue-bird/core/middleware.js";

// Middleware auth pre-configurado
router.get("/api/profile", Middleware.auth, controller.profile);

// Middleware web auth (redirige a / si falla)
router.get("/dashboard", Middleware.webAuth, (req, res) => {
    return Template.renderReact(res, "Dashboard");
});

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

Cómo Funciona

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

⚠️ Consideraciones