@seip/bluebird-js 0.0.1 → 0.1.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.
Files changed (81) hide show
  1. package/.env_example +53 -53
  2. package/AGENTS.md +426 -403
  3. package/LICENSE +1 -1
  4. package/README.md +292 -285
  5. package/app/routes/api.js +50 -50
  6. package/app/routes/web.js +55 -53
  7. package/app/views/about.js +63 -0
  8. package/app/views/dashboard.js +147 -0
  9. package/app/views/index.js +80 -0
  10. package/app/views/layouts/main/view.js +81 -0
  11. package/app/views/legal/terms.html +19 -0
  12. package/app/views/login.js +80 -0
  13. package/core/app.d.ts +18 -18
  14. package/core/app.js +684 -644
  15. package/core/auth.d.ts +13 -13
  16. package/core/auth.js +326 -326
  17. package/core/cache.d.ts +17 -17
  18. package/core/cache.js +475 -475
  19. package/core/cli/doctor.js +287 -287
  20. package/core/cli/ecosystem.js +162 -162
  21. package/core/cli/init.js +779 -779
  22. package/core/cli/migrate.js +541 -541
  23. package/core/cli/model.js +66 -66
  24. package/core/cli/nginx.js +199 -199
  25. package/core/cli/route.js +120 -120
  26. package/core/cli/view.js +55 -36
  27. package/core/config.d.ts +3 -3
  28. package/core/config.js +111 -111
  29. package/core/csrf.d.ts +3 -3
  30. package/core/csrf.js +114 -114
  31. package/core/database.d.ts +15 -15
  32. package/core/database.js +636 -636
  33. package/core/debug.d.ts +3 -3
  34. package/core/debug.js +249 -249
  35. package/core/hash.d.ts +3 -3
  36. package/core/hash.js +194 -194
  37. package/core/html.d.ts +42 -0
  38. package/core/html.js +217 -0
  39. package/core/index.d.ts +1176 -1071
  40. package/core/logger.d.ts +3 -3
  41. package/core/logger.js +127 -124
  42. package/core/middleware.d.ts +3 -3
  43. package/core/middleware.js +28 -28
  44. package/core/model.d.ts +19 -19
  45. package/core/model.js +600 -600
  46. package/core/queue.d.ts +13 -13
  47. package/core/queue.js +172 -172
  48. package/core/ratelimit.d.ts +3 -3
  49. package/core/ratelimit.js +145 -145
  50. package/core/redis.d.ts +21 -21
  51. package/core/redis.js +230 -230
  52. package/core/render-cache.js +212 -0
  53. package/core/render.d.ts +3 -3
  54. package/core/render.js +199 -555
  55. package/core/router.d.ts +3 -3
  56. package/core/router.js +171 -171
  57. package/core/seo.d.ts +3 -3
  58. package/core/seo.js +106 -106
  59. package/core/swagger.d.ts +3 -3
  60. package/core/swagger.js +60 -60
  61. package/core/upload.d.ts +13 -13
  62. package/core/upload.js +102 -102
  63. package/core/util/colors.js +82 -82
  64. package/core/validate.d.ts +15 -15
  65. package/core/validate.js +364 -364
  66. package/core/view-loader.js +162 -0
  67. package/core/vite.d.ts +3 -3
  68. package/core/vite.js +145 -145
  69. package/core/ws.d.ts +13 -13
  70. package/core/ws.js +245 -245
  71. package/index.js +18 -18
  72. package/jsconfig.json +15 -15
  73. package/package.json +85 -86
  74. package/production.md +273 -273
  75. package/public/css/bluebird.min.css +1 -1
  76. package/public/js/bluebird-client.js +1780 -1662
  77. package/public/js/bluebird.min.js +1072 -1072
  78. package/app/views/about.html +0 -161
  79. package/app/views/dashboard.html +0 -140
  80. package/app/views/index.html +0 -150
  81. package/app/views/login.html +0 -144
