High-Performance
Express Framework.

1 Installation & Setup

Get your project up and running with Blue Bird in three simple steps

1. Installation

Install the framework package in your project directory

npm install @seip/blue-bird

2. Initialize Project

Run the initialization tool to generate the default application directory structure

npx blue-bird

This will generate files such as .env, backend/, frontend/, and other basic configurations.

3. Package Configuration

Ensure your package.json is set to use ES Modules by adding "type": "module"

{
  "type": "module"
}

2 Configuration (.env)

Settings are structured inside the `.env` configuration file. Standard variables configure ports, debugging levels, and Docker databases.

# Server and Application Configuration
DEBUG=true
PORT=3000
HOST="localhost"
APP_URL="http://localhost"
STATIC_PATH="frontend/public"
VERSION="1.0.0"
BLUEBIRD_PROJECT_NAME="bluebird"

#Docker /Swagger config
TITLE="Blue-Bird"
DESCRIPTION="Description project"

# HTML Meta / SEO Configuration
TITLE_META="Blue Bird"
DESCRIPTION_META="Example description meta"
KEYWORDS_META="Example keywords meta"
AUTHOR_META="Blue Bird"
LANGMETA="en"

# Security Configuration
JWT_SECRET="JWT_SECRET"

# Database Configuration (Used only for local development outside Docker)
# SQLite (Default)
DATABASE_URL="file:./dev.db"

# MySQL (Uncomment to use MySQL locally or DEV)
# DATABASE_URL="mysql://root:root@localhost:3306/blue_bird"

# PostgreSQL (Uncomment to use PostgreSQL locally or DEV)
# DATABASE_URL="postgresql://root:root@localhost:5432/blue_bird?schema=public"

# Database / Docker Configuration
DB_NAME="blue_bird"
DB_USER="root"
DB_PASSWORD="root"
DB_PORT=3306

3 Application Class (App)

Initializes the framework server, setting up default parsers, static routes, secure CORS policies, cookies, and route handlers.

import App from "@seip/blue-bird/core/app.js";
import routerFrontend from "./routes/frontend.js";
import routerApi from "./routes/api.js";

const app = new App({
  port: 3000,
  routes: [routerFrontend, routerApi],
  cors: { origin: "http://localhost:3000" },
  rateLimit: { windowMs: 15 * 60 * 1000, max: 100 }
});

app.run();

4 Routing & SEO

Do not use native Express routers. Always use Blue Bird's custom Router class wrapper. Set `{ seo: true }` to automatically populate the site maps.

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

// Instantiates a router with sitemap/robots automation enabled
const router = new Router("/", { seo: true });

router.get("/", (req, res) => {
  return Template.render(res, "index", {
    metaTags: {
      titleMeta: "Home Page",
      descriptionMeta: "Welcome to our application"
    }
  });
});

export default router;

5 Template Engine (Template)

Renders physical static .html files located in frontend/templates/. Replaces standard tags dynamically at speed:

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

router.get("/about", (req, res) => {
  return Template.render(res, "about", {
    cache: 60, // TTL in seconds (skipped when DEBUG=true)
    minify: true, // Compress code & strip comments in production
    metaTags: {
      titleMeta: "About Us",
      descriptionMeta: "Read more about our operations"
    }
  });
});

Programmatic Cache Invalidation

// Clear all cached pages in memory
Template.clearCache();

// Clear specific page cache
Template.clearCache("about");

6 Validation (Validator)

Checks request payload schemas automatically. It cleanses strings to prevent cross-site scripting (XSS) by default, and responds with a standard 400 Bad Request validation array on failures.

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

const userSchema = {
  email: { required: true, email: true },
  password: { required: true, min: 8 },
  bio: { required: false } // Cleansed from XSS scripts automatically
};

const validateUser = new Validator(userSchema, "en");

routerApi.post("/users", validateUser.middleware(), (req, res) => {
  res.json({ success: true });
});

7 Authentication (Auth)

Implements stateless JWT authentication. Payload structures are encrypted with military-grade AES-256-GCM algorithms and set inside secure, signed cookies or read from header strings.

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

// 1. Protecting routes (API returns 401, Web pages redirect to target path)
router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => {
  Template.render(res, "dashboard");
});

// 2. Logging in and setting session cookies
router.post("/api/login", async (req, res) => {
  const user = { id: 1, name: "John Doe", role: "admin" };
  await Auth.login(res, user);
  res.json({ success: true });
});

// 3. Logging out and clearing cookies
router.post("/api/logout", async (req, res) => {
  await Auth.logout(res);
  res.json({ success: true });
});

8 Cache Middleware

For database or heavy operations, cache the resulting JSON/HTML stream automatically using our routing middleware cache wrapper.

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

// Cache this API result for 60 seconds
router.get("/api/statistics", Cache.middleware(60), (req, res) => {
  res.json({ computedData: [10, 20, 30] });
});

9 Helmet Security

Protect HTTP response headers by applying Helmet rules. You can declare Helmet policies per-router. Custom configuration keeps X-Powered-By: Blue Bird headers active by default.

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

const apiRouter = new Router("/api");
apiRouter.use(App.helmet()); // Uses default policies

const secureWebRouter = new Router("/web");
secureWebRouter.use(App.helmet({ contentSecurityPolicy: false })); // Disables CSP restrictions

10 Hybrid SPA & Preact Integration

Blue Bird includes native single page application (SPA) support. The server intercepts SPA requests via header X-blueBird-SPA: true, returning a JSON payload containing the #blueBird-spa-content element body. This drastically reduces CPU, RAM, and network consumption by eliminating repetitive layout renders.

