@seip/blue-bird 0.7.0 → 0.7.1

package/.env_example

@@ -3,18 +3,23 @@ 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
+# Docker / Swagger Config
 TITLE="Blue-Bird"
 DESCRIPTION="Description project"
 
-
 # Security Configuration
 JWT_SECRET="JWT_SECRET"
 
+# Redis Configuration
+REDIS_HOST="localhost"
+REDIS_PORT=6379
+REDIS_PASSWORD=""
+
+# PM2 Clustering Instances (integer or 'max')
+PM2_INSTANCES=1
+
 # Database Configuration (Used only for local development outside Docker)
 # SQLite (Default)
 DATABASE_URL="file:./dev.db"

package/AGENTS.md

@@ -131,7 +131,7 @@ router.post("/logout", async (req, res) => {
 
 ## 6. Performance Caching (Cache)
 
-If an Express route involves heavy processing or database queries, utilize the `Cache` middleware to cache the REST API JSON payload.
+If an Express route involves heavy processing or database queries, utilize the `Cache` middleware to cache the REST API JSON or HTML payload.
 
 ```javascript
 import Cache from "@seip/blue-bird/core/cache.js";
@@ -141,6 +141,8 @@ router.get("/stats", Cache.middleware(60), (req, res) => {
 });
 ```
 
+The Cache module integrates with Redis when `REDIS_HOST` is configured in the environment. If Redis is unavailable or fails, it transparently falls back to an in-memory cache system without interrupting requests.
+
 ## 7. Security (Helmet)
 
 Helmet is **not applied globally** by default. Apply it per-router where needed:
@@ -156,19 +158,28 @@ apiRouter.use(App.helmet());
 
 Blue Bird features a built-in Docker Compose CLI wrapper to deploy and manage containerized development databases and production stacks.
 
+Production deployments always use Docker for orchestration, running:
+- Nginx: Serves static files directly from `frontend/dist/client/` and blocks common scanner requests (`.env`, `.git`, etc.) with fallback to Express.
+- Node.js App: Managed via PM2 in cluster mode using `PM2_INSTANCES` configuration (defaults to `1`, can be set to `max`).
+- MySQL: Database service.
+- Redis: Memory caching and session store.
+
 ```bash
 # Manage containers using blue-bird CLI
-npx blue-bird docker start          # Starts production app + mysql database
+npx blue-bird docker start          # Starts production app stack (mysql, redis, app, nginx)
 npx blue-bird docker start mysql    # Starts MySQL container only (useful for local development)
+npx blue-bird docker start redis    # Starts Redis container only
+npx blue-bird docker start dbs      # Starts both database containers (MySQL + Redis)
 npx blue-bird docker stop           # Stops all running containers
 npx blue-bird docker build          # Builds/rebuilds application image
 npx blue-bird docker ps             # Shows status of active containers
 npx blue-bird docker logs           # Tails Node.js app container logs
+npx blue-bird docker pm2 [args]     # Runs PM2 commands inside the app container (e.g. status, monit)
 npx blue-bird docker mysql          # Runs interactive MySQL client terminal inside the container
 npx blue-bird docker prune          # Cleans unused volumes, dangling images, and BuildKit caches
 ```
 
-The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts.
+The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts. Alternatively, PM2 and other services can be run manually in standalone server environments.
 
 ## 9. AI Development Guidelines
 

package/README.md

@@ -62,8 +62,8 @@ project/
 │   │       ├── index.astro
 │   │       └── about.astro
 │   ├── public/              # Static assets mapped to root of Astro build
-│   │   └── js/
-│   │       └── tailwind.js  # Local Tailwind compiler
+│   │   └── css/
+│   │       └── app.css      # Css files
 │   └── astro.config.mjs     # Astro configuration file
 ├── docker/
 │   └── Dockerfile           # Optimized production build file
@@ -122,8 +122,8 @@ const app = new App({
     serverEntry: "./frontend/dist/server/entry.mjs", // Path to compiled Astro server entrypoint
     client: false, // Set to true to serve static files from client build
     clientDir: "./frontend/dist/client", // Path to Astro client static assets
-    base: "/" // Mount base path
-  }
+    base: "/", // Mount base path
+  },
 });
 ```
 
@@ -201,6 +201,8 @@ router.get("/stats", Cache.middleware(60), (req, res) => {
 });
 ```
 