package/LICENSE CHANGED
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
18
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,285 +1,292 @@
1
- # Bluebird.js Framework
2
-
3
- **Performance-first Node.js API and web framework with native JavaScript ESM, built-in JWT auth, HTML rendering, BaseModel, schema validation, and multi-level caching.**
4
-
5
- [![npm version](https://img.shields.io/npm/v/@seip/bluebird-js.svg)](https://www.npmjs.com/package/@seip/bluebird-js)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
- [![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.18.0-brightgreen.svg)](https://nodejs.org)
8
-
9
- ---
10
-
11
- ## Introduction
12
-
13
- Bluebird.js (`@seip/bluebird-js`) is a high-performance web and API framework built on Express (Node.js 22.18+). It provides native modern JavaScript ESM execution, HTML template rendering, multi-driver caching (in-memory by default with filesystem and Redis support), AES-256-GCM encrypted JWT authentication, BaseModel schema definitions, CSRF protection, background queues, and PM2 production clustering into a cohesive developer experience.
14
-
15
- ### Key Highlights
16
-
17
- - **Pure Modern JavaScript (ESM):** Zero build steps, zero transpilation, pure Node.js 22.18+ ESM.
18
- - **Root Entrypoint (`index.js`):** Clean and intuitive architecture with the entry file directly at the root.
19
- - **Server Layouts, Partials & React Islands:** Fast SSR HTML with L0 in-memory template caching, shared layouts (`{{!< main}}`), reusable server partials with props (`{{> card title="Users"}}`), loops/conditionals, selective React Islands via Vite, View Transitions SPA navigation, and uninterrupted audio/video streaming (`data-persist="true"`).
20
- - **Lightweight BaseModel:** Static facade providing readable schemas, CRUD shortcuts, smart relations, soft deletes, automatic query cache invalidation, and validation bridges.
21
- - **Native SQLite & Desktop Mode (Electron/Tauri):** Uses Node's built-in `node:sqlite` driver with zero compilation overhead, plus first-class `desktop: true` mode (`app.runDesktop()`) for read-only `.asar` bundles.
22
- - **Decoupled Caching:** High-speed in-memory LRU cache by default, persistent filesystem fallback, and modular Redis support via `core/redis.js`.
23
- - **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection, built-in Rate Limiter (`rateLimit` in `App` or `App.rateLimit()`), automatic `/sitemap.xml` & `/robots.txt` generation, and secure HTTP headers without external bloat.
24
- - **Production Ready:** Built-in PM2 clustering CLI (`npx bluebird-js make:ecosystem`), optimized Nginx generator (`npx bluebird-js nginx:conf`), and native runner (`npm start`).
25
-
26
- ---
27
-
28
- ## Quick Start
29
-
30
- ### 1. Requirements
31
-
32
- - Node.js 22.18.0 or higher
33
- - npm 10+
34
-
35
- ### 2. Installation and Initialization
36
-
37
- ```bash
38
- npm install @seip/bluebird-js
39
- npx bluebird-js
40
- ```
41
-
42
- The interactive CLI configures:
43
- - Project title and port settings
44
- - Database engine: `sqlite` (default, native zero-configuration), `mysql`, `postgres`, or `none`
45
- - Connection credentials and database paths
46
- - Automatic generation of `index.js`, `.env`, `jsconfig.json`, `app/`, and `public/`
47
-
48
- ### 3. Development Server
49
-
50
- ```bash
51
- npm run dev
52
- ```
53
-
54
- The server starts with Node's native file watcher (`--watch`) and loads `.env` automatically via `--env-file=.env`.
55
-
56
- ---
57
-
58
- ## Project Structure
59
-
60
- ```
61
- project/
62
- ├── index.js # Main application entrypoint
63
- ├── app/
64
- │ ├── models/ # BaseModel definitions
65
- │ │ ├── user.js # User model schema & methods
66
- │ │ └── post.js # Post model schema & relations
67
- │ ├── routes/ # Application routes
68
- │ │ ├── api.js # REST API routes
69
- │ │ └── web.js # HTML page routes
70
- │ ├── views/ # HTML and EJS templates
71
- │ │ ├── layouts/ # Shared page layouts (e.g. main.html)
72
- │ │ ├── partials/ # Reusable server partials/components
73
- │ │ ├── index.html # Public home view
74
- │ │ └── about.html # About page view
75
- │ └── jobs/ # Background worker job handlers
76
- ├── src/ # Frontend source (React Islands)
77
- │ └── islands/ # Interactive React island components
78
- ├── public/ # Public static assets (CSS, JS, images, fonts)
79
- │ ├── css/
80
- │ ├── js/
81
- │ │ └── bluebird-client.js # View Transitions, partial swaps & islands runtime
82
- │ └── dist/ # Production Vite hashed bundles
83
- ├── core/ # Bluebird.js framework core
84
- ├── database/ # SQLite storage and SQL migrations
85
- │ └── migrations/
86
- ├── ecosystem.config.cjs # PM2 cluster configuration (production)
87
- ├── production.md # Production deployment guide
88
- ├── .env # Environment variables
89
- └── package.json
90
- ```
91
-
92
- ---
93
-
94
- ## Usage Examples
95
-
96
- ### 1. Application Entrypoint (`index.js`)
97
-
98
- ```javascript
99
- import App from "@seip/bluebird-js/core/app.js";
100
- import routerApi from "./app/routes/api.js";
101
- import routerWeb from "./app/routes/web.js";
102
-
103
- const app = new App({
104
- routes: [routerWeb, routerApi],
105
- port: process.env.PORT || 3000,
106
- rateLimit: { max: 120, windowMs: 60000 },
107
- });
108
-
109
- app.run();
110
- ```
111
-
112
- For **Electron / Desktop** applications:
113
-
114
- ```javascript
115
- const app = new App({
116
- desktop: true,
117
- userDataPath: electronApp.getPath("userData"),
118
- routes: [routerWeb, routerApi],
119
- });
120
-
121
- const { url } = await app.runDesktop();
122
- mainWindow.loadURL(url);
123
- ```
124
-
125
- ### 2. Defining a Model (`app/models/user.js`)
126
-
127
- ```javascript
128
- import Model from "@seip/bluebird-js/core/model.js";
129
-
130
- export default class User extends Model {
131
- static table = "users";
132
- static primaryKey = "id";
133
- static timestamps = true;
134
- static softDelete = true;
135
-
136
- static schema = {
137
- id: { type: "int", primary: true, auto: true },
138
- name: { type: "string", length: 150, required: true },
139
- email: { type: "string", length: 150, unique: true, required: true, email: true },
140
- password: { type: "string", length: 255, required: true, min: 8, hidden: true, hash: true },
141
- role: { type: "string", length: 20, default: "user", in: ["user", "admin"] },
142
- };
143
- }
144
- ```
145
-
146
- ### 3. REST API Routes (`app/routes/api.js`)
147
-
148
- ```javascript
149
- import App from "@seip/bluebird-js/core/app.js";
150
- import Router from "@seip/bluebird-js/core/router.js";
151
- import User from "../models/user.js";
152
-
153
- const routerApi = new Router("/api");
154
-
155
- routerApi.get("/users", async (req, res) => {
156
- const users = await User.all({ limit: 50, order: "id DESC" });
157
- res.ok({ users });
158
- });
159
-
160
- routerApi.post(
161
- "/users",
162
- App.rateLimit({ max: 10, windowMs: 60000 }),
163
- User.validator("create").middleware(),
164
- async (req, res) => {
165
- const userId = await User.create(req.body);
166
- res.created({ id: userId }, "User created successfully");
167
- }
168
- );
169
-
170
- export default routerApi;
171
- ```
172
-
173
- ### 4. HTML Views, Layouts & Server Partials (`app/routes/web.js`)
174
-
175
- When `{ seo: true }` is enabled on a router, Bluebird automatically generates `/sitemap.xml` and `/robots.txt`:
176
-
177
- ```javascript
178
- import Router from "@seip/bluebird-js/core/router.js";
179
- import Render from "@seip/bluebird-js/core/render.js";
180
-
181
- const routerWeb = new Router("/", { seo: true });
182
-
183
- routerWeb.get("/", Render.view("index", { title: "Bluebird Application" }));
184
- routerWeb.get("/stats-card", (req, res) => {
185
- return Render.partial(res, "stat_card", { label: "Revenue", val: "$12,400", active: true });
186
- });
187
-
188
- export default routerWeb;
189
- ```
190
-
191
- Inside your views (`app/views/dashboard.html`), use layouts (`{{!< main}}`), partials with props (`{{> name ...}}`), loops (`{{#each}}`), and conditionals (`{{#if}}`):
192
-
193
- ```html
194
- {{!< main }}
195
- <section class="stats-grid">
196
- {{> stat_card label="Revenue" val=stats.revenue active=true }}
197
- <ul>
198
- {{#each items as item}}
199
- <li>{{ item_index }}: {{ item.name }}</li>
200
- {{/each}}
201
- </ul>
202
- </section>
203
- ```
204
-
205
- ### 5. Multi-Driver Caching (`core/cache.js`)
206
-
207
- ```javascript
208
- import Cache from "@seip/bluebird-js/core/cache.js";
209
-
210
- await Cache.set("metrics", { activeUsers: 450 }, 60, { driver: "memory" });
211
- const metrics = await Cache.get("metrics", { driver: "memory" });
212
-
213
- await Cache.set("report", htmlContent, 300, { driver: "file" });
214
- ```
215
-
216
- ### 6. React Islands & Client Router (`src/islands/`)
217
-
218
- Combine server-side rendered dynamic SEO with interactive React components and instant View Transitions SPA navigation:
219
-
220
- ```bash
221
- # 1. Install React and Vite island tooling
222
- npx bluebird-js add react-islands
223
- ```
224
-
225
- Inside your HTML template (`app/views/index.html`):
226
- ```html
227
- <!DOCTYPE html>
228
- <html lang="en">
229
- <head>
230
- <meta charset="UTF-8" />
231
- <title>{{title}}</title>
232
- <meta name="description" content="{{description}}" />
233
- {{{bluebirdHead}}}
234
- <script type="module" src="/js/bluebird-client.js"></script>
235
- </head>
236
- <body>
237
- <!-- Persistent live media stream or state across page navigation -->
238
- <div data-island="RadioPlayer" data-props='{"stream":"https://live.mp3"}' data-persist="true"></div>
239
-
240
- <!-- Interactive component -->
241
- <div data-island="LiveCounter" data-props='{"initial": 0}'></div>
242
-
243
- <!-- Partial fragment swap without reloading full page -->
244
- <a href="/stats-card" data-partial-target="#stats-panel">Refresh Stats</a>
245
- <div id="stats-panel"></div>
246
- </body>
247
- </html>
248
- ```
249
-
250
- ---
251
-
252
- ## Production Deployment
253
-
254
- Bluebird.js supports direct Node.js execution and PM2 process clustering out of the box:
255
-
256
- ```bash
257
- npm start # Starts via Node.js
258
- npx bluebird-js make:ecosystem --start # Generates ecosystem config and launches via PM2
259
- ```
260
-
261
- For complete instructions covering PM2, systemd services, Nginx reverse proxy setup, and optional standalone Docker configurations, read the [Production Guide](production.md).
262
-
263
- ---
264
-
265
- ## Developer Tooling CLI
266
-
267
- ```bash
268
- npx bluebird-js doctor # Diagnostic audit and HTTP smoke tests
269
- npx bluebird-js make:model <Name> # Generates BaseModel class
270
- npx bluebird-js make:route <name> [--auth] # Scaffolds REST route
271
- npx bluebird-js make:view <name> [--ejs] # Scaffolds HTML/EJS template
272
- npx bluebird-js make:migration <name> [--model <M>] # Generates database migration
273
- npx bluebird-js migrate # Executes pending migrations
274
- npx bluebird-js seed # Executes database seeds
275
- npx bluebird-js nginx:conf [domain] [port] [root] # Generates Nginx reverse proxy configuration
276
- npx bluebird-js make:ecosystem [--start] # Generates PM2 clustering config
277
- npx bluebird-js add react-islands # Scaffolds React Islands, Vite & Client Router
278
- npx bluebird-js add <module> # Installs optional on-demand package
279
- ```
280
-
281
- ---
282
-
283
- ## License
284
-
285
- MIT License. Copyright (c) 2026 Seip25.
1
+ # Bluebird.js Framework
2
+
3
+ **Performance-first Node.js API and web framework with native JavaScript ESM, built-in JWT auth, HTML rendering, BaseModel, schema validation, and multi-level caching.**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@seip/bluebird-js.svg)](https://www.npmjs.com/package/@seip/bluebird-js)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
+ [![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.18.0-brightgreen.svg)](https://nodejs.org)
8
+
9
+ ---
10
+
11
+ ## Introduction
12
+
13
+ Bluebird.js (`@seip/bluebird-js`) is a high-performance web and API framework built on Express (Node.js 22.18+). It provides native modern JavaScript ESM execution, HTML template rendering, multi-driver caching (in-memory by default with filesystem and Redis support), AES-256-GCM encrypted JWT authentication, BaseModel schema definitions, CSRF protection, background queues, and PM2 production clustering into a cohesive developer experience.
14
+
15
+ ### Key Highlights
16
+
17
+ - **Pure Modern JavaScript (ESM):** Zero build steps, zero transpilation, pure Node.js 22.18+ ESM.
18
+ - **Root Entrypoint (`index.js`):** Clean and intuitive architecture with the entry file directly at the root.
19
+ - **Pure JavaScript Views & View Transitions:** Modern zero-build SSR with tagged template literals (html\`...\`), automatic XSS escaping, shared layouts, simple inline vanilla scripts, View Transitions SPA navigation, and uninterrupted audio/video streaming (data-persist="true").
20
+ - **Lightweight BaseModel:** Static facade providing readable schemas, CRUD shortcuts, smart relations, soft deletes, automatic query cache invalidation, and validation bridges.
21
+ - **Native SQLite & Desktop Mode (Electron/Tauri):** Uses Node's built-in `node:sqlite` driver with zero compilation overhead, plus first-class `desktop: true` mode (`app.runDesktop()`) for read-only `.asar` bundles.
22
+ - **Decoupled Caching:** High-speed in-memory LRU cache by default, persistent filesystem fallback, and modular Redis support via `core/redis.js`.
23
+ - **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection, built-in Rate Limiter (`rateLimit` in `App` or `App.rateLimit()`), automatic `/sitemap.xml` & `/robots.txt` generation, and secure HTTP headers without external bloat.
24
+ - **Production Ready:** Built-in PM2 clustering CLI (`npx bluebird-js make:ecosystem`), optimized Nginx generator (`npx bluebird-js nginx:conf`), and native runner (`npm start`).
25
+
26
+ ---
27
+
28
+ ## Quick Start
29
+
30
+ ### 1. Requirements
31
+
32
+ - Node.js 22.18.0 or higher
33
+ - npm 10+
34
+
35
+ ### 2. Installation and Initialization
36
+
37
+ ```bash
38
+ npm install @seip/bluebird-js
39
+ npx bluebird-js
40
+ ```
41
+
42
+ The interactive CLI configures:
43
+ - Project title and port settings
44
+ - Database engine: `sqlite` (default, native zero-configuration), `mysql`, `postgres`, or `none`
45
+ - Connection credentials and database paths
46
+ - Automatic generation of `index.js`, `.env`, `jsconfig.json`, `app/`, and `public/`
47
+
48
+ ### 3. Development Server
49
+
50
+ ```bash
51
+ npm run dev
52
+ ```
53
+
54
+ The server starts with Node's native file watcher (`--watch`) and loads `.env` automatically via `--env-file=.env`.
55
+
56
+ ---
57
+
58
+ ## Project Structure
59
+
60
+ ```
61
+ project/
62
+ ├── index.js # Main application entrypoint
63
+ ├── app/
64
+ │ ├── models/ # BaseModel definitions
65
+ │ │ ├── user.js # User model schema & methods
66
+ │ │ └── post.js # Post model schema & relations
67
+ │ ├── routes/ # Application routes
68
+ │ │ ├── api.js # REST API routes
69
+ │ │ └── web.js # HTML page routes
70
+ │ ├── views/ # Pure JavaScript ESM views
71
+ │ │ ├── layouts/ # Shared page layouts (e.g. main/view.js)
72
+ │ │ ├── index.js # Public home view
73
+ │ │ ├── about.js # About page view
74
+ │ │ ├── login.js # Sign-in page view
75
+ │ │ └── dashboard.js # Protected dashboard view
76
+ │ └── jobs/ # Background worker job handlers
77
+ ├── src/ # Frontend source (React Islands)
78
+ │ └── islands/ # Interactive React island components
79
+ ├── public/ # Public static assets (CSS, JS, images, fonts)
80
+ │ ├── css/
81
+ │ ├── js/
82
+ │ │ └── bluebird-client.js # View Transitions, partial swaps & islands runtime
83
+ │ └── dist/ # Production Vite hashed bundles
84
+ ├── core/ # Bluebird.js framework core
85
+ ├── database/ # SQLite storage and SQL migrations
86
+ │ └── migrations/
87
+ ├── ecosystem.config.cjs # PM2 cluster configuration (production)
88
+ ├── production.md # Production deployment guide
89
+ ├── .env # Environment variables
90
+ └── package.json
91
+ ```
92
+
93
+ ---
94
+
95
+ ## Usage Examples
96
+
97
+ ### 1. Application Entrypoint (`index.js`)
98
+
99
+ ```javascript
100
+ import App from "@seip/bluebird-js/core/app.js";
101
+ import routerApi from "./app/routes/api.js";
102
+ import routerWeb from "./app/routes/web.js";
103
+
104
+ const app = new App({
105
+ routes: [routerWeb, routerApi],
106
+ port: process.env.PORT || 3000,
107
+ rateLimit: { max: 120, windowMs: 60000 },
108
+ });
109
+
110
+ app.run();
111
+ ```
112
+
113
+ For **Electron / Desktop** applications:
114
+
115
+ ```javascript
116
+ const app = new App({
117
+ desktop: true,
118
+ userDataPath: electronApp.getPath("userData"),
119
+ routes: [routerWeb, routerApi],
120
+ });
121
+
122
+ const { url } = await app.runDesktop();
123
+ mainWindow.loadURL(url);
124
+ ```
125
+
126
+ ### 2. Defining a Model (`app/models/user.js`)
127
+
128
+ ```javascript
129
+ import Model from "@seip/bluebird-js/core/model.js";
130
+
131
+ export default class User extends Model {
132
+ static table = "users";
133
+ static primaryKey = "id";
134
+ static timestamps = true;
135
+ static softDelete = true;
136
+
137
+ static schema = {
138
+ id: { type: "int", primary: true, auto: true },
139
+ name: { type: "string", length: 150, required: true },
140
+ email: { type: "string", length: 150, unique: true, required: true, email: true },
141
+ password: { type: "string", length: 255, required: true, min: 8, hidden: true, hash: true },
142
+ role: { type: "string", length: 20, default: "user", in: ["user", "admin"] },
143
+ };
144
+ }
145
+ ```
146
+
147
+ ### 3. REST API Routes (`app/routes/api.js`)
148
+
149
+ ```javascript
150
+ import App from "@seip/bluebird-js/core/app.js";
151
+ import Router from "@seip/bluebird-js/core/router.js";
152
+ import User from "../models/user.js";
153
+
154
+ const routerApi = new Router("/api");
155
+
156
+ routerApi.get("/users", async (req, res) => {
157
+ const users = await User.all({ limit: 50, order: "id DESC" });
158
+ res.ok({ users });
159
+ });
160
+
161
+ routerApi.post(
162
+ "/users",
163
+ App.rateLimit({ max: 10, windowMs: 60000 }),
164
+ User.validator("create").middleware(),
165
+ async (req, res) => {
166
+ const userId = await User.create(req.body);
167
+ res.created({ id: userId }, "User created successfully");
168
+ }
169
+ );
170
+
171
+ export default routerApi;
172
+ ```
173
+
174
+ ### 4. HTML Views, Layouts & Server Partials (`app/routes/web.js`)
175
+
176
+ When `{ seo: true }` is enabled on a router, Bluebird automatically generates `/sitemap.xml` and `/robots.txt`:
177
+
178
+ ```javascript
179
+ import Router from "@seip/bluebird-js/core/router.js";
180
+ import Render from "@seip/bluebird-js/core/render.js";
181
+
182
+ const routerWeb = new Router("/", { seo: true });
183
+
184
+ routerWeb.get("/", Render.view("index", { title: "Bluebird Application" }));
185
+ routerWeb.get("/stats-card", (req, res) => {
186
+ return Render.partial(res, "stat_card", { label: "Revenue", val: "$12,400", active: true });
187
+ });
188
+
189
+ export default routerWeb;
190
+ ```
191
+
192
+ Inside your views (`app/views/dashboard.js`), use pure JavaScript functions with `html` tagged templates and plain vanilla `<script>` tags:
193
+
194
+ ```javascript
195
+ // app/views/dashboard.js
196
+ import { html } from "@seip/bluebird-js/core/html.js";
197
+
198
+ export const layout = "main";
199
+ export const head = (data) => ({ title: `Dashboard — ${data.user?.name || "Member"}` });
200
+
201
+ export default function DashboardView({ user, metrics }) {
202
+ const initial = metrics?.unread || 0;
203
+
204
+ return html`
205
+ <section class="dashboard-grid">
206
+ <h1>Welcome back, ${user.name}</h1>
207
+
208
+ <div class="card">
209
+ <button id="btnDec" class="btn-sm">-</button>
210
+ <span id="counter" class="font-bold">${initial}</span>
211
+ <button id="btnInc" class="btn-sm">+</button>
212
+ </div>
213
+ </section>
214
+
215
+ <!-- Native inline script: clean, readable, zero build steps -->
216
+ <script>
217
+ (() => {
218
+ let count = ${initial};
219
+ const el = document.getElementById("counter");
220
+ document.getElementById("btnInc")?.addEventListener("click", () => {
221
+ count++;
222
+ if (el) el.textContent = count;
223
+ });
224
+ document.getElementById("btnDec")?.addEventListener("click", () => {
225
+ if (count > 0) count--;
226
+ if (el) el.textContent = count;
227
+ });
228
+ })();
229
+ </script>
230
+ `;
231
+ }
232
+ ```
233
+
234
+ > **Live Reload:** When running development (`npm run dev` with `node --watch`), Bluebird automatically reloads the browser tab via native Server-Sent Events whenever changes trigger a server restart. No plugins or browser extensions needed.
235
+
236
+ > **Architecture Tip:** Keep business operations, third-party APIs, and database transactions in `app/services/` or `app/models/`. Views should remain declarative, lightweight, and focused on presentation.
237
+
238
+ ### 5. Multi-Driver Caching (`core/cache.js`)
239
+
240
+ ```javascript
241
+ import Cache from "@seip/bluebird-js/core/cache.js";
242
+
243
+ await Cache.set("metrics", { activeUsers: 450 }, 60, { driver: "memory" });
244
+ const metrics = await Cache.get("metrics", { driver: "memory" });
245
+
246
+ await Cache.set("report", htmlContent, 300, { driver: "file" });
247
+ ```
248
+
249
+ ### 6. Raw Static HTML Delivery (`Render.html`)
250
+
251
+ For static legal documents, terms of service, or offline pages without server-side templating overhead:
252
+
253
+ ```javascript
254
+ routerWeb.get("/terms", (req, res) => Render.html(res, "legal/terms.html", { ttl: 86400 }));
255
+ ```
256
+
257
+ ---
258
+
259
+ ## Production Deployment
260
+
261
+ Bluebird.js supports direct Node.js execution and PM2 process clustering out of the box:
262
+
263
+ ```bash
264
+ npm start # Starts via Node.js
265
+ npx bluebird-js make:ecosystem --start # Generates ecosystem config and launches via PM2
266
+ ```
267
+
268
+ For complete instructions covering PM2, systemd services, Nginx reverse proxy setup, and optional standalone Docker configurations, read the [Production Guide](production.md).
269
+
270
+ ---
271
+
272
+ ## Developer Tooling CLI
273
+
274
+ ```bash
275
+ npx bluebird-js doctor # Diagnostic audit and HTTP smoke tests
276
+ npx bluebird-js make:model <Name> # Generates BaseModel class
277
+ npx bluebird-js make:route <name> [--auth] # Scaffolds REST route
278
+ npx bluebird-js make:view <name> [--ejs] # Scaffolds HTML/EJS template
279
+ npx bluebird-js make:migration <name> [--model <M>] # Generates database migration
280
+ npx bluebird-js migrate # Executes pending migrations
281
+ npx bluebird-js seed # Executes database seeds
282
+ npx bluebird-js nginx:conf [domain] [port] [root] # Generates Nginx reverse proxy configuration
283
+ npx bluebird-js make:ecosystem [--start] # Generates PM2 clustering config
284
+ npx bluebird-js add react-islands # Scaffolds React Islands, Vite & Client Router
285
+ npx bluebird-js add <module> # Installs optional on-demand package
286
+ ```
287
+
288
+ ---
289
+
290
+ ## License
291
+
292
+ MIT License. Copyright (c) 2026 Seip25.