The JS Framework for
Modern Developers.

A powerful structure based on Express and React, designed to build fast applications and everything you need pre-configured.

View Documentation

npm install @seip/blue-bird

The Blue Bird Philosophy

Tired of configuring CORS, Cookies,etc and Routing every time you start a project? Blue Bird provides a solid, pre-configured base so you can go straight to the business logic, without losing the pure extensibility of Express.

⚡ All-In-One

Express, React , Validations, JWT Auth, and Uploads ready to use.

💎 Flexible

Use the `.use()` method to configure Express middleware just like you always do.

Core Features

Designed to scale with elegance.

Integrated JWT Auth

Token generation and validation with middleware ready to protect your API or Web routes.

Data Validation

Multi-language validation engine with predefined rules and automatic messages.

Upload Helpers

File uploads to disk powered by Multer, configured for your public folder.

React

React, React Router pre-configured and ready to use in SPA .

Vite

Vite ready to use , for dev and production.

Express

Express pre-configured and ready to use in API mode and Web mode.

Technical Reference

Everything about the Blue Bird Core API.

Init Initialize App

Initialize your Blue Bird application.

npx blue-bird

React React Setup

Setup React for your Blue Bird application.

npm run react

Dev Dev Setup (Express + Vite)

Edit package.json for "module" and "type": "module" support

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

Setup Dev for your Blue Bird application.

npm run dev

Setup Vite for your Blue Bird application.

npm run vite:dev

App Main App Class

Central configuration for your Express server.

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

// Extend Express with .use()
app.use(myCustomMiddleware); 


app.run();

Option	Type	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
cookieParser	Boolean	true
helmet	Boolean \| Object	true
xssClean	Boolean	true
swagger	Boolean	true

Integrated Security

🛡️ Helmet

Automatically activates secure HTTP headers to protect against common attacks like clickjacking, MIME sniffing and more.

new App({
    helmet: true
});

Also accepts custom configuration.

🧼 XSS Clean

Automatically sanitizes the request body to prevent malicious script injection (XSS).

new App({ 
    xssClean: true
});

Global Rate Limit

Blue Bird includes IP-based request throttling using express-rate-limit.

new App({
    rateLimit: {
        windowMs: 15 * 60 * 1000, // 15 minutes
        max: 100
    }
});

Behavior

Applies global IP limiting.
Returns JSON when the limit is exceeded.
Automatically respects trust proxy.
In Debug mode, excludes the route /debug.

Integrated Logger

Blue Bird includes a logging system that:

Register HTTP method, IP and URL.
Automatically hides sensitive parameters (password, token).
Save logs to file.
In Debug mode it shows colored logs in the console.

R Router

Manage your routes in a modular and clean way.

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' });
});
//Example renderReact with customized meta Tags 
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

Render React components with automated SEO and multi-language support.

Practical SEO Routing

The router.seo() method allows you to register multiple routes with metadata and props in a single call. It supports both single-language and multi-language configurations.

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

const frontendRouter = new Router();

frontendRouter.seo([
    {
        path: "/",
        component: "Home",
        // Multi-language support (prefixed routes like /es/ will be created)
        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",
        // Direct meta support for single language
        meta: { titleMeta: "About Us", descriptionMeta: "Learn more about Blue Bird" },
        props: { id: 2 }
    }
], { 
    languages: ["en", "es"], 
    defaultLanguage: "en" 
});

// IMPORTANT: Wildcard route for SPA support
routerFrontendExample.get("*", (req, res) => {
    return Template.renderReact(res, "App");
});

💡 Best Practices & SEO

Path Matching: The routes defined in router.seo() must exactly match the routes in your App.jsx (React Router). Otherwise, React will load the default route upon hydration.
Wildcard Route (*): It is essential to include a * route at the end to ensure any sub-route not specifically defined is correctly handled by the SPA (App).
SEO/AI Advantage: This method is ideal for SEO because bots and AI detect the initial server-side rendering with the correct meta tags (title, description, keywords) before React's JavaScript takes over.

Manual Rendering

If you need more control, you can use Template.renderReact directly. It automatically handles the <html lang="..."> attribute if langMeta is provided.

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

router.get("/custom", (req, res) => {
    return Template.renderReact(res, "Custom", { some: "prop" }, {
        metaTags: {
            titleMeta: "Custom Page",
            descriptionMeta: "Custom description",
            langMeta: "en" // Automatically sets 
        },
        skeleton: true // [NEW] Enables skeleton loading (loading loaders) automatically
    });
});

V Validation

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

const routerUsers = new Router("/api")

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

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

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) //Mode manual  
Auth.protect(); // Middleware
//Get user with jwt
routerApiExample.get("/user", Auth.protect(), (req, res) => {
const currentUser = req;
console.log(`Request made by: ${currentUser.name} (ID: ${currentUser.id})`);
....});