+Integrates with Redis if `REDIS_HOST` is defined in the environment. Falls back to an in-memory cache automatically if Redis is not configured or not running.
+
 ---
 
 ### 6. Security Headers (`Helmet`)
@@ -228,12 +230,15 @@ npx blue-bird docker <command> [options]
 
 ### Supported Actions:
 
-- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + MySQL).
+- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + Nginx + MySQL + Redis).
 - **`npx blue-bird docker start mysql`**: Boots the MySQL container only (great for local HTTP development).
+- **`npx blue-bird docker start redis`**: Boots the Redis container only.
+- **`npx blue-bird docker start dbs`**: Boots both database containers (MySQL + Redis).
 - **`npx blue-bird docker stop`**: Stops all active containers.
 - **`npx blue-bird docker build [--no-cache]`**: Builds or updates the Node.js production image.
 - **`npx blue-bird docker ps`**: Lists running project containers and ports.
 - **`npx blue-bird docker logs [app|mysql]`**: Tails logs for the specified container.
+- **`npx blue-bird docker pm2 [args]`**: Runs PM2 commands inside the Node.js application container (e.g. `status`, `monit`, `reload all`).
 - **`npx blue-bird docker db`**: Connects into the container's interactive MySQL shell using credentials from `.env`.
 - **`npx blue-bird docker prune`**: Safely clears orphaned volumes, dangling build caches, and images.
 
@@ -243,9 +248,16 @@ npx blue-bird docker <command> [options]
 
 You can deploy Blue Bird applications to production using two main workflows:
 
-### A. Docker Container Stack (Recommended)
+### A. Docker Container Stack (Highly Recommended)
+
+Using the built-in Docker stack is the recommended deployment method because it sets up a complete, hardened production environment automatically:
+- **Nginx Reverse Proxy:** Captures traffic on port 3000 (or custom PORT), serves Astro client-side assets directly from the filesystem to offload the Node.js server, and proxies the rest to Express.
+- **PM2 Clustering:** Launches Node.js in cluster mode inside the container, utilizing all available CPU cores based on `PM2_INSTANCES` configuration (defaulting to 1).
+- **Security Mitigation:** Nginx blocks common malicious scanners (e.g. `/.env`, `/.git`, `/wp-admin`) instantly using a 444 status code and implements a `10r/s` request rate-limit.
+- **Services Stack:** MySQL and Redis are configured in the same bridge network automatically.
 
-1. Configure `.env` with production keys,DEBUG=false and your custom `TITLE`.
+To deploy via Docker:
+1. Configure `.env` with production keys, `DEBUG=false` and your custom `TITLE`.
 2. Build the production image:
    ```bash
    npx blue-bird docker build
@@ -255,9 +267,9 @@ You can deploy Blue Bird applications to production using two main workflows:
    npx blue-bird docker start prod
    ```
 
-### B. Standard PM2 / Node.js Runtime
+### B. Standard Standalone PM2 / Node.js Runtime
 
