@seip/blue-bird 0.6.4 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env_example +0 -6
- package/AGENTS.md +41 -156
- package/README.md +46 -130
- package/backend/routes/api.js +21 -17
- package/core/app.js +86 -81
- package/core/cli/init.js +120 -11
- package/core/logger.js +77 -78
- package/core/router.js +2 -6
- package/frontend/astro.config.mjs +35 -0
- package/frontend/public/css/app.css +319 -0
- package/frontend/public/favicon.ico +0 -0
- package/frontend/src/http/api.js +19 -0
- package/frontend/src/layouts/Layout.astro +20 -0
- package/frontend/src/pages/about.astro +54 -0
- package/frontend/src/pages/index.astro +104 -0
- package/{backend/index.js → index.js} +11 -4
- package/package.json +12 -4
- package/backend/routes/frontend.js +0 -39
- package/core/seo.js +0 -113
- package/core/template.js +0 -319
- package/frontend/public/js/blue-bird.js +0 -1465
- package/frontend/public/js/tailwind.js +0 -8
- package/frontend/templates/about.html +0 -105
- package/frontend/templates/index.html +0 -146
- package/frontend/templates/preact_example.html +0 -80
package/.env_example
CHANGED
|
@@ -11,12 +11,6 @@ BLUEBIRD_PROJECT_NAME="bluebird"
|
|
|
11
11
|
TITLE="Blue-Bird"
|
|
12
12
|
DESCRIPTION="Description project"
|
|
13
13
|
|
|
14
|
-
# HTML Meta / SEO Configuration
|
|
15
|
-
TITLE_META="Blue Bird"
|
|
16
|
-
DESCRIPTION_META="Example description meta"
|
|
17
|
-
KEYWORDS_META="Example keywords meta"
|
|
18
|
-
AUTHOR_META="Blue Bird"
|
|
19
|
-
LANGMETA="en"
|
|
20
14
|
|
|
21
15
|
# Security Configuration
|
|
22
16
|
JWT_SECRET="JWT_SECRET"
|
package/AGENTS.md
CHANGED
|
@@ -4,11 +4,12 @@ This document serves as the primary manual for any AI Agent interacting with the
|
|
|
4
4
|
|
|
5
5
|
## 1. Core Architecture
|
|
6
6
|
|
|
7
|
-
Blue Bird is a framework built on **Express** for backend and **
|
|
7
|
+
Blue Bird is a framework built on **Express** for backend and **Astro** (v7.0) for frontend rendering. It saves developers from repetitive configuration, validation, security, JWT authentication, and database environment configuration out of the box.
|
|
8
8
|
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
11
|
-
- **
|
|
9
|
+
- **Entrypoint (`index.js`)**: Initializes the server using `App` from `core/app.js` and registers the routes.
|
|
10
|
+
- **Backend (`backend/`)**: Application routes and logic (e.g. `backend/routes/`).
|
|
11
|
+
- **Frontend (`frontend/`)**: Astro project files. Source pages go in `frontend/src/pages/` and static/public assets go in `frontend/public/`.
|
|
12
|
+
- **Core (`core/`)**: The framework core. Contains wrapper classes such as `Router`, `Validator`, `Auth`, `Cache`, etc. **DO NOT MODIFY** the core unless explicitly requested, as it could break other apps.
|
|
12
13
|
|
|
13
14
|
## 2. Routing (Router)
|
|
14
15
|
|
|
@@ -26,121 +27,55 @@ routerApi.get("/users", (req, res) => {
|
|
|
26
27
|
export default routerApi;
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
|
|
30
|
-
Blue Bird renders HTML templates directly using its `Template` class.
|
|
30
|
+
Astro routes (pages) are handled automatically by Astro's file-based routing inside the `frontend/src/pages/` directory.
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
import Router from "@seip/blue-bird/core/router.js";
|
|
34
|
-
import Template from "@seip/blue-bird/core/template.js";
|
|
32
|
+
## 3. Astro Node Middleware Integration
|
|
35
33
|
|
|
36
|
-
|
|
34
|
+
Blue Bird integrates Astro as a middleware handler. This is configured in the main `App` constructor:
|
|
37
35
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
titleMeta: "Home",
|
|
42
|
-
descriptionMeta: "Welcome to my site",
|
|
43
|
-
},
|
|
44
|
-
});
|
|
45
|
-
});
|
|
36
|
+
```javascript
|
|
37
|
+
import App from "@seip/blue-bird/core/app.js";
|
|
38
|
+
import routerApi from "./backend/routes/api.js";
|
|
46
39
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
titleMeta: "About Us",
|
|
51
|
-
descriptionMeta: "Learn more about us",
|
|
52
|
-
},
|
|
53
|
-
});
|
|
40
|
+
const app = new App({
|
|
41
|
+
routes: [routerApi],
|
|
42
|
+
astro: true, // Enables Astro SSR/SSG middleware mode
|
|
54
43
|
});
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
**SEO (Sitemap & Robots.txt):**
|
|
58
|
-
When a `Router` is created with `{ seo: true }`, all `GET` routes registered on it are automatically included in the generated `/sitemap.xml` and `/robots.txt`.
|
|
59
44
|
|
|
60
|
-
|
|
61
|
-
const router = new Router("/", { seo: true });
|
|
45
|
+
app.run();
|
|
62
46
|
```
|
|
63
47
|
|
|
64
|
-
|
|
65
|
-
- **Robots.txt:** Auto-served pointing to the generated sitemap.
|
|
66
|
-
|
|
67
|
-
## 3. HTML View Rendering (Template)
|
|
68
|
-
|
|
69
|
-
The `Template` class renders HTML files directly from the `frontend/` directory. It resolves placeholders in the HTML files (using double curly braces `{{variable}}`) populated by the options, metaTags, and application configurations.
|
|
48
|
+
### Config Options
|
|
70
49
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
The renderer automatically replaces the following standard tags:
|
|
74
|
-
|
|
75
|
-
- `{{lang}}` or `{{langHtml}}`: Active language code (defaults to `"en"`).
|
|
76
|
-
- `{{title}}` or `{{titleMeta}}`: Page title.
|
|
77
|
-
- `{{canonicalUrl}}`: Canonical page link.
|
|
78
|
-
- `{{description}}` or `{{descriptionMeta}}`: Meta description text.
|
|
79
|
-
- `{{keywords}}` or `{{keywordsMeta}}`: Meta keywords.
|
|
80
|
-
- `{{author}}` or `{{authorMeta}}`: Meta author.
|
|
81
|
-
- `{{classBody}}`: CSS class for the body wrapper.
|
|
82
|
-
- `{{headOptions}}`: SEO Open Graph, Twitter cards, and hot reload scripts.
|
|
83
|
-
- `{{linkStyles}}`: Dynamic stylesheet `<link>` tags.
|
|
84
|
-
- `{{scriptsHead}}`: Script tags loaded in the `<head>`.
|
|
85
|
-
- `{{scriptsBody}}`: Script tags loaded in the `<body>`.
|
|
86
|
-
|
|
87
|
-
Additionally, any top-level key inside `options` or `metaTags` (e.g. `{{username}}`) will be dynamically replaced in the HTML template string.
|
|
88
|
-
|
|
89
|
-
### Basic Rendering
|
|
50
|
+
Astro middleware options can be customized by passing a configuration object:
|
|
90
51
|
|
|
91
52
|
```javascript
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
authorMeta: "Blue Bird",
|
|
101
|
-
},
|
|
102
|
-
});
|
|
53
|
+
const app = new App({
|
|
54
|
+
astro: {
|
|
55
|
+
server: true, // Enables Astro SSR handler middleware
|
|
56
|
+
serverEntry: "./frontend/dist/server/entry.mjs", // Path to server build entrypoint
|
|
57
|
+
client: false, // Set to true to serve Astro client static assets
|
|
58
|
+
clientDir: "./frontend/dist/client", // Path to client static build folder
|
|
59
|
+
base: "/" // Base route mount path
|
|
60
|
+
}
|
|
103
61
|
});
|
|
104
62
|
```
|
|
105
63
|
|
|
106
|
-
|
|
64
|
+
To use Astro as Express middleware, ensure your Astro configuration uses the node adapter in middleware mode:
|
|
107
65
|
|
|
108
66
|
```javascript
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
67
|
+
// frontend/astro.config.mjs
|
|
68
|
+
import { defineConfig } from 'astro/config';
|
|
69
|
+
import node from '@astrojs/node';
|
|
70
|
+
|
|
71
|
+
export default defineConfig({
|
|
72
|
+
output: 'server',
|
|
73
|
+
adapter: node({
|
|
74
|
+
mode: 'middleware',
|
|
75
|
+
}),
|
|
114
76
|
});
|
|
115
77
|
```
|
|
116
78
|
|
|
117
|
-
**Cache behavior:**
|
|
118
|
-
|
|
119
|
-
- `DEBUG=true` → Cache is always bypassed (reads from disk every time).
|
|
120
|
-
- `DEBUG=false` + `cache` > 0 → Output HTML is cached in memory for the specified duration in seconds.
|
|
121
|
-
- `DEBUG=false` + `cache: false` (or 0) → Bypasses caching entirely.
|
|
122
|
-
|
|
123
|
-
### Cache Management
|
|
124
|
-
|
|
125
|
-
```javascript
|
|
126
|
-
import Template from "@seip/blue-bird/core/template.js";
|
|
127
|
-
|
|
128
|
-
Template.clearCache();
|
|
129
|
-
Template.clearCache("home");
|
|
130
|
-
Template.getCacheKeys();
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
### Hot Reload (Development)
|
|
134
|
-
|
|
135
|
-
When `DEBUG=true` in `.env`, Blue Bird automatically:
|
|
136
|
-
|
|
137
|
-
1. Injects a hot-reload script into every rendered template.
|
|
138
|
-
2. Watches `frontend/` for `.html`, `.css`, and `.js` file changes.
|
|
139
|
-
3. Notifies connected browsers via Server-Sent Events (SSE) to reload.
|
|
140
|
-
4. Clears the template cache on file changes.
|
|
141
|
-
|
|
142
|
-
No configuration needed — it works automatically in debug mode.
|
|
143
|
-
|
|
144
79
|
## 4. Data Validation (Validator)
|
|
145
80
|
|
|
146
81
|
Incoming request data must be validated using `core/validate.js`, which automatically returns HTTP 400 JSON responses on error.
|
|
@@ -154,10 +89,6 @@ const userSchema = {
|
|
|
154
89
|
bio: { required: false },
|
|
155
90
|
};
|
|
156
91
|
|
|
157
|
-
const postSchema = {
|
|
158
|
-
contentHtml: { required: true, xss: false },
|
|
159
|
-
};
|
|
160
|
-
|
|
161
92
|
const validateUser = new Validator(userSchema, "en");
|
|
162
93
|
|
|
163
94
|
routerApi.post("/users", validateUser.middleware(), (req, res) => {
|
|
@@ -179,21 +110,6 @@ import Auth from "@seip/blue-bird/core/auth.js";
|
|
|
179
110
|
router.get("/profile", Auth.protect(), (req, res) => {
|
|
180
111
|
res.json({ user: req.user });
|
|
181
112
|
});
|
|
182
|
-
|
|
183
|
-
router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => {
|
|
184
|
-
Template.render(res, "dashboard");
|
|
185
|
-
});
|
|
186
|
-
|
|
187
|
-
router.get(
|
|
188
|
-
"/admin",
|
|
189
|
-
Auth.protect({
|
|
190
|
-
cookieKey: "admin_session",
|
|
191
|
-
key: "admin",
|
|
192
|
-
}),
|
|
193
|
-
(req, res) => {
|
|
194
|
-
res.json({ admin: req.admin });
|
|
195
|
-
},
|
|
196
|
-
);
|
|
197
113
|
```
|
|
198
114
|
|
|
199
115
|
### Login and Logout
|
|
@@ -211,16 +127,11 @@ router.post("/logout", async (req, res) => {
|
|
|
211
127
|
await Auth.logout(res);
|
|
212
128
|
res.json({ message: "Logged out" });
|
|
213
129
|
});
|
|
214
|
-
|
|
215
|
-
await Auth.login(res, user, "my_session", {
|
|
216
|
-
expiresIn: "7d",
|
|
217
|
-
cookie: { httpOnly: true, secure: true },
|
|
218
|
-
});
|
|
219
130
|
```
|
|
220
131
|
|
|
221
132
|
## 6. Performance Caching (Cache)
|
|
222
133
|
|
|
223
|
-
If
|
|
134
|
+
If an Express route involves heavy processing or database queries, utilize the `Cache` middleware to cache the REST API JSON payload.
|
|
224
135
|
|
|
225
136
|
```javascript
|
|
226
137
|
import Cache from "@seip/blue-bird/core/cache.js";
|
|
@@ -228,10 +139,6 @@ import Cache from "@seip/blue-bird/core/cache.js";
|
|
|
228
139
|
router.get("/stats", Cache.middleware(60), (req, res) => {
|
|
229
140
|
res.json({ ok: true });
|
|
230
141
|
});
|
|
231
|
-
|
|
232
|
-
router.get("/dashboard", Cache.middleware(120), (req, res) => {
|
|
233
|
-
Template.render(res, "dashboard");
|
|
234
|
-
});
|
|
235
142
|
```
|
|
236
143
|
|
|
237
144
|
## 7. Security (Helmet)
|
|
@@ -241,9 +148,8 @@ Helmet is **not applied globally** by default. Apply it per-router where needed:
|
|
|
241
148
|
```javascript
|
|
242
149
|
import App from "@seip/blue-bird/core/app.js";
|
|
243
150
|
|
|
244
|
-
const
|
|
245
|
-
|
|
246
|
-
webRouter.use(App.helmet({ contentSecurityPolicy: false }));
|
|
151
|
+
const apiRouter = new Router("/api");
|
|
152
|
+
apiRouter.use(App.helmet());
|
|
247
153
|
```
|
|
248
154
|
|
|
249
155
|
## 8. Docker Compose CLI
|
|
@@ -264,32 +170,11 @@ npx blue-bird docker prune # Cleans unused volumes, dangling images, an
|
|
|
264
170
|
|
|
265
171
|
The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts.
|
|
266
172
|
|
|
267
|
-
## 9.
|
|
268
|
-
|
|
269
|
-
Blue Bird includes a high-performance Hybrid SPA rendering feature.
|
|
270
|
-
1. **Server Detection**: `Template.render` intercepts SPA requests (header `X-blueBird-SPA: true` or query `?source=frontend`). It returns a parsed JSON payload with `meta`, `body` (only content inside `#blueBird-spa-content`), and `css` stylesheets.
|
|
271
|
-
2. **SPA Direct Caching**: SPA requests are cached separately (key `spa:<template>`). The server strips security headers (CSP, Frame-Options, Content-Type-Options) to reduce JSON payload bytes.
|
|
272
|
-
3. **Preact Islands**: Use import maps to render dynamic reactive zones. Simply add scripts of type `module` inside `#blueBird-spa-content`, and they will automatically execute and render on each navigation.
|
|
273
|
-
|
|
274
|
-
```html
|
|
275
|
-
<script type="importmap">
|
|
276
|
-
{
|
|
277
|
-
"imports": {
|
|
278
|
-
"preact": "https://esm.sh/preact@10.19.2",
|
|
279
|
-
"preact/hooks": "https://esm.sh/preact@10.19.2/hooks",
|
|
280
|
-
"htm/preact": "https://esm.sh/htm@3.1.1/preact"
|
|
281
|
-
}
|
|
282
|
-
}
|
|
283
|
-
</script>
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
## 10. AI Development Guidelines
|
|
173
|
+
## 9. AI Development Guidelines
|
|
287
174
|
|
|
288
|
-
1. **Frontend**: Use
|
|
175
|
+
1. **Frontend**: Use Astro pages inside `frontend/src/pages/` (e.g. `.astro` files). Static/public assets belong in `frontend/public/`.
|
|
289
176
|
2. **JSON Responses**: API endpoints should return standardized responses formatted as `{ message: "..." }` or `{ data: ... }`.
|
|
290
177
|
3. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
|
|
291
|
-
4. **
|
|
292
|
-
5. **Caching & Minification**: Cache pages using `Template.render` options or route-level `Cache.middleware()`. All HTML outputs are automatically minified.
|
|
293
|
-
6. **No inline comments**: Only use JSDoc for documentation.
|
|
178
|
+
4. **No inline comments**: Only use JSDoc for documentation.
|
|
294
179
|
|
|
295
180
|
_This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._
|
package/README.md
CHANGED
|
@@ -9,23 +9,19 @@
|
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## Introduction
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
**Blue Bird** es un framework potente basado en **Express**. Está diseñado para ayudar a los desarrolladores a construir aplicaciones rápidas, APIs escalables y todo pre-configurado: validación de datos, middlewares de seguridad, autenticación JWT encriptada con GCM, renderizado de plantillas HTML crudo con caché ultra rápida en memoria, minificación HTML automática, gestión de SEO, hot-reload y flujos de trabajo con Docker y CLI integrados.
|
|
14
|
+
Blue Bird is a powerful, opinionated framework built on Express for backend routing and APIs, integrated with Astro (v7.0) for high-performance frontend rendering. It features pre-configured data validation, security middlewares, GCM-encrypted JWT authentication, and CLI/Docker developer workflows out of the box.
|
|
17
15
|
|
|
18
16
|
---
|
|
19
17
|
|
|
20
18
|
## 🚀 Key Features / Características Clave
|
|
21
19
|
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
- 🔄 **SSE Hot Reload**: Automated browser hot-reloading in development (`DEBUG=true`) on file changes.
|
|
28
|
-
- 🐳 **Docker & PM2 Devops**: Pre-built Docker Compose/Dockerfile templates and CLI tools for zero-config dev and VPS production.
|
|
20
|
+
- All-In-One: Pre-configured Express server with JSON, URL encoding, Cookies, and CORS.
|
|
21
|
+
- Astro Frontend: Native integration with Astro (v7.0) for server-side rendering (SSR), static site generation (SSG), and middleware mode.
|
|
22
|
+
- Premium Security: AES-256-GCM encrypted JWT cookie auth, secure route filters, and built-in Helmet configurator.
|
|
23
|
+
- File Uploads: Easy Multer-based single/multiple file storage handling.
|
|
24
|
+
- Docker & PM2 Devops: Pre-built Docker Compose/Dockerfile templates and CLI tools for zero-config dev and VPS production.
|
|
29
25
|
|
|
30
26
|
---
|
|
31
27
|
|
|
@@ -58,20 +54,21 @@ npm run dev
|
|
|
58
54
|
```
|
|
59
55
|
project/
|
|
60
56
|
├── backend/
|
|
61
|
-
│
|
|
62
|
-
│
|
|
63
|
-
│ │ └── frontend.js # Frontend HTML template routes
|
|
64
|
-
│ └── index.js # App startup and initialization
|
|
57
|
+
│ └── routes/ # Express route files
|
|
58
|
+
│ └── api.js # REST API routes
|
|
65
59
|
├── frontend/
|
|
66
|
-
│ ├──
|
|
67
|
-
│ │
|
|
68
|
-
│ │
|
|
69
|
-
│ └──
|
|
70
|
-
│
|
|
71
|
-
│
|
|
60
|
+
│ ├── src/
|
|
61
|
+
│ │ └── pages/ # Astro routes and pages (.astro)
|
|
62
|
+
│ │ ├── index.astro
|
|
63
|
+
│ │ └── about.astro
|
|
64
|
+
│ ├── public/ # Static assets mapped to root of Astro build
|
|
65
|
+
│ │ └── js/
|
|
66
|
+
│ │ └── tailwind.js # Local Tailwind compiler
|
|
67
|
+
│ └── astro.config.mjs # Astro configuration file
|
|
72
68
|
├── docker/
|
|
73
|
-
│ └── Dockerfile # Optimized production
|
|
69
|
+
│ └── Dockerfile # Optimized production build file
|
|
74
70
|
├── docker-compose.yml # Dev/Prod container configurations
|
|
71
|
+
├── index.js # App startup and initialization entrypoint
|
|
75
72
|
├── AGENTS.md # AI coding assistant guidebook
|
|
76
73
|
└── .env # App configuration (git-ignored)
|
|
77
74
|
```
|
|
@@ -80,7 +77,7 @@ project/
|
|
|
80
77
|
|
|
81
78
|
## 📖 Core Modules Documentation / Documentación de Módulos
|
|
82
79
|
|
|
83
|
-
### 1. Routing
|
|
80
|
+
### 1. Routing (`Router`)
|
|
84
81
|
|
|
85
82
|
Do not use Express' native router. Always use Blue Bird's wrapper class:
|
|
86
83
|
|
|
@@ -94,61 +91,41 @@ routerApi.get("/users", (req, res) => {
|
|
|
94
91
|
export default routerApi;
|
|
95
92
|
```
|
|
96
93
|
|
|
97
|
-
**For the Frontend (HTML Rendering / SEO):**
|
|
98
|
-
Instantiate a router with `{ seo: true }`. All registered GET routes are automatically added to the dynamic sitemap at `/sitemap.xml` and `/robots.txt`.
|
|
99
|
-
|
|
100
|
-
```javascript
|
|
101
|
-
const router = new Router("/", { seo: true });
|
|
102
|
-
router.get("/", (req, res) => {
|
|
103
|
-
return Template.render(res, "index", {
|
|
104
|
-
metaTags: {
|
|
105
|
-
titleMeta: "Home",
|
|
106
|
-
descriptionMeta: "Welcome to Blue Bird Framework",
|
|
107
|
-
},
|
|
108
|
-
});
|
|
109
|
-
});
|
|
110
|
-
```
|
|
111
|
-
|
|
112
94
|
---
|
|
113
95
|
|
|
114
|
-
### 2.
|
|
96
|
+
### 2. Astro Node Middleware Integration
|
|
115
97
|
|
|
116
|
-
|
|
98
|
+
Blue Bird supports Astro (v7.0) Node middleware mode. Astro handles frontend SSR, routing, static assets, and layouts, while Express handles API endpoints and server logic.
|
|
117
99
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
- `{{lang}}`: Selected/active language code.
|
|
121
|
-
- `{{title}}` or `{{titleMeta}}`: Page HTML title.
|
|
122
|
-
- `{{canonicalUrl}}`: Canonical page URL for crawlers.
|
|
123
|
-
- `{{description}}`: Meta description.
|
|
124
|
-
- `{{keywords}}`: Meta keywords.
|
|
125
|
-
- `{{author}}`: Meta author.
|
|
100
|
+
To enable Astro integration:
|
|
126
101
|
|
|
127
102
|
```javascript
|
|
128
|
-
import
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
metaTags: {
|
|
135
|
-
titleMeta: "About Us",
|
|
136
|
-
descriptionMeta: "Learn more about us",
|
|
137
|
-
},
|
|
138
|
-
});
|
|
103
|
+
import App from "@seip/blue-bird/core/app.js";
|
|
104
|
+
import routerApi from "./backend/routes/api.js";
|
|
105
|
+
|
|
106
|
+
const app = new App({
|
|
107
|
+
routes: [routerApi],
|
|
108
|
+
astro: true, // Enables Astro middleware mode
|
|
139
109
|
});
|
|
110
|
+
|
|
111
|
+
app.run();
|
|
140
112
|
```
|
|
141
113
|
|
|
142
|
-
####
|
|
114
|
+
#### Advanced Config Options
|
|
143
115
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
116
|
+
You can pass a configuration object instead of a boolean value:
|
|
117
|
+
|
|
118
|
+
```javascript
|
|
119
|
+
const app = new App({
|
|
120
|
+
astro: {
|
|
121
|
+
server: true, // Mounts Astro SSR handler
|
|
122
|
+
serverEntry: "./frontend/dist/server/entry.mjs", // Path to compiled Astro server entrypoint
|
|
123
|
+
client: false, // Set to true to serve static files from client build
|
|
124
|
+
clientDir: "./frontend/dist/client", // Path to Astro client static assets
|
|
125
|
+
base: "/" // Mount base path
|
|
126
|
+
}
|
|
127
|
+
});
|
|
128
|
+
```
|
|
152
129
|
|
|
153
130
|
---
|
|
154
131
|
|
|
@@ -288,7 +265,7 @@ To deploy in a standard Linux environment using PM2 process manager:
|
|
|
288
265
|
```
|
|
289
266
|
2. Start the application under PM2:
|
|
290
267
|
```bash
|
|
291
|
-
pm2 start
|
|
268
|
+
pm2 start index.js --name "bluebird-app"
|
|
292
269
|
```
|
|
293
270
|
3. Monitor status:
|
|
294
271
|
```bash
|
|
@@ -298,67 +275,6 @@ To deploy in a standard Linux environment using PM2 process manager:
|
|
|
298
275
|
|
|
299
276
|
---
|
|
300
277
|
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
## ⚡ Hybrid SPA & Preact Integration
|
|
304
|
-
|
|
305
|
-
Blue Bird natively integrates high-performance Hybrid Single Page Application (SPA) support:
|
|
306
|
-
* **Server-Side:** The `Template` class intercepts SPA requests and returns only the `#blueBird-spa-content` section wrapped in an optimized JSON payload. These requests feature cleaned headers (removing strict CSP/Frame rules to minimize footprint) and are cached independently in RAM.
|
|
307
|
-
* **Client-Side (`blue-bird.js`):** The SPA engine intercepts local anchor link click events, plays animated *fadeOut* and *fadeIn* transitions using Anime.js, updates metadata, and injects the new HTML fragments.
|
|
308
|
-
|
|
309
|
-
### Preact Integration (Reactive Component Structure)
|
|
310
|
-
|
|
311
|
-
You can inject rich interactivity by adding Preact and HTM via Import Maps directly, without any build steps or bundlers:
|
|
312
|
-
|
|
313
|
-
#### 1. Load the Import Map in your HTML head:
|
|
314
|
-
```html
|
|
315
|
-
<head>
|
|
316
|
-
<!-- ... -->
|
|
317
|
-
<script type="importmap">
|
|
318
|
-
{
|
|
319
|
-
"imports": {
|
|
320
|
-
"preact": "https://esm.sh/preact@10.19.2",
|
|
321
|
-
"preact/hooks": "https://esm.sh/preact@10.19.2/hooks",
|
|
322
|
-
"htm/preact": "https://esm.sh/htm@3.1.1/preact"
|
|
323
|
-
}
|
|
324
|
-
}
|
|
325
|
-
</script>
|
|
326
|
-
<script src="/js/blue-bird.js"></script>
|
|
327
|
-
</head>
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
#### 2. Declare the component inside the `#blueBird-spa-content` container:
|
|
331
|
-
```html
|
|
332
|
-
<main id="blueBird-spa-content">
|
|
333
|
-
<div id="counter-app"></div>
|
|
334
|
-
|
|
335
|
-
<script type="module">
|
|
336
|
-
import { render } from 'preact';
|
|
337
|
-
import { useState } from 'preact/hooks';
|
|
338
|
-
import { html } from 'htm/preact';
|
|
339
|
-
|
|
340
|
-
function Counter() {
|
|
341
|
-
const [count, setCount] = useState(0);
|
|
342
|
-
return html`
|
|
343
|
-
<div class="p-6 bg-slate-900 border border-white/10 rounded-2xl">
|
|
344
|
-
<h2 class="text-lg font-bold">Preact Counter</h2>
|
|
345
|
-
<p class="text-3xl text-blue-400 font-extrabold my-2">${count}</p>
|
|
346
|
-
<button class="px-4 py-2 bg-blue-600 rounded-lg text-white font-semibold" onClick=${() => setCount(count + 1)}>
|
|
347
|
-
Increment
|
|
348
|
-
</button>
|
|
349
|
-
</div>
|
|
350
|
-
`;
|
|
351
|
-
}
|
|
352
|
-
|
|
353
|
-
render(html`<${Counter} />`, document.getElementById('counter-app'));
|
|
354
|
-
</script>
|
|
355
|
-
</main>
|
|
356
|
-
```
|
|
357
|
-
|
|
358
|
-
When navigating between pages using the SPA engine, any scripts of type `module` inside the page body will automatically execute in the DOM, mounting and updating your Preact "interactivity islands".
|
|
359
|
-
|
|
360
|
-
---
|
|
361
|
-
|
|
362
278
|
## 📄 License / Licencia
|
|
363
279
|
|
|
364
280
|
Distributed under the **MIT License**. See `LICENSE` for more information.
|
package/backend/routes/api.js
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import Router from "@seip/blue-bird/core/router.js";
|
|
2
2
|
import Validator from "@seip/blue-bird/core/validate.js";
|
|
3
3
|
import Cache from "@seip/blue-bird/core/cache.js";
|
|
4
|
-
import Auth from "@seip/blue-bird/core/auth.js"
|
|
4
|
+
import Auth from "@seip/blue-bird/core/auth.js";
|
|
5
5
|
|
|
6
|
-
const
|
|
6
|
+
const routerApi = new Router("/api");
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
routerApi.get("//", (req, res) => {
|
|
9
|
+
res.json({ api: true, message: "Bluebird API", time: Date.now() });
|
|
10
|
+
});
|
|
11
|
+
|
|
12
|
+
routerApi.get("/users", (req, res) => {
|
|
9
13
|
const users = [
|
|
10
14
|
{
|
|
11
15
|
name: "John Doe",
|
|
@@ -26,28 +30,28 @@ const loginSchema = {
|
|
|
26
30
|
|
|
27
31
|
const loginValidator = new Validator(loginSchema);
|
|
28
32
|
|
|
29
|
-
|
|
33
|
+
routerApi.post("/login", loginValidator.middleware(), (req, res) => {
|
|
30
34
|
res.json({ message: "Login successful", body: req.body });
|
|
31
35
|
});
|
|
32
36
|
|
|
33
|
-
|
|
34
|
-
await new Promise(resolve => setTimeout(resolve, 2000));
|
|
37
|
+
routerApi.get("/cache", Cache.middleware(), async (req, res) => {
|
|
38
|
+
await new Promise((resolve) => setTimeout(resolve, 2000));
|
|
35
39
|
res.json({ message: "Cache successful" });
|
|
36
|
-
})
|
|
40
|
+
});
|
|
37
41
|
|
|
38
|
-
|
|
39
|
-
const token = await Auth.login(res, { id: 1, name: "John Doe" })
|
|
42
|
+
routerApi.get("/auth_generate", async (req, res) => {
|
|
43
|
+
const token = await Auth.login(res, { id: 1, name: "John Doe" });
|
|
40
44
|
res.json({ message: "Auth successful", token });
|
|
41
|
-
})
|
|
45
|
+
});
|
|
42
46
|
|
|
43
|
-
|
|
44
|
-
await Auth.logout(res)
|
|
47
|
+
routerApi.get("/auth_logout", async (req, res) => {
|
|
48
|
+
await Auth.logout(res);
|
|
45
49
|
res.json({ message: "Auth successful" });
|
|
46
|
-
})
|
|
50
|
+
});
|
|
47
51
|
|
|
48
|
-
|
|
49
|
-
const userInfo = req.user
|
|
52
|
+
routerApi.get("/auth_verify", Auth.protect(), (req, res) => {
|
|
53
|
+
const userInfo = req.user;
|
|
50
54
|
res.json({ message: "Auth successful", user: userInfo });
|
|
51
|
-
})
|
|
55
|
+
});
|
|
52
56
|
|
|
53
|
-
export default
|
|
57
|
+
export default routerApi;
|