How it works under the hood: When the user clicks an internal link, the SPA client engine (bundled in blue-bird.js) intercepts the event, triggers a CSS/opacity fadeOut transition on the content container, and requests the page using a lightweight AJAX fetch with the header X-blueBird-SPA: true. The server intercepts this request, reads the page from the memory cache (using separate spa: prefixes), removes boilerplate headers (like strict security frames and CSP checks to minimize bandwidth), and returns only the page body metadata and content. Finally, the client injects the content, runs scripts, and triggers a smooth slide-up fadeIn transition.

Note: This client-side bundle and SPA behavior are entirely optional. If you prefer a traditional multi-page website (MPA) with standard browser reloads, you can simply remove the <script src="/js/blue-bird.js"></script> reference from your layout templates. The server will automatically fallback to serving full HTML views.

Additionally, if you want to keep the SPA navigation features but disable the Anime.js visual transitions globally, you can define window.enabledAnime = false; in a script block before loading the blue-bird.js script.

Below is the standard setup for layout templates (Home and About) and the typical JSON payload returned by the server when navigating dynamically.

1. Default Home Template (index.html)

<!DOCTYPE html>
<html lang="{{lang}}">
<head>
    <meta charset="UTF-8">
    <title>{{title}}</title>
    <script src="/js/tailwind.js"></script>
    <!-- Enable or disable SPA transitions globally (default: true) -->
    <script>window.enabledAnime = true;</script>
    <script src="/js/blue-bird.js"></script>
</head>
<body class="bg-slate-950 text-white">
    <header>
        <nav>
            <a href="/">Home</a>
            <a href="/about">About</a>
            <a href="/preact_example">Preact Example</a>
        </nav>
    </header>

    <!-- Content container -->
    <main id="blueBird-spa-content" class="max-w-7xl mx-auto px-4">
        <h1>Welcome to Home Page</h1>
        <p>This content is dynamic.</p>
    </main>
</body>
</html>

2. Default About Template (about.html)

<!DOCTYPE html>
<html lang="{{lang}}">
<head>
    <meta charset="UTF-8">
    <title>{{title}}</title>
    <script src="/js/tailwind.js"></script>
    <!-- Enable or disable SPA transitions globally (default: true) -->
    <script>window.enabledAnime = true;</script>
    <script src="/js/blue-bird.js"></script>
</head>
<body class="bg-slate-950 text-white">
    <header>
        <nav>
            <a href="/">Home</a>
            <a href="/about">About</a>
            <a href="/preact_example">Preact Example</a>
        </nav>
    </header>

    <!-- Content container -->
    <main id="blueBird-spa-content" class="max-w-4xl mx-auto px-4">
        <h1>About Us</h1>
        <p>This is the about page content.</p>
    </main>
</body>
</html>

3. Typical SPA JSON Response

When clicking on /about from the home page, the client requests the URL with the X-blueBird-SPA: true header. The server responds with this JSON payload instead of a full page reload:

{
    "meta": {
        "title": "About - Blue Bird",
        "description": "About Blue Bird Framework",
        "keywords": "about, blue bird, framework",
        "author": "Blue Bird"
    },
    "body": "<div class=\"space-y-12\"><h1>About Us</h1><p>This is the about page content.</p></div>",
    "css": []
}

You can integrate Preact directly without bundlers or compilation using Import Maps and the script loading engine from the blue-bird.js bundle:

<!-- Load in head section -->

<script src="/js/blue-bird.js"></script>

<!-- Inside main container #blueBird-spa-content -->
<main id="blueBird-spa-content">
    <div id="preact-app"></div>
    <script type="importmap">
{
    "imports": {
        "preact": "https://esm.sh/preact@10.19.2",
        "preact/hooks": "https://esm.sh/preact@10.19.2/hooks",
        "htm/preact": "https://esm.sh/htm@3.1.1/preact"
    }
}
</script>

    <script type="module">
        import { render } from 'preact';
        import { useState } from 'preact/hooks';
        import { html } from 'htm/preact';

        function App() {
            const [count, setCount] = useState(0);
            return html`
                <div class="p-6 bg-slate-900 rounded-2xl">
                    <h2 class="text-lg text-white">Preact Counter</h2>
                    <p class="text-2xl text-blue-400 font-extrabold">${count}</p>
                    <button onClick=${(e) => setCount(count + 1)}>Increment</button>
                </div>
            `;
        }

        render(html`<${App} />`, document.getElementById('preact-app'));
    </script>
</main>

11 Docker CLI Command Wrapper

Manage development containers and full-stack deployments directly using the built-in Docker CLI tool wrapper.

# Start Production Application Stack (App + MySQL)
npx blue-bird docker start prod

# Start MySQL Database Container Only (Ideal for Local Development)
npx blue-bird docker start mysql

# Stop All Running Project Containers
npx blue-bird docker stop

# Rebuild Node.js Application Production Container Image
npx blue-bird docker build

# Check Active Containers Status
npx blue-bird docker ps

# Tail Live Node.js Container Logs
npx blue-bird docker logs

# Run Interactive MySQL Client Shell Inside the Database Container
npx blue-bird docker db

# Remove Unused Volumes, Dangling Images, and Buildkit Cache
npx blue-bird docker prune

12 Production Setup (VPS / PM2)

Outside of Docker, you can run and manage production instances using PM2 process manager for maximum uptime and automated cluster scaling.

# Install PM2 globally
npm install pm2 -g

# Start the application in production mode
pm2 start backend/index.js --name "blue-bird-app" --node-args="--env-file=.env"

# Save the PM2 cluster layout to restore automatically on reboots
pm2 save

# Make PM2 restart automatically on system startup
pm2 startup