-To deploy in a standard Linux environment using PM2 process manager:
+If you choose to run outside of Docker, you must set up the reverse proxy and databases manually. To deploy in a standard Linux environment using PM2:
 
 1. Install PM2 globally:
    ```bash
@@ -265,7 +277,7 @@ To deploy in a standard Linux environment using PM2 process manager:
    ```
 2. Start the application under PM2:
    ```bash
-   pm2 start index.js --name "bluebird-app"
+   pm2 start index.js --name "bluebird-app" --node-args="--env-file=.env" -i max
    ```
 3. Monitor status:
    ```bash

package/core/cache.js

@@ -1,38 +1,101 @@
+import fs from "node:fs";
+
 const CACHE = {};
 
+let redisClient = null;
+let isRedisConnected = false;
+const redisHost = process.env.REDIS_HOST ?? false;
+const redisPort = process.env.REDIS_PORT ?? 6379;
+const redisPassword = process.env.REDIS_PASSWORD || "";
+const redisUrl = redisPassword
+  ? `redis://:${redisPassword}@${redisHost}:${redisPort}`
+  : `redis://${redisHost}:${redisPort}`;
+
+/**
+ * Initializes the Redis client connection if REDIS_HOST env is set.
+ * @returns {Promise<void>}
+ */
+async function initRedis() {
+  if (redisClient) return;
+  if (!redisHost) return;
+
+  try {
+    const { createClient } = await import("redis");
+    let host = redisHost;
+    if (host === "localhost" && fs.existsSync("/.dockerenv")) {
+      host = "redis";
+    }
+    const url = redisUrl;
+
+    redisClient = createClient({ url });
+    redisClient.on("error", () => {
+      isRedisConnected = false;
+    });
+    await redisClient.connect();
+    isRedisConnected = true;
+  } catch (err) {
+    redisClient = null;
+    isRedisConnected = false;
+  }
+}
+
+initRedis().catch(() => {});
+
 setInterval(() => {
-    const now = Date.now();
-    for (const key in CACHE) {
-        if (CACHE[key].expiry <= now) {
-            delete CACHE[key];
-        }
+  const now = Date.now();
+  for (const key in CACHE) {
+    if (CACHE[key].expiry <= now) {
+      delete CACHE[key];
     }
+  }
 }, 300000).unref();
+
 /**
- * Simple in-memory Cache class to provide middleware for Express routes.
- * Caches JSON responses based on the request URL.
+ * High-performance Caching class supporting both local memory and Redis backends.
  */
 class Cache {
   /**
-   * Middleware to cache responses.
-   * @param {number} [seconds=60] - Number of seconds to cache the response.
-   * @returns {Function} Express middleware function.
-   * @example
-   * router.get("/stats", Cache.middleware(120), (req, res) => {
-   *     res.json({ ok: true });
-   * });
+   * Express middleware to cache route JSON and HTML responses.
+   * @param {number} [seconds=60] - Expiry time in seconds.
+   * @returns {Function} Express middleware.
    */
   static middleware(seconds = 60) {
-    return (req, res, next) => {
+    return async (req, res, next) => {
       const key = req.originalUrl;
 
-      if (CACHE[key] && CACHE[key].expiry > Date.now()) {
-        const cached = CACHE[key];
-        if (cached.type === "json") {
-          return res.json(cached.data);
-        } else {
-          res.type("text/html");
-          return res.send(cached.data);
+      if (redisHost && !redisClient) {
+        await initRedis().catch(() => {});
+      }
+
+      if (isRedisConnected && redisClient) {
+        try {
+          const cachedData = await redisClient.get(key);
+          if (cachedData) {
+            const cached = JSON.parse(cachedData);
+            if (cached.type === "json") {
+              return res.json(cached.data);
+            } else {
+              res.type("text/html");
+              res.set("X-Blue-Bird-Cache", "HIT");
+              return res.send(cached.data);
+            }
+          }
+        } catch (err) {
+          isRedisConnected = false;
+        }
+      }
+
+      if (!isRedisConnected || !redisClient) {
+        if (CACHE[key] && CACHE[key].expiry > Date.now()) {
+          const cached = CACHE[key];
+          if (cached.type === "json") {
+            res.set("X-Blue-Bird-Cache", "HIT");
+            return res.json(cached.data);
+          } else {
+            res.type("text/html");
+            res.set("X-Blue-Bird-Cache", "HIT");
+            return res.send(cached.data);
+          }
         }
       }
 
@@ -40,33 +103,58 @@ class Cache {
       const originalSend = res.send.bind(res);
       let cachedInRequest = false;
 
-      res.json = (body) => {
+      res.json = async (body) => {
         if (!cachedInRequest) {
-          CACHE[key] = {
+          cachedInRequest = true;
+          const cacheObject = {
             type: "json",
             data: body,
             expiry: Date.now() + seconds * 1000,
           };
-          cachedInRequest = true;
+          if (isRedisConnected && redisClient) {
+            try {
+              await redisClient.set(key, JSON.stringify(cacheObject), {
+                EX: seconds,
+              });
+            } catch (err) {
+              CACHE[key] = cacheObject;
+            }
+          } else {
+            CACHE[key] = cacheObject;
+          }
         }
+        res.set("X-Blue-Bird-Cache", "MISS");
         return originalJson(body);
       };
 
-      res.send = (body) => {
+      res.send = async (body) => {
         if (!cachedInRequest && typeof body === "string") {
-          CACHE[key] = {
+          cachedInRequest = true;
+          const cacheObject = {
             type: "html",
             data: body,
             expiry: Date.now() + seconds * 1000,
           };
-          cachedInRequest = true;
+          if (isRedisConnected && redisClient) {
+            try {
+              await redisClient.set(key, JSON.stringify(cacheObject), {
+                EX: seconds,
+              });
+            } catch (err) {
+              CACHE[key] = cacheObject;
+            }
+          } else {
+            CACHE[key] = cacheObject;
+          }
         }
+        res.set("X-Blue-Bird-Cache", "MISS");
         return originalSend(body);
       };
 
+      res.set("X-Blue-Bird-Cache", "MISS");
       next();
     };
   }
 }
 
-export default Cache;
+export default Cache;

package/core/cli/docker.js

@@ -58,27 +58,43 @@ async function startCommand(service) {
   checkComposeFile();
 
   if (service === "mysql" || service === "--mysql" || service === "dev") {
-    console.log(chalk.cyan("Starting MySQL container (dev mode)..."));
+    console.log(chalk.cyan("Starting MySQL container..."));
     const code = await runCmd("docker", ["compose", "up", "-d", "mysql"]);
     if (code === 0) {
-      console.log(chalk.green("MySQL started. Run your app locally with: npm run dev"));
-      console.log(chalk.blue("To also run the app in Docker (production), use: npx blue-bird docker start prod"));
+      console.log(chalk.green("MySQL started."));
     } else {
       console.error(chalk.red("Error starting MySQL."));
       process.exit(1);
     }
+  } else if (service === "redis" || service === "--redis") {
+    console.log(chalk.cyan("Starting Redis container..."));
+    const code = await runCmd("docker", ["compose", "up", "-d", "redis"]);
+    if (code === 0) {
+      console.log(chalk.green("Redis started."));
+    } else {
+      console.error(chalk.red("Error starting Redis."));
+      process.exit(1);
+    }
+  } else if (service === "dbs" || service === "databases") {
+    console.log(chalk.cyan("Starting Database containers (MySQL + Redis)..."));
+    const code = await runCmd("docker", ["compose", "up", "-d", "mysql", "redis"]);
+    if (code === 0) {
+      console.log(chalk.green("Database containers started."));
+    } else {
+      console.error(chalk.red("Error starting databases."));
+      process.exit(1);
+    }
   } else if (service === "prod" || service === "app" || service === "--app" || !service) {
-    console.log(chalk.cyan("Starting production stack (MySQL + Node.js app)..."));
+    console.log(chalk.cyan("Starting production stack (MySQL + Redis + App + Nginx)..."));
     const code = await runCmd("docker", ["compose", "--profile", "prod", "up", "-d"]);
     if (code === 0) {
       console.log(chalk.green("Production stack started."));
-      console.log(chalk.blue("View logs with: npx blue-bird docker logs"));
     } else {
       console.error(chalk.red("Error starting production stack."));
       process.exit(1);
     }
   } else {
-    console.error(chalk.red(`Unknown service '${service}'. Use: mysql (or --mysql), prod (or --app), or no arguments for both.`));
+    console.error(chalk.red(`Unknown service '${service}'. Use: mysql, redis, dbs, prod.`));
     process.exit(1);
   }
 }
@@ -99,13 +115,18 @@ async function stopCommand(service) {
     await runCmd("docker", ["compose", "stop", "mysql"]);
     await runCmd("docker", ["compose", "rm", "-f", "mysql"]);
     console.log(chalk.green("MySQL stopped."));
+  } else if (service === "redis" || service === "--redis") {
+    console.log(chalk.cyan("Stopping Redis..."));
+    await runCmd("docker", ["compose", "stop", "redis"]);
+    await runCmd("docker", ["compose", "rm", "-f", "redis"]);
+    console.log(chalk.green("Redis stopped."));
   } else if (service === "app" || service === "--app") {
     console.log(chalk.cyan("Stopping Node.js app container..."));
     await runCmd("docker", ["compose", "--profile", "prod", "stop", "app"]);
     await runCmd("docker", ["compose", "--profile", "prod", "rm", "-f", "app"]);
     console.log(chalk.green("App container stopped."));
   } else {
-    console.error(chalk.red(`Unknown service '${service}'. Use: all (default), mysql, app.`));
+    console.error(chalk.red(`Unknown service '${service}'. Use: all, mysql, redis, app.`));
     process.exit(1);
   }
 }
@@ -235,6 +256,21 @@ async function pruneCommand(forceOpt, allOpt) {
   await runCmd("docker", ["system", "df"]);
 }
 
+/**
+ * Executes PM2 commands inside the Node.js application container.
+ * @param {string[]} pm2Args - Arguments to pass to PM2.
+ */
+async function pm2Command(pm2Args = []) {
+  checkComposeFile();
+  const subCommand = pm2Args[0] || "status";
+  const cmdArgs = ["compose", "exec", "app", "pm2", subCommand, ...pm2Args.slice(1)];
+  const code = await runCmd("docker", cmdArgs);
+  if (code !== 0) {
+    console.error(chalk.red("Error running PM2 command. Make sure the production stack is started."));
+    process.exit(1);
+  }
+}
+
 /**
  * Entry point for Blue Bird CLI Docker subcommands.
  */
@@ -286,6 +322,9 @@ async function main() {
     case "logs":
       await logsCommand(args[1], args[2]);
       break;
+    case "pm2":
+      await pm2Command(args.slice(1));
+      break;
     case "mysql":
     case "db": {
       let user, password, db, root = false;
@@ -312,7 +351,7 @@ async function main() {
     }
     default:
       console.log(chalk.yellow(`Unknown docker command: ${command}`));
-      console.log("Available commands: start, stop, build, ps, logs, mysql/db, df/disk, prune/clean");
+      console.log("Available commands: start, stop, build, ps, logs, pm2, mysql/db, df/disk, prune/clean");
   }
 }
 

package/docker/Dockerfile

@@ -1,25 +1,16 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# Blue Bird Framework — Production Dockerfile
-# Node.js 24-alpine for lightweight, production-ready environment
-# ─────────────────────────────────────────────────────────────────────────────
 FROM node:24.7.0-alpine3.21
 
-# Set environment variables
 ENV NODE_ENV=production
 
 WORKDIR /app
 
-# Copy package files first (layer cache optimization)
 COPY package*.json ./
 
-# Install production dependencies
-RUN npm ci --omit=dev
+RUN npm ci --omit=dev && npm install -g pm2
 
-# Copy project source
 COPY . .
 
-# Expose the application port
 EXPOSE 3000
 
-# Start the application
-CMD ["npm", "start"]
+CMD ["sh", "-c", "pm2-runtime start index.js -i ${PM2_INSTANCES:-1}"]
+

package/docker/nginx.conf

@@ -0,0 +1,83 @@
+user  nginx;
+worker_processes  auto;
+
+error_log  /var/log/nginx/error.log notice;
+pid        /var/run/nginx.pid;
+
+events {
+    worker_connections  1024;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+
+    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
+                      '$status $body_bytes_sent "$http_referer" '
+                      '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log  /var/log/nginx/access.log  main;
+
+    sendfile        on;
+    tcp_nopush     on;
+    tcp_nodelay    on;
+    keepalive_timeout  65;
+    types_hash_max_size 2048;
+
+    gzip on;
+    gzip_disable "msie6";
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_buffers 16 8k;
+    gzip_http_version 1.1;
+    gzip_min_length 256;
+    gzip_types
+        text/plain
+        text/css
+        application/json
+        application/javascript
+        application/x-javascript
+        text/xml
+        application/xml
+        application/xml+rss
+        text/javascript
+        image/svg+xml;
+
+    limit_req_zone $binary_remote_addr zone=bluebird_limit:10m rate=10r/s;
+
+    server {
+        listen 80;
+        server_name localhost;
+        root /app/frontend/dist/client;
+
+        resolver 127.0.0.11 valid=5s;
+
+        location ~* /(\.env|\.git|wp-content|wp-admin|xmlrpc\.php) {
+            return 444;
+        }
+
+        location / {
+            try_files $uri @node_app;
+        }
+
+        location /_astro/ {
+            expires max;
+            add_header Cache-Control "public, max-age=31536000, immutable";
+            try_files $uri =404;
+        }
+
+        location @node_app {
+            limit_req zone=bluebird_limit burst=20 nodelay;
+
+            set $upstream_target http://app:3000;
+            proxy_pass $upstream_target;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+}

package/docker-compose.yml

@@ -1,28 +1,12 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# Blue Bird Framework — Docker Compose
-#
-# DEVELOPMENT / DATABASE ONLY:
-#   npx blue-bird docker start mysql   → Only MySQL container
-#
-# PRODUCTION:
-#   npx blue-bird docker start prod    → MySQL + Node.js app container
-#   npx blue-bird docker stop          → Stop all containers
-#
-# Multi-project VPS support:
-#   Each project uses TITLE (or sanitised TITLE) to name
-#   containers and networks uniquely.
-# ─────────────────────────────────────────────────────────────────────────────
-
 services:
-  # ── Node.js App (Production only) ─────────────────────────────────────────
   app:
     build:
       context: .
       dockerfile: docker/Dockerfile
     container_name: ${TITLE:-bluebird}-app
     restart: unless-stopped
-    ports:
-      - "${PORT:-3000}:${PORT:-3000}"
+    expose:
+      - "3000"
     volumes:
       - .:/app
       - /app/node_modules
@@ -32,15 +16,36 @@ services:
       - NODE_ENV=production
       - DEBUG=false
       - DATABASE_URL=mysql://root:${DB_PASSWORD:-root}@mysql:3306/${DB_NAME:-blue_bird}
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - PORT=3000
     depends_on:
       mysql:
         condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - bluebird_net
+    profiles:
+      - prod
+
+  nginx:
+    image: nginx:1.27-alpine
+    container_name: ${TITLE:-bluebird}-nginx
+    restart: unless-stopped
+    ports:
+      - "${PORT:-3000}:80"
+    volumes:
+      - .:/app:ro
+      - ./docker/nginx.conf:/etc/nginx/nginx.conf:ro
+    depends_on:
+      app:
+        condition: service_started
     networks:
       - bluebird_net
     profiles:
       - prod
 
-  # ── MySQL Database ─────────────────────────────────────────────────────────
   mysql:
     image: mysql:8.0
     container_name: ${TITLE:-bluebird}-mysql
@@ -61,10 +66,28 @@ services:
     networks:
       - bluebird_net
 
+  redis:
+    image: redis:7-alpine
+    container_name: ${TITLE:-bluebird}-redis
+    restart: unless-stopped
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    networks:
+      - bluebird_net
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
 volumes:
   mysql_data:
+  redis_data:
 
 networks:
   bluebird_net:
     name: ${TITLE:-bluebird}_network
     driver: bridge
+

package/frontend/src/http/api.js

@@ -15,5 +15,10 @@ export function apiUrl(path = "", requestUrl) {
   if (!requestUrl) {
     throw new Error("apiUrl: requestUrl is required in production (pass Astro.url)");
   }
-  return new URL(`/${path}`, requestUrl).href;
+  const url = new URL(`/${path}`, requestUrl);
+  if (url.hostname === "localhost") {
+    url.hostname = "127.0.0.1";
+    url.port = port;
+  }
+  return url.href;
 }

package/frontend/src/pages/index.astro

@@ -4,11 +4,17 @@ import { apiUrl } from "../http/api";
 
 let apiData = null;
 try {
-  const response = await fetch(apiUrl("api/", Astro.url));
+  const targetUrl = apiUrl("api/", Astro.url);
+  console.log("[index.astro] request URL:", Astro.url.href);
+  console.log("[index.astro] target URL:", targetUrl);
+  const response = await fetch(targetUrl);
   apiData = await response.json();
   console.log("[index.astro] /api/ response:", apiData);
 } catch (err) {
   console.error("[index.astro] fetch error:", err.message);
+  if (err.cause) {
+    console.error("[index.astro] fetch error cause:", err.cause);
+  }
 }
 ---
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@seip/blue-bird",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Express opinionated framework with HTML rendering, API architecture, built-in JWT auth, validation, caching, and SEO",
   "type": "module",
+  "exports": {
+    "./*": "./*"
+  },
   "bin": {
     "blue-bird": "core/cli/init.js"
   },
@@ -62,6 +65,7 @@
     "helmet": "^8.1.0",
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.0.2",
+    "redis": "^4.7.0",
     "xss": "^1.0.15"
   }
 }