Uploads

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

UI Frontend & Components

Multi-language Support

The frontend features built-in multi-language capabilities. A Context Provider reads the blue_bird_lang key from your localStorage to manage translations across components.

Note: By default, Blue Bird already includes LanguageProvider in App.jsx to manage multi-language applications natively. If you wish to remove it, simply edit App.jsx and remove the provider wrapping.

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

export default function App() {
  return (
    <LanguageProvider>
      <Router>
        {/* Your Routes Here */}
      </Router>
    </LanguageProvider>
  );
}

Then, inside any component or page you can use the useLanguage() hook:

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

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

  return (
    <div>
      {/* Translations are located in frontend/resources/js/blue-bird/locales/[lang].json */}
      <p className="error">{t('error_general')}</p>
    </div>
  );
}

Pre-built React Components

To accelerate development, we provide beautiful, ready-to-use React components. They are styled using Tailwind CSS (which is now integrated natively via Vite in vite.config.js, ensuring optimal performance). Some of the included components:

Button: Buttons with multiple variants and states.
Input: Standardized text fields.
Card: Clean containers for your UI.
Snackbar / SnackbarContext: Toast notifications for user feedback.
Typography: Consistent typography sizing and colors.

Auth Auth Scaffolding

Blue Bird provides a zero-config, production-ready complete authentication system scaffolding tool.

npm run scaffolding-auth

What does it generate?

Backend routes (routes/auth.js, routes/authenticated.js) with ready logic for login, registration, logout, and password resets.
An independent service inside backend/databases/services/auth.service.js. This separates database logic, so if you wish to swap raw SQL with Prisma or another ORM later, it's very straightforward.
React frontend views at frontend/resources/js/pages/auth (Login, Register, Dashboard, Forgot/Reset Password).
Fully localized interfaces, supporting our multi-language translations automatically.

C Cache Middleware

Simple in-memory caching middleware for JSON responses. It allows for improved performance by avoiding repeatedly running the handler for a defined period.

Basic Use

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

const routerStats = new Router("/")

routerStats("/stats", 
    Cache.middleware(120), // 120 seconds 
    controller.stats
);
//Testing
routerStats("/stats_", 
    cache.middleware(120), 
    async (req, res) => { 
        await new Promise(resolve => setTimeout(resolve, 2000)); 
    
    res.json({ 
        message: 'Login successful', 
        note: 'This response took 2 seconds to arrive.' 
    }); 
    }
);;

Parameter

Parameter	Type	Default	Description
seconds	Number	60	Time in seconds that the response remains cached.

How It Works

Use req.originalUrl as cache key.
Intercepts res.json() to store the response.
If the key exists and has not expired, return the cached JSON.
If it expires, re-execute the handler.
The cache is lost when the server restarts.

S Swagger Integration

Automated documentation integration using Swagger (OpenAPI 3). Allows you to view and test endpoints directly from your browser.

First install swagger with npm or cli blue-bird with:

    
        npm run swagger-install

Basic Configuration


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

Use on Routes

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

Reusable Schemas

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

Access

Documentation will be available in /docs.
Allows you to test endpoints directly from the browser.
Supports authentication if defined in components.securitySchemes.

⚠️ Considerations

Comments @swagger must be properly indented.
Paths must exactly match those defined in Express.
In production, it is recommended to protect /docs.

D Debug & Metrics

The Debug module allows you to monitor your application's performance in real time. It records metrics such as response time, RAM usage, CPU consumption, and statistics by route. When Debug=true is set in .env, the route is activated.

Then access the visual panel at:

http://localhost:3000/debug

Features

📊 Recorded Metrics

Response time (ms)
Memory usage (RSS)
CPU consumption
HTTP Status
History of last 50 requests

⚙️ Features

Auto update with fetch
Endpoint JSON: /debug?fetch=true
Metrics reset button
Does not log static files
Does not register the /debug

Endpoint JSON

GET /debug?fetch=true

Returns metrics in JSON format:

{ 
    "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 
        } 
    }
}

Production

Blue Bird is designed for production. With features like caching, gzip compression, and robust error handling, you can be sure that your application will work correctly.

For production, it is recommended to use a proxy server like Nginx to handle SSL, gzip compression, and load balancing.

First edit .env , putting DEBUG=false

DEBUG=false

Then run the command to generate the build of react with vite:

npm run vite:build

To run in production use "npm run start" , so with PM2 we will do:

pm2 start npm --name "blue-bird" -- run start

This will start the application in production and keep it alive .

pm2 save

This will save the PM2 configuration so that it starts automatically when the server restarts.

The JS Framework for Modern Developers.