The JS Framework for
Modern Developers.

React React Configuration

Set up React for your Blue Bird application.

npm run react

Dev Dev Setup (Express + Vite)

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

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

Start the backend server:

npm run dev

Start the frontend server (Vite):

npm run vite:dev

E Configuration (.env)

Configure environment variables for your application.

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

# Server Configuration
HOST="localhost"
PORT=3000

# Global Metadata (Fallback)
TITLE_META="Blue Bird"
DESCRIPTION_META="My amazing project"

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

app.use(myCustomMiddleware);

app.run();

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

routerUsers.get("*", (req, res) => {
    // SPA Rendering with React
    return Template.renderReact(res, "App", { title: "My Project" });
})

export default routerUsers;

T Template & SEO

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

Practical SEO Routing

The router.seo() method allows registering multiple routes with their metadata and props in a single call.

import Router from "@seip/blue-bird/core/router.js";
import seoData from "./seo.js"; // External SEO data file

const frontendRouter = new Router();

// Option A: Simple meta (no i18n)
frontendRouter.seo([
    { path: "/", component: "Home", meta: { titleMeta: "Home", descriptionMeta: "Welcome" }, props: { id: 1 } }
]);

// Option B: Multilingual with external seoData file (recommended)
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 });
// Generates: /, /en, /es, /about, /en/about, /es/about

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

External SEO File (seo.js)

Similar to the seo.php pattern, centralizes multilingual meta tags:

// 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" }
  }
};

Advanced SEO (Social & Automation)

The framework now supports social media tags and automatic generation of essential files for search engines.

// SPA Navigation: when ?source=frontend is detected, renderReact
// returns JSON {meta, props, component, lang} instead of HTML.
fetch('/about?source=frontend')
  .then(r => r.json())
  .then(data => {
    // data = { meta: {titleMeta, descriptionMeta, ...}, props: {...}, component: "About", lang: "en" }
  });

HTML Templates & Hybrid Strategy

Ideal for Landing Pages, Terms & Conditions, or Privacy Policies that require instant loading without the weight of React.

router.get("/", (req, res) => {
    // Loads frontend/landing.html, applies SEO from .env and stores it in RAM cache
    return Template.renderHtml(res, "landing", { 
        withAssets: false, // Zero JavaScript for maximum speed
        metaTags: { titleMeta: "Exclusive Offer" } 
    });
});

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 // Automatically enables skeleton loading
    });
});

V Validator

Validate input data with automatic XSS prevention.

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

const schema = {
    // XSS sanitization is applied by default to all string fields.
    email: { required: true, email: true },
    password: { required: true, min: 6 },
    // You can explicitly disable it to allow HTML/React content
    html_content: { required: true, xss: false }
};

const validate = new Validator(schema, 'en');
// The second parameter allows returning localized errors based on client language.

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

Error Localization (API)

The validator automatically detects the language for error messages in this order: Body, Query String, Cookies, or the Accept-Language header.

fetch('/api/register', {
    method: 'POST',
    headers: { 
        'Content-Type': 'application/json',
        'Accept-Language': 'en' // Validator will return errors in English
    },
    body: JSON.stringify(data)
});

// Useful for quick tests or direct links
fetch('/api/register?lang=en', { 
    method: 'POST',
    body: JSON.stringify(data)
});

fetch('/api/register', {
    method: 'POST',
    body: JSON.stringify({
        ...data,
        lang: 'pt' // Highest priority over others
    })
});

H Helmet (Security)

Helmet is not applied globally by default. Apply it per-router where needed using App.helmet().

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

// Apply helmet to a specific router
const webRouter = new Router("/web");
webRouter.use(App.helmet()); // Helmet with defaults
webRouter.use(App.helmet({ contentSecurityPolicy: false })); // Custom options

// Or enable globally in App constructor (not recommended)
new App({ helmet: true });

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

S SPA Navigation (SPAProvider)

The framework includes an SPAProvider that bridges React Router navigation with backend SEO data. On every <Link> navigation, it fetches meta/props from the backend and updates document.title + meta tags automatically.

Setup in App.jsx

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

// Wrap routes with SPAProvider
<SPAProvider languages={["en", "es"]} defaultLanguage="en">
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="/about" element={<About />} />
    {/* Language-prefixed routes are auto-generated */}
    <Route path="/en" element={<Home />} />
    <Route path="/es" element={<Home />} />
    <Route path="/en/about" element={<About />} />
    <Route path="/es/about" element={<About />} />
  </Routes>
</SPAProvider>

Language Switching with navigateToLang

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

                            
Navigation Components (Recommended)
                            

                                The framework provides components that encapsulate localization logic for a cleaner syntax.
                            

                            
1. <Link /> Component
                            
Replaces react-router-dom's Link to automatically persist the current language.
                            
import Link from "../blue-bird/components/Link";

// Automatically prepends /es/ or /en/ based on the current session
<Link to="/about">About Us</Link>

                            
2. <LanguageButton /> Component
                            
Encapsulates the navigateToLang logic.
                            
import LanguageButton from "../blue-bird/components/LanguageButton";

<LanguageButton lang="es" variant="outline">Spanish</LanguageButton>
<LanguageButton lang="en" variant="outline">English</LanguageButton>

                            
Monolingual Support
                            

                                If your application only uses one language, simply leave the LANGUAGES
                                array empty in App.jsx. The framework will automatically disable all prefix
                                logic.
                            
                            
// App.jsx
const LANGUAGES = []; // Monolingual application
const DEFAULT_LANGUAGE = "en";

                            

                                
🔄 How does it work?
                                

                                    
Initial load: Express serves full HTML with correct SEO meta
                                        tags.
                                    
Client navigation: When clicking a <Link>,
                                        SPAProvider does fetch(path?source=frontend).
                                    
Backend responds JSON:
                                        {meta, props, component, lang} instead of HTML.
                                    
                                    
React updates: document.title, meta tags and localStorage
                                        language.