@seip/bluebird-js 0.1.7 → 0.2.1
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/AGENTS.md +727 -620
- package/README.md +670 -607
- package/app/models/user.js +19 -0
- package/app/resources/html/home.html +137 -0
- package/app/resources/html/layouts/main.html +55 -0
- package/app/resources/html/notFound.html +14 -0
- package/app/resources/html/table.html +15 -0
- package/app/resources/html/terms.html +46 -0
- package/app/resources/index.html +27 -0
- package/app/resources/layouts/AppLayout.jsx +92 -0
- package/app/resources/main.jsx +18 -0
- package/app/resources/pages/Dashboard.jsx +93 -0
- package/app/resources/pages/Home.jsx +140 -0
- package/app/resources/pages/Login.jsx +35 -0
- package/app/resources/pages/NotFound.jsx +16 -0
- package/app/resources/pages/Register.jsx +55 -0
- package/app/resources/pages/TableDemo.jsx +85 -0
- package/app/resources/routes.jsx +59 -0
- package/app/resources/spa.js +73 -0
- package/app/resources/styles.css +9 -0
- package/app/routes/api.js +129 -50
- package/app/routes/auth.js +209 -0
- package/app/routes/web.js +89 -47
- package/core/ai.js +30 -10
- package/core/app.d.ts +2 -18
- package/core/app.js +987 -801
- package/core/auth.d.ts +2 -13
- package/core/auth.js +444 -326
- package/core/cli/build.js +37 -0
- package/core/cli/dev.js +155 -0
- package/core/cli/doctor.js +37 -2
- package/core/cli/export.js +191 -0
- package/core/cli/init.js +91 -322
- package/core/cli/nginx.js +1 -1
- package/core/cli/templates.js +139 -0
- package/core/cli/view.js +98 -161
- package/core/config.js +44 -2
- package/core/csrf.js +156 -24
- package/core/database.js +1184 -1131
- package/core/debug.js +1 -1
- package/core/html.js +8 -1
- package/core/index.d.ts +126 -310
- package/core/paths.js +55 -0
- package/core/ratelimit.js +10 -1
- package/core/react/client/api.js +239 -0
- package/core/react/client/auth.js +236 -0
- package/core/react/client/components.js +1321 -0
- package/core/react/client/datatable.js +595 -0
- package/core/react/client/i18n.js +440 -0
- package/core/react/client/index.d.ts +314 -0
- package/core/react/client/index.js +50 -0
- package/core/react/client/router.js +26 -0
- package/core/react/client/theme.css +512 -0
- package/core/render-cache.js +250 -212
- package/core/render.d.ts +25 -21
- package/core/render.js +738 -736
- package/core/router.d.ts +2 -3
- package/core/router.js +171 -171
- package/core/seo.js +10 -0
- package/core/spa.js +599 -0
- package/core/view-loader.js +155 -613
- package/core/vite-plugin.d.ts +18 -0
- package/core/vite-plugin.js +162 -0
- package/core/vite.js +250 -145
- package/index.js +22 -18
- package/jsconfig.json +5 -3
- package/package.json +114 -92
- package/production.md +8 -3
- package/public/js/bluebird.js +1886 -0
- package/templates/_auth/app/database.js +19 -0
- package/templates/_auth/app/models/user.js +22 -0
- package/templates/_auth/app/routes/auth-router.js +304 -0
- package/templates/_base/app/resources/html/layouts/main.html +55 -0
- package/templates/_base/app/resources/html/notFound.html +14 -0
- package/templates/_base/app/resources/index.html +27 -0
- package/templates/_base/app/resources/styles.css +9 -0
- package/templates/api/app/models/note.js +18 -0
- package/templates/api/app/routes/api.js +82 -0
- package/templates/api/app/routes/auth.js +11 -0
- package/templates/api/index.js +19 -0
- package/templates/api/template.json +13 -0
- package/templates/auth/app/mail.js +11 -0
- package/templates/auth/app/models/password_reset.js +18 -0
- package/templates/auth/app/resources/html/home.html +21 -0
- package/templates/auth/app/resources/html/partials/nav.html +2 -0
- package/templates/auth/app/resources/layouts/AppLayout.jsx +60 -0
- package/templates/auth/app/resources/main.jsx +18 -0
- package/templates/auth/app/resources/pages/Dashboard.jsx +51 -0
- package/templates/auth/app/resources/pages/ForgotPassword.jsx +34 -0
- package/templates/auth/app/resources/pages/Login.jsx +36 -0
- package/templates/auth/app/resources/pages/NotFound.jsx +16 -0
- package/templates/auth/app/resources/pages/Profile.jsx +99 -0
- package/templates/auth/app/resources/pages/Register.jsx +50 -0
- package/templates/auth/app/resources/pages/ResetPassword.jsx +50 -0
- package/templates/auth/app/resources/routes.jsx +54 -0
- package/templates/auth/app/resources/spa.js +29 -0
- package/templates/auth/app/routes/api.js +17 -0
- package/templates/auth/app/routes/auth.js +13 -0
- package/templates/auth/app/routes/web.js +21 -0
- package/templates/auth/index.js +19 -0
- package/templates/auth/template.json +15 -0
- package/templates/blank/app/models/.gitkeep +0 -0
- package/templates/blank/app/resources/html/home.html +27 -0
- package/templates/blank/app/resources/html/partials/nav.html +1 -0
- package/templates/blank/app/resources/main.jsx +16 -0
- package/templates/blank/app/resources/pages/Home.jsx +42 -0
- package/templates/blank/app/resources/pages/NotFound.jsx +27 -0
- package/templates/blank/app/resources/routes.jsx +15 -0
- package/templates/blank/app/resources/spa.js +24 -0
- package/templates/blank/app/routes/api.js +11 -0
- package/templates/blank/app/routes/web.js +21 -0
- package/templates/blank/index.js +13 -0
- package/templates/blank/template.json +12 -0
- package/templates/blog/app/lib/blog.js +149 -0
- package/templates/blog/app/models/post.js +22 -0
- package/templates/blog/app/resources/html/home.html +28 -0
- package/templates/blog/app/resources/html/not-found.html +5 -0
- package/templates/blog/app/resources/html/partials/nav.html +2 -0
- package/templates/blog/app/resources/html/partials/post-card.html +9 -0
- package/templates/blog/app/resources/html/post.html +8 -0
- package/templates/blog/app/resources/layouts/AdminLayout.jsx +54 -0
- package/templates/blog/app/resources/main.jsx +18 -0
- package/templates/blog/app/resources/pages/Login.jsx +31 -0
- package/templates/blog/app/resources/pages/NotFound.jsx +16 -0
- package/templates/blog/app/resources/pages/PostEditor.jsx +51 -0
- package/templates/blog/app/resources/pages/Posts.jsx +83 -0
- package/templates/blog/app/resources/pages/Register.jsx +43 -0
- package/templates/blog/app/resources/routes.jsx +51 -0
- package/templates/blog/app/resources/spa.js +25 -0
- package/templates/blog/app/resources/styles.css +40 -0
- package/templates/blog/app/routes/api.js +77 -0
- package/templates/blog/app/routes/auth.js +10 -0
- package/templates/blog/app/routes/web.js +114 -0
- package/templates/blog/index.js +21 -0
- package/templates/blog/template.json +14 -0
- package/vite.config.js +11 -0
- package/app/views/components/Header.jsx +0 -42
- package/app/views/components/LiveCounter.jsx +0 -67
- package/app/views/layouts/main/view.jsx +0 -201
- package/app/views/legal/terms.html +0 -29
- package/app/views/pages/about.jsx +0 -98
- package/app/views/pages/dashboard.jsx +0 -278
- package/app/views/pages/index.jsx +0 -123
- package/app/views/pages/login.jsx +0 -141
- package/core/actions.d.ts +0 -4
- package/core/actions.js +0 -355
- package/core/jsx.d.ts +0 -38
- package/core/jsx.js +0 -1597
- package/core/vite.d.ts +0 -3
- package/public/js/bluebird-client.js +0 -3265
- package/public/js/tailwind.js +0 -8
package/AGENTS.md
CHANGED
|
@@ -1,620 +1,727 @@
|
|
|
1
|
-
# Bluebird.js Framework - AI Agent Guide
|
|
2
|
-
|
|
3
|
-
This document serves as the primary manual for any AI Agent interacting with the codebase. It details the architecture of Bluebird.js (`@seip/bluebird-js`), its internal modules, and how features should be written or modified.
|
|
4
|
-
|
|
5
|
-
## 1. Core Architecture
|
|
6
|
-
|
|
7
|
-
Bluebird.js is a performance-first web and API framework built on **Express** (Node.js 22.18+).
|
|
8
|
-
|
|
9
|
-
- **Entrypoint (`index.js`)**: Located at the project root. Initializes the server using `App` from `core/app.js` and registers the routes.
|
|
10
|
-
- **Application (`app/`)**: Application code — `app/routes/` (
|
|
11
|
-
- **Public assets (`public/`)**: Static files
|
|
12
|
-
- **
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
const
|
|
135
|
-
|
|
136
|
-
await
|
|
137
|
-
|
|
138
|
-
await User.
|
|
139
|
-
await User.
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
res.
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
res.ok(
|
|
215
|
-
});
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
await
|
|
263
|
-
});
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
```javascript
|
|
293
|
-
import
|
|
294
|
-
|
|
295
|
-
const
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
});
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
npx bluebird-js
|
|
328
|
-
npx bluebird-js
|
|
329
|
-
npx bluebird-js
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
Bluebird
|
|
337
|
-
|
|
338
|
-
-
|
|
339
|
-
|
|
340
|
-
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
}
|
|
377
|
-
});
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
- **
|
|
424
|
-
|
|
425
|
-
-
|
|
426
|
-
-
|
|
427
|
-
-
|
|
428
|
-
-
|
|
429
|
-
- **
|
|
430
|
-
-
|
|
431
|
-
- **
|
|
432
|
-
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
}
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
}
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
1
|
+
# Bluebird.js Framework - AI Agent Guide
|
|
2
|
+
|
|
3
|
+
This document serves as the primary manual for any AI Agent interacting with the codebase. It details the architecture of Bluebird.js (`@seip/bluebird-js`), its internal modules, and how features should be written or modified.
|
|
4
|
+
|
|
5
|
+
## 1. Core Architecture
|
|
6
|
+
|
|
7
|
+
Bluebird.js is a performance-first web and API framework built on **Express** (Node.js 22.18+). Public landing pages and SEO routes are server-rendered with **HTML `{{ }}` templates** (`app/resources/html/`), while interactive dashboards and applications run as client-rendered **React 19 + React Router** SPAs (`app/resources/`) mounted with **`router.spa()`**, bundled with **Vite 7**, and styled with **Tailwind CSS v4** (light and dark modes). It also provides JWT auth with role enforcement, multi-level caching, BaseModel, schema validation, database access, and queue processing out of the box.
|
|
8
|
+
|
|
9
|
+
- **Entrypoint (`index.js`)**: Located at the project root. Initializes the server using `App` from `core/app.js` and registers the routes.
|
|
10
|
+
- **Application (`app/`)**: Application code — `app/resources/` holds everything client-side: the React SPA (`index.html` shell, `spa.js` config, `main.jsx`, `routes.jsx`, `layouts/`, `pages/`), `styles.css` (Tailwind v4 entry), and `html/` (HTML `{{ }}` SSR views, `html/layouts/`, `html/partials/`). Server code lives in `app/routes/` (API, Auth, Web routes), `app/models/` (BaseModels), and `app/jobs/` (background workers).
|
|
11
|
+
- **Public assets (`public/`)**: Static files (`images/`, `js/bluebird.js` vanilla UI helpers). `public/build/` is generated by `npx bluebird-js build` (hashed client bundle and CSS manifest). Served directly by Nginx or Express fallback.
|
|
12
|
+
- **React & Vite runtime (`core/vite.js`, `core/vite-plugin.js`, `core/spa.js`, `core/react/client/`)**: `ViteBridge` manages Vite middleware in dev and `public/build/.vite/manifest.json` in production; `core/spa.js` powers `router.spa()` with per-URL SEO metadata, JSON-LD, and full-width `#root` skeletons; `core/react/client/` exports React UI components, `api`, `AuthProvider`, `RequireAuth`, `GuestOnly`, and `useTheme` as `@seip/bluebird-js/react`.
|
|
13
|
+
- **Core (`core/`)**: The framework core. Contains `Router`, `Render`, `Validator`, `Auth`, `Cache`, `Redis`, `Database`, `Model`, `Csrf`, `Hash`, `ViteBridge`, etc. **DO NOT MODIFY** the core unless explicitly requested.
|
|
14
|
+
|
|
15
|
+
## 2. Modern JavaScript Standard (ESM)
|
|
16
|
+
|
|
17
|
+
Bluebird.js standardizes on modern JavaScript (Node.js 22.18+ ESM) with JSDoc types. Server code (routes, models) runs directly in Node; React SPA modules and Tailwind CSS are compiled by Vite:
|
|
18
|
+
|
|
19
|
+
- **Development (`npm run dev` → `bluebird-js dev`)**: Express + Vite middleware on the same port (HMR / React Fast Refresh, on-the-fly Tailwind CSS v4, also injected into HTML `{{ }}` pages). The server restarts when any server file under `app/` changes (routes, models, jobs, `app/lib/`, `app/database.js`...), plus `index.js`, `.env`, and `app/resources/spa.js` (add more with `--watch dir`); client files in `app/resources/` are hot-reloaded by Vite instead; writes to `logs/`, `node_modules/`, or build output never restart it. Do not use `node --watch-path`: on some platforms it reports changes outside the watched paths (Vite's `node_modules/.vite-temp`, `logs/`) and restarts endlessly.
|
|
20
|
+
- **Build (`npx bluebird-js build`)**: Client SPA & CSS bundle in `public/build/` with `.vite/manifest.json`.
|
|
21
|
+
- **Static export (`npx bluebird-js export`)**: The React SPA as 100% static HTML/JS/CSS (`dist/client/`) for Electron, Capacitor, or static hosting.
|
|
22
|
+
- **Production Entrypoint (`index.js`)**: Run with `node --env-file=.env index.js` (`npm start`) or via PM2 cluster.
|
|
23
|
+
- **Initialization**: `npx bluebird-js` scaffolds a new project directly with `index.js` at the root, from a template: `--blank` (default: HTML page on `/` + one-page React SPA on `/app/*`), `--auth` (login, register, forgot/reset password, dashboard, profile), `--blog` (HTML blog with RSS and sitemap + React admin), `--api` (headless REST API with JWT and a CRUD example), or `--demo` (framework showcase). Templates live in `templates/` (`_base` and `_auth` are shared layers) and never overwrite existing files. Non-interactive: `npx bluebird-js --auth --yes --title "My App"`.
|
|
24
|
+
- **IDE Intellisense**: Powered by `core/index.d.ts` and `jsconfig.json`.
|
|
25
|
+
|
|
26
|
+
```javascript
|
|
27
|
+
import App from "@seip/bluebird-js/core/app.js";
|
|
28
|
+
import routerApi from "./app/routes/api.js";
|
|
29
|
+
import routerAuth from "./app/routes/auth.js";
|
|
30
|
+
import routerWeb from "./app/routes/web.js";
|
|
31
|
+
|
|
32
|
+
const app = new App({
|
|
33
|
+
routes: [routerWeb, routerAuth, routerApi],
|
|
34
|
+
port: process.env.PORT || 3000,
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
app.run();
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## 3. Routing (Router & `router.spa()`)
|
|
41
|
+
|
|
42
|
+
Do not use Express' native router directly. Always use Bluebird's `Router` wrapper.
|
|
43
|
+
|
|
44
|
+
```javascript
|
|
45
|
+
import Router from "@seip/bluebird-js/core/router.js";
|
|
46
|
+
|
|
47
|
+
const routerApi = new Router("/api");
|
|
48
|
+
|
|
49
|
+
routerApi.get("/users", (req, res) => {
|
|
50
|
+
res.json({ users: [] });
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
export default routerApi;
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
When created with `{ seo: true }`, static GET routes and static indexable `router.spa()` entries are tracked for `/sitemap.xml` and `/robots.txt`.
|
|
57
|
+
|
|
58
|
+
Mount a React Router SPA under any prefix with `router.spa(path, options)`:
|
|
59
|
+
|
|
60
|
+
```javascript
|
|
61
|
+
routerWeb.spa("/app", {
|
|
62
|
+
lang: "en",
|
|
63
|
+
titleTemplate: "%s — My App",
|
|
64
|
+
skeleton: "app",
|
|
65
|
+
meta: {
|
|
66
|
+
"*": { title: "Workspace", robots: "noindex, nofollow", skeleton: "app" },
|
|
67
|
+
"login": { title: "Sign In", description: "Access your account", robots: "index, follow", skeleton: "auth" },
|
|
68
|
+
"/app/register": { title: "Create Account", robots: "index, follow", skeleton: "auth" },
|
|
69
|
+
},
|
|
70
|
+
});
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## 4. Request Validation (Validator)
|
|
74
|
+
|
|
75
|
+
Incoming request data is validated using `core/validate.js`, which automatically returns HTTP 400 JSON responses on error. The validator inspects request payloads without destructively mutating raw data.
|
|
76
|
+
|
|
77
|
+
```javascript
|
|
78
|
+
import Validator from "@seip/bluebird-js/core/validate.js";
|
|
79
|
+
|
|
80
|
+
const userSchema = {
|
|
81
|
+
email: { required: true, email: true },
|
|
82
|
+
password: { required: true, min: 8 },
|
|
83
|
+
bio: { required: false },
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
const validateUser = new Validator(userSchema, "en");
|
|
87
|
+
|
|
88
|
+
routerApi.post("/users", validateUser.middleware(), (req, res) => {
|
|
89
|
+
res.json({ success: true });
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## 5. Lightweight BaseModel (Model)
|
|
94
|
+
|
|
95
|
+
> **Important Architecture Note:**
|
|
96
|
+
> Bluebird's `BaseModel` (`core/model.js`) is designed as a lightweight, built-in static facade for high performance, simple queries, soft deletes, and migrations.
|
|
97
|
+
> **For complex multi-tier enterprise ORM mapping, Prisma is recommended.**
|
|
98
|
+
|
|
99
|
+
### Defining a Model
|
|
100
|
+
|
|
101
|
+
Create models inside `app/models/`:
|
|
102
|
+
|
|
103
|
+
```javascript
|
|
104
|
+
import Model from "@seip/bluebird-js/core/model.js";
|
|
105
|
+
|
|
106
|
+
export default class User extends Model {
|
|
107
|
+
static table = "users";
|
|
108
|
+
static primaryKey = "id";
|
|
109
|
+
static timestamps = true;
|
|
110
|
+
static softDelete = true;
|
|
111
|
+
|
|
112
|
+
static schema = {
|
|
113
|
+
id: { type: "int", primary: true, auto: true },
|
|
114
|
+
name: { type: "string", length: 150, required: true },
|
|
115
|
+
email: { type: "string", length: 150, unique: true, required: true, email: true },
|
|
116
|
+
password: { type: "string", length: 255, required: true, min: 8, hidden: true, hash: true },
|
|
117
|
+
role: { type: "string", length: 20, default: "user", in: ["user", "admin"] },
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### CRUD Shortcuts & Query Facades
|
|
123
|
+
|
|
124
|
+
Every Model exposes direct shortcuts to database queries, transactions, and mutations:
|
|
125
|
+
|
|
126
|
+
```javascript
|
|
127
|
+
const total = await User.query("SELECT COUNT(*) as count FROM users", [], "return_row");
|
|
128
|
+
await User.transaction(async (tx) => {
|
|
129
|
+
await tx.query("UPDATE users SET role = ? WHERE id = ?", ["admin", 1]);
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
const userId = await User.create({ name: "Alice", email: "alice@example.com", password: "secretPassword" });
|
|
133
|
+
|
|
134
|
+
const user = await User.find(1, { cache: 60 });
|
|
135
|
+
const userWithPosts = await User.find(1, { oneMany: Post });
|
|
136
|
+
const postWithAuthor = await Post.find(10, { belongsTo: User });
|
|
137
|
+
|
|
138
|
+
const page = await User.paginate({ where: { role: "user" }, page: 1, limit: 10 });
|
|
139
|
+
await User.update(userId, { name: "Alice Smith" });
|
|
140
|
+
|
|
141
|
+
const totalUsers = await User.count({ role: "user" });
|
|
142
|
+
const exists = await User.exists({ email: "alice@example.com" });
|
|
143
|
+
|
|
144
|
+
const matching = await User.all({
|
|
145
|
+
where: {
|
|
146
|
+
id: [1, 2, 3],
|
|
147
|
+
role: { $ne: "banned" },
|
|
148
|
+
views: { $gt: 100 },
|
|
149
|
+
},
|
|
150
|
+
});
|
|
151
|
+
|
|
152
|
+
const userRecord = await User.firstOrCreate({ email: "john@example.com" }, { name: "John Doe" });
|
|
153
|
+
const updatedRecord = await User.updateOrCreate({ email: "john@example.com" }, { name: "Johnathan" });
|
|
154
|
+
|
|
155
|
+
await User.delete(userId);
|
|
156
|
+
await User.delete(userId, { force: true });
|
|
157
|
+
await User.delete(userId, { cascade: [Post] });
|
|
158
|
+
await User.restore(userId);
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## 6. CSRF Protection (Csrf)
|
|
162
|
+
|
|
163
|
+
Bluebird provides built-in HMAC-signed double-submit CSRF protection (`core/csrf.js`):
|
|
164
|
+
|
|
165
|
+
```javascript
|
|
166
|
+
import Csrf from "@seip/bluebird-js/core/csrf.js";
|
|
167
|
+
|
|
168
|
+
routerWeb.use(Csrf.middleware());
|
|
169
|
+
|
|
170
|
+
const token = Csrf.ensure(req, res); // Valid token for this request (issues the `_csrf` cookie when missing)
|
|
171
|
+
Csrf.verifyRequest(req); // Timing-safe cookie ↔ header/body check
|
|
172
|
+
Csrf.rotate(res); // Fresh token (done automatically by Auth.login / Auth.logout)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
- Tokens are accepted from the `X-CSRF-Token` header or the `_csrf` body field. **Query-string tokens are rejected.**
|
|
176
|
+
- The signing secret is `CSRF_SECRET` or `JWT_SECRET`. Without either, a random per-process secret is used (tokens do not survive restarts or validate across PM2 workers) and a warning is printed in production.
|
|
177
|
+
- Cached pages never leak tokens between visitors: the token is replaced by a placeholder before caching and restored per request.
|
|
178
|
+
|
|
179
|
+
## 7. Authentication & Password Hashing (Auth & Hash)
|
|
180
|
+
|
|
181
|
+
### Password Hashing (Hash)
|
|
182
|
+
|
|
183
|
+
Native password hashing using `node:crypto.scrypt` with random salt and timing-safe comparison (zero external npm dependencies required).
|
|
184
|
+
|
|
185
|
+
```javascript
|
|
186
|
+
import Hash from "@seip/bluebird-js/core/hash.js";
|
|
187
|
+
|
|
188
|
+
const hash = await Hash.make("mySecretPassword");
|
|
189
|
+
const isValid = await Hash.verify("mySecretPassword", hash);
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### JWT Handling (Auth)
|
|
193
|
+
|
|
194
|
+
Native JWT handling with AES-256-GCM encryption and HMAC-SHA256 signature verification using `node:crypto`, plus optional role enforcement and guest-friendly session inspection:
|
|
195
|
+
|
|
196
|
+
```javascript
|
|
197
|
+
import Auth from "@seip/bluebird-js/core/auth.js";
|
|
198
|
+
|
|
199
|
+
router.get("/profile", Auth.protect(), (req, res) => {
|
|
200
|
+
res.json({ user: req.user });
|
|
201
|
+
});
|
|
202
|
+
|
|
203
|
+
router.get("/admin/metrics", Auth.protect({ roles: ["admin", "editor"] }), (req, res) => {
|
|
204
|
+
res.ok({ metrics: true });
|
|
205
|
+
});
|
|
206
|
+
|
|
207
|
+
router.get("/session", Auth.optional(), (req, res) => {
|
|
208
|
+
res.ok({ user: req.user || null });
|
|
209
|
+
});
|
|
210
|
+
|
|
211
|
+
router.post("/login", async (req, res) => {
|
|
212
|
+
const user = { id: 1, name: "John", role: "user" };
|
|
213
|
+
await Auth.login(res, user);
|
|
214
|
+
res.ok(user, "Logged in");
|
|
215
|
+
});
|
|
216
|
+
|
|
217
|
+
router.post("/logout", async (req, res) => {
|
|
218
|
+
await Auth.logout(res);
|
|
219
|
+
res.ok(null, "Logged out");
|
|
220
|
+
});
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Project auth routes in `app/routes/auth.js` expose `/api/auth/me`, `/api/auth/login`, `/api/auth/logout`, and optional `/api/auth/register` via `createAuthRouter({ register: true })` (defaults to `register: false`). The auth and API routers apply `Csrf.middleware()`; bearer clients (`X-Auth-Mode: token`) receive `{ user, token }` instead of a cookie.
|
|
224
|
+
|
|
225
|
+
`Auth.configure({ resolveUser: async (payload, req) => user | null })` reloads the user on every `Auth.protect()` / `Auth.optional()` request after the token signature is checked: return the current user (fresh role) or `null` to reject the session; errors reject it too. The `auth`, `api`, and `blog` templates use it with a `session_version` column stored in the token as `sv`: password change/reset and `POST /api/auth/logout-all` increment it to revoke every existing session, `PUT /api/auth/password` returns a fresh session for the current device, and `PUT /api/auth/profile` requires `current_password` to change the email. Never trust roles from the token alone for sensitive actions.
|
|
226
|
+
|
|
227
|
+
## 8. HTTP Response Helpers & Health Check
|
|
228
|
+
|
|
229
|
+
Bluebird decorates the Express `res` object with standardized helper methods:
|
|
230
|
+
|
|
231
|
+
```javascript
|
|
232
|
+
res.ok(data, "Success message");
|
|
233
|
+
res.created(data, "Created successfully");
|
|
234
|
+
res.paginate(items, pagination, "Fetched");
|
|
235
|
+
|
|
236
|
+
res.badRequest("Invalid input", errors);
|
|
237
|
+
res.unauthorized("Authentication required");
|
|
238
|
+
res.forbidden("Access denied");
|
|
239
|
+
res.notFound("Resource not found");
|
|
240
|
+
res.serverError("Internal failure", err);
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Every Bluebird application provides a native `/api/health` endpoint returning uptime, timestamp, environment, and memory consumption.
|
|
244
|
+
|
|
245
|
+
Unknown routes get a 404: JSON (`{ message: "Not Found" }`) under `/api` or for JSON clients, and for browser requests the `app/resources/html/notFound.html` view (receives `{{ path }}`) rendered inside the `main` layout, falling back to a built-in page when the view does not exist. Unknown routes inside a `router.spa()` mount are handled by the React `NotFound` page (`{ path: "*" }` in `routes.jsx`). Disable it with `new App({ notFound: false })`.
|
|
246
|
+
|
|
247
|
+
## 9. Performance Caching (Cache & Redis)
|
|
248
|
+
|
|
249
|
+
Caching defaults to fast in-memory LRU storage, ideal for desktop applications and single or dual PM2 instances. Filesystem caching (`driver: "file"`) is available as persistent local fallback, and Redis (`driver: "redis"`) is isolated in `core/redis.js` on-demand for high-traffic environments.
|
|
250
|
+
|
|
251
|
+
```javascript
|
|
252
|
+
import Cache from "@seip/bluebird-js/core/cache.js";
|
|
253
|
+
|
|
254
|
+
router.get("/stats", Cache.middleware(60), (req, res) => {
|
|
255
|
+
res.ok({ usersCount: 150 });
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
await Cache.set("custom_key", { data: "value" }, 120, { driver: "memory" });
|
|
259
|
+
const cachedData = await Cache.get("custom_key", { driver: "memory" });
|
|
260
|
+
|
|
261
|
+
const stats = await Cache.deduplicate("stats-key", async () => {
|
|
262
|
+
return await calculateHeavyStats();
|
|
263
|
+
});
|
|
264
|
+
|
|
265
|
+
await Cache.delete("custom_key");
|
|
266
|
+
await Cache.clear();
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Render Cache & Query Parameters
|
|
270
|
+
|
|
271
|
+
HTML caches (`Render.cache(ttl)`, `Render.html(..., { cache: 300, cacheQuery: [...] })`, and `router.spa(..., { cache: 300 })`) key entries by **path only**. Requests carrying query parameters bypass the cache unless the parameter is allowlisted, preventing cache flooding with `?random=...` variants:
|
|
272
|
+
|
|
273
|
+
```javascript
|
|
274
|
+
routerWeb.get("/posts", (req, res) =>
|
|
275
|
+
Render.html(res, "posts", { posts }, { layout: "main", cache: 300, cacheQuery: ["page", "sort"] })
|
|
276
|
+
);
|
|
277
|
+
|
|
278
|
+
router.get("/posts", Render.cache(300, { query: ["page"] }), handler);
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Authenticated requests are never shared-cached. Cache keys include the full path (`baseUrl` + `path`) and the request language (`#lang=es` when not `en`). `req.lang` comes from `?lang=`, the body, or the `lang` cookie and only accepts BCP 47 style tags (`es`, `pt-BR`), falling back to `en`. Invalidate with `await Render.invalidate("/posts")`.
|
|
282
|
+
|
|
283
|
+
## 10. Database Module (database.js)
|
|
284
|
+
|
|
285
|
+
Bluebird provides a unified wrapper class (`core/database.js`) supporting **SQLite (native `node:sqlite` in Node 22.18+ with `better-sqlite3` fallback)**, **MySQL (`mysql2/promise`)**, and **PostgreSQL (`pg`)**:
|
|
286
|
+
|
|
287
|
+
- **Native SQLite by Default:** No native C++ compilation or build tools required.
|
|
288
|
+
- **SQLite Concurrency & WAL:** Automatically configures WAL mode, busy timeout, and memory-mapped I/O.
|
|
289
|
+
- **Prepared Statement Caching:** SQLite caches prepared statement ASTs automatically.
|
|
290
|
+
- **Query Caching:** Supports `{ cache: 60 }` across memory, file, and redis backends.
|
|
291
|
+
|
|
292
|
+
```javascript
|
|
293
|
+
import { Database, DB_TYPE } from "@seip/bluebird-js/core/database.js";
|
|
294
|
+
|
|
295
|
+
const connection = new Database(20);
|
|
296
|
+
|
|
297
|
+
const user = await connection.query("SELECT * FROM users WHERE id = ?", [1], "return_row");
|
|
298
|
+
const stats = await connection.query("SELECT COUNT(*) as cnt FROM logs", [], { cache: 60 });
|
|
299
|
+
|
|
300
|
+
await connection.transaction(async (tx) => {
|
|
301
|
+
const id = await tx.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
|
|
302
|
+
await tx.query("INSERT INTO profiles (user_id) VALUES (?)", [id]);
|
|
303
|
+
});
|
|
304
|
+
|
|
305
|
+
// Atomic, WAL-safe compressed database backup with retention rotation
|
|
306
|
+
const backup = await Database.backup({ out: "database/backups", keep: 10, compress: true });
|
|
307
|
+
|
|
308
|
+
// Integrity-verified restore with pre-restore safety snapshot
|
|
309
|
+
await Database.restore("database/backups/backup-sqlite-2026-11-03_170000_123.db.gz", {
|
|
310
|
+
safetyBackup: true,
|
|
311
|
+
verify: true,
|
|
312
|
+
});
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Backup rotation orders files by the timestamp in their name (equal `mtime` values on Windows/NTFS never drop the newest backup), never deletes the backup just created, and suffixes `-1`, `-2` on same-millisecond collisions.
|
|
316
|
+
|
|
317
|
+
## 11. On-Demand Modules & CLI Add
|
|
318
|
+
|
|
319
|
+
To keep dependencies lightweight and minimal, optional modules load dynamically on-demand:
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
npx bluebird-js add upload # Installs multer for file uploads
|
|
323
|
+
npx bluebird-js add ws # Installs ws for WebSockets
|
|
324
|
+
npx bluebird-js add redis # Installs redis for distributed caching
|
|
325
|
+
npx bluebird-js add sqlite # Installs better-sqlite3 (fallback for older environments)
|
|
326
|
+
npx bluebird-js add mysql # Installs mysql2
|
|
327
|
+
npx bluebird-js add postgres # Installs pg
|
|
328
|
+
npx bluebird-js add bcrypt # Installs bcrypt
|
|
329
|
+
npx bluebird-js add swagger # Installs swagger-ui-express & swagger-jsdoc
|
|
330
|
+
npx bluebird-js add helmet # Installs helmet
|
|
331
|
+
npx bluebird-js add ejs # Installs ejs
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
## 12. Security, Rate Limiting & SEO (Security Headers, Helmet, RateLimit, Seo)
|
|
335
|
+
|
|
336
|
+
Bluebird includes built-in security headers enabled by default (`X-Content-Type-Options: nosniff`, `X-XSS-Protection: 0`, `X-Frame-Options: SAMEORIGIN`, `Referrer-Policy: strict-origin-when-cross-origin`, `Permissions-Policy`).
|
|
337
|
+
|
|
338
|
+
### Content-Security-Policy with Nonces
|
|
339
|
+
|
|
340
|
+
Use `{nonce}` in the policy to get a random per-request nonce. It is exposed as `res.locals.cspNonce` and added automatically to every inline `<script>` and `<style>` tag of the documents Bluebird renders (HTML `{{ }}` views, `router.spa()` skeleton styles/scripts, and cached pages).
|
|
341
|
+
|
|
342
|
+
```javascript
|
|
343
|
+
const app = new App({
|
|
344
|
+
routes: [routerWeb, routerApi],
|
|
345
|
+
security: { csp: "default-src 'self'; script-src 'self' 'nonce-{nonce}'" },
|
|
346
|
+
});
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
### CORS
|
|
350
|
+
|
|
351
|
+
CORS is secure by default: `origin: "*"` never reflects the request origin and never sends `Access-Control-Allow-Credentials`. Credentialed cross-origin requests require an explicit allowlist:
|
|
352
|
+
|
|
353
|
+
```javascript
|
|
354
|
+
new App({ cors: { origin: ["https://app.example.com"], credentials: true } });
|
|
355
|
+
new App({ cors: { origin: (origin) => origin.endsWith(".example.com"), credentials: true } });
|
|
356
|
+
new App({ cors: false }); // disable CORS headers entirely
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
### Trusted Proxies & Client IP
|
|
360
|
+
|
|
361
|
+
`req.ip` (used by rate limits and logs) honors Express `trust proxy`. The default `trustProxy: "loopback, linklocal, uniquelocal"` trusts only a reverse proxy on the same host or a private network (Nginx from `npx bluebird-js nginx:conf`, Docker), so clients cannot spoof `X-Forwarded-For`. Behind a CDN pass its hop count or address list (`new App({ trustProxy: 2 })`); `true` trusts every hop and is unsafe when the app is reachable directly.
|
|
362
|
+
|
|
363
|
+
### JWT Secret
|
|
364
|
+
|
|
365
|
+
Set `JWT_SECRET` (32+ characters, generated by the scaffold). In production a missing or weak secret is never replaced by a known value: Bluebird uses a random per-process secret and logs an error, so sessions end on restart until you set it.
|
|
366
|
+
|
|
367
|
+
### Native Rate Limiting (`core/ratelimit.js`)
|
|
368
|
+
|
|
369
|
+
Configure rate limiting globally via `new App({ rateLimit })` or per-route via `App.rateLimit()` (supports `"memory"` and `"redis"` drivers). Every limiter keeps its own buckets (`prefix`), so a global and a per-route limiter never double count:
|
|
370
|
+
|
|
371
|
+
```javascript
|
|
372
|
+
import App from "@seip/bluebird-js/core/app.js";
|
|
373
|
+
|
|
374
|
+
const app = new App({
|
|
375
|
+
routes: [routerWeb, routerApi],
|
|
376
|
+
rateLimit: { max: 120, windowMs: 60000 },
|
|
377
|
+
});
|
|
378
|
+
|
|
379
|
+
routerApi.post("/login", App.rateLimit({ max: 5, windowMs: 60000 }), async (req, res) => {
|
|
380
|
+
res.ok({ authenticated: true });
|
|
381
|
+
});
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
### Automatic SEO Sitemap & Robots (`core/seo.js`)
|
|
385
|
+
|
|
386
|
+
When a `Router` is created with `{ seo: true }`, all static `GET` routes are automatically registered and exposed at `/sitemap.xml` and `/robots.txt` by `App`. Dynamic pages (e.g. blog posts) are added with `Seo.registerRoute("/", "/blog/my-post")` and removed with `Seo.unregisterRoute("/blog/my-post")`.
|
|
387
|
+
|
|
388
|
+
### Helmet Integration
|
|
389
|
+
|
|
390
|
+
Helmet can be applied per router when installed (`npx bluebird-js add helmet`):
|
|
391
|
+
|
|
392
|
+
```javascript
|
|
393
|
+
import App from "@seip/bluebird-js/core/app.js";
|
|
394
|
+
|
|
395
|
+
const apiRouter = new Router("/api");
|
|
396
|
+
apiRouter.use(App.helmet());
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
## 13. Production Deployment & Electron Desktop Mode
|
|
400
|
+
|
|
401
|
+
### PM2 & Nginx Reverse Proxy
|
|
402
|
+
|
|
403
|
+
Production deployments run directly via `npm start` or PM2 cluster mode:
|
|
404
|
+
|
|
405
|
+
```bash
|
|
406
|
+
npx bluebird-js make:ecosystem # Generates ecosystem.config.cjs
|
|
407
|
+
npx bluebird-js make:ecosystem --start # Generates and starts immediately in PM2
|
|
408
|
+
npx bluebird-js nginx:conf [domain] [port] [root] # Generates Nginx config with upstream keepalive & static try_files
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
For complete deployment details including Nginx reverse proxy configuration and optional standalone Docker snippet, consult [production.md](production.md).
|
|
412
|
+
|
|
413
|
+
### Electron & Desktop Mode (`desktop: true`)
|
|
414
|
+
|
|
415
|
+
Two ways to ship desktop/mobile apps from the same React code in `app/resources/`:
|
|
416
|
+
|
|
417
|
+
1. **Embedded server** (below): Electron runs the full Bluebird server locally (`app.runDesktop()`), including SQLite, HTML views, and the SPA.
|
|
418
|
+
2. **Static client** (`npx bluebird-js export`, section 16): Electron `loadFile()` or Capacitor loads a static HTML/JS/CSS build that calls a remote Bluebird `/api/` with bearer tokens.
|
|
419
|
+
|
|
420
|
+
Bluebird supports running embedded inside Electron or Tauri desktop applications where the application bundle (`.asar`) is read-only:
|
|
421
|
+
|
|
422
|
+
- **Base Directory Resolution (`appPath`)**: Accepts `appPath: electronApp.getAppPath()` (or `Config.setAppDir()`) to ensure views (`app/resources/html/`) and static assets (`public/`) resolve accurately regardless of shortcut launch locations (`process.cwd()`).
|
|
423
|
+
- **Writable User Data (`userDataPath`)**: Automatically routes SQLite database files, `logs/`, `app/cache/`, and file uploads (`Upload.storage()`) to `Config.userDataDir()` (`electronApp.getPath("userData")`), copying bundled initial SQLite template databases from `appPath`, `process.resourcesPath`, or `.asar.unpacked` on first launch.
|
|
424
|
+
- **Dynamic Port & LAN / QR Access**:
|
|
425
|
+
- By default, binds to `127.0.0.1` with dynamic port allocation (`port: 0`) via `await app.runDesktop()`.
|
|
426
|
+
- When `{ allowLan: true }` is enabled, binds to `0.0.0.0` and returns `{ server, port, url, lanUrl, lanIp }` ready for mobile QR code access on local WiFi.
|
|
427
|
+
- **Uploads & Static Serving**:
|
|
428
|
+
- In desktop mode, `Upload.storage()` writes to `userDataDir/uploads` and `App` automatically mounts `/uploads` to serve uploaded files statically without read-only filesystem errors.
|
|
429
|
+
- **Clean Shutdown & WAL Checkpoint**:
|
|
430
|
+
- Invoking `await app.close()` (e.g. in Electron `app.on("before-quit")`) automatically checkpoints SQLite WAL (`PRAGMA wal_checkpoint(TRUNCATE)`), closes open database handles via `Database.closeAll()`, and frees Windows file locks cleanly.
|
|
431
|
+
- **Packaging with electron-builder**:
|
|
432
|
+
- Recommended `electron-builder` configuration in `package.json`:
|
|
433
|
+
```json
|
|
434
|
+
"build": {
|
|
435
|
+
"asar": true,
|
|
436
|
+
"asarUnpack": ["app/resources/**/*", "database/**/*"]
|
|
437
|
+
}
|
|
438
|
+
```
|
|
439
|
+
- Run `npx bluebird-js build` before packaging: desktop mode serves the compiled SPA bundle and Tailwind CSS from `public/build/` (the generated `desktop:*` scripts already do it).
|
|
440
|
+
|
|
441
|
+
```javascript
|
|
442
|
+
import App from "@seip/bluebird-js/core/app.js";
|
|
443
|
+
import { app as electronApp, BrowserWindow } from "electron";
|
|
444
|
+
import routerApi from "./app/routes/api.js";
|
|
445
|
+
import routerAuth from "./app/routes/auth.js";
|
|
446
|
+
import routerWeb from "./app/routes/web.js";
|
|
447
|
+
|
|
448
|
+
const app = new App({
|
|
449
|
+
desktop: true,
|
|
450
|
+
appPath: electronApp.getAppPath(),
|
|
451
|
+
userDataPath: electronApp.getPath("userData"),
|
|
452
|
+
routes: [routerWeb, routerAuth, routerApi],
|
|
453
|
+
});
|
|
454
|
+
|
|
455
|
+
electronApp.whenReady().then(async () => {
|
|
456
|
+
const { url, port, lanUrl, lanIp } = await app.runDesktop({ allowLan: true });
|
|
457
|
+
const mainWindow = new BrowserWindow({ width: 1200, height: 800 });
|
|
458
|
+
mainWindow.loadURL(url);
|
|
459
|
+
|
|
460
|
+
electronApp.on("before-quit", async () => {
|
|
461
|
+
await app.close();
|
|
462
|
+
});
|
|
463
|
+
});
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## 14. Developer Tooling CLI
|
|
467
|
+
|
|
468
|
+
```bash
|
|
469
|
+
npx bluebird-js [--blank|--auth|--blog|--api|--demo] # Scaffolds a project from a template (default: blank)
|
|
470
|
+
npx bluebird-js doctor # Project diagnostics and HTTP smoke tests
|
|
471
|
+
npx bluebird-js make:model <Name> # BaseModel scaffolding
|
|
472
|
+
npx bluebird-js make:route <name> # REST route scaffolding
|
|
473
|
+
npx bluebird-js make:route <name> --auth # Authenticated REST route scaffolding
|
|
474
|
+
npx bluebird-js build # Vite build: client SPA + Tailwind CSS in public/build/
|
|
475
|
+
npx bluebird-js export [--api url] [--out dir] # Static React export (Electron, Capacitor, static hosts)
|
|
476
|
+
npx bluebird-js make:view <name> [--partial|--layout] # HTML {{ }} template scaffolding in app/resources/html/
|
|
477
|
+
npx bluebird-js make:migration [name] # Smart auto-migration from app/models/
|
|
478
|
+
npx bluebird-js make:migration --model <Model> # Auto DDL migration for specific Model schema
|
|
479
|
+
npx bluebird-js migrate [--yes] # Executes pending migrations with auto-detection
|
|
480
|
+
npx bluebird-js migrate:status # Displays applied batches
|
|
481
|
+
npx bluebird-js migrate:rollback # Reverts latest batch
|
|
482
|
+
npx bluebird-js make:seed <name> # Database seed file creation
|
|
483
|
+
npx bluebird-js seed # Executes database seeds
|
|
484
|
+
npx bluebird-js db:backup [--keep 10] [--out dir] # Compressed WAL-safe database backup with retention rotation
|
|
485
|
+
npx bluebird-js dev [entry] [--watch dir] # Dev server (Vite HMR) restarting only on server file changes
|
|
486
|
+
npx bluebird-js db:restore <file> [--yes] # Safe database restore with pre-backup & integrity check
|
|
487
|
+
npx bluebird-js nginx:conf [domain] [port] [root] # Generates Host Nginx reverse proxy
|
|
488
|
+
npx bluebird-js make:ecosystem [--start] # Generates PM2 cluster configuration
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
## 15. Background Jobs & Queue (Queue)
|
|
492
|
+
|
|
493
|
+
Lightweight background worker (`core/queue.js`) backed by Redis with automatic in-memory fallback.
|
|
494
|
+
|
|
495
|
+
```javascript
|
|
496
|
+
import Queue from "@seip/bluebird-js/core/queue.js";
|
|
497
|
+
|
|
498
|
+
Queue.process("sendWelcomeEmail", async (payload) => {
|
|
499
|
+
console.log(`Sending email to ${payload.email}...`);
|
|
500
|
+
});
|
|
501
|
+
|
|
502
|
+
await Queue.dispatch("sendWelcomeEmail", { email: "user@example.com" });
|
|
503
|
+
await Queue.work();
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
## 16. HTML `{{ }}` SSR Rendering & React Router SPA (`router.spa()`)
|
|
507
|
+
|
|
508
|
+
Bluebird cleanly separates **SEO server-rendered HTML** from **client-side React applications**:
|
|
509
|
+
|
|
510
|
+
1. **HTML `{{ }}` SSR (`app/resources/html/`)**: Express routes call `Render.html(res, "view", data, { layout, cache })`. Ideal for landing pages, storefronts, marketing pages, and emails.
|
|
511
|
+
2. **React Router SPA (`router.spa()`)**: Serves the React shell `app/resources/index.html` (built-in default when missing) with per-URL SEO tags (`title`, `description`, `keywords`, `canonical`, Open Graph, `robots`, `jsonld`), custom scripts/styles, and a full-width inline skeleton inside `<div id="root">`. React mounts on the client with zero server state embedded, so the same code is exported unchanged with `npx bluebird-js export`.
|
|
512
|
+
|
|
513
|
+
Everything client-side lives in `app/resources/`. The two HTML entry points are intentionally separate files:
|
|
514
|
+
|
|
515
|
+
- `app/resources/index.html`: React SPA shell (`router.spa()` and `npx bluebird-js export`).
|
|
516
|
+
- `app/resources/html/layouts/main.html`: HTML `{{ }}` SSR layout (`Render.html(..., { layout: "main" })`).
|
|
517
|
+
|
|
518
|
+
```
|
|
519
|
+
app/
|
|
520
|
+
├── resources/
|
|
521
|
+
│ ├── index.html (React SPA shell: {{{ head }}}, {{{ skeleton }}}, {{{ scripts }}})
|
|
522
|
+
│ ├── spa.js (SPA config: mount, title, meta tree; used by router.spa() and export)
|
|
523
|
+
│ ├── styles.css (Tailwind v4 entry shared by HTML views and React)
|
|
524
|
+
│ ├── main.jsx (createRoot + AuthProvider + RouterProvider, imports ./styles.css)
|
|
525
|
+
│ ├── routes.jsx (createRouter + lazy routes)
|
|
526
|
+
│ ├── layouts/AppLayout.jsx (React layouts)
|
|
527
|
+
│ ├── pages/ (Home.jsx, Login.jsx, Register.jsx, Dashboard.jsx, NotFound.jsx)
|
|
528
|
+
│ └── html/
|
|
529
|
+
│ ├── layouts/main.html (HTML SSR layout with {{{ body }}})
|
|
530
|
+
│ ├── partials/ ({{> partialName }})
|
|
531
|
+
│ ├── home.html (HTML {{ }} SSR page)
|
|
532
|
+
│ ├── terms.html
|
|
533
|
+
│ └── notFound.html (404 page for unknown non-/api routes)
|
|
534
|
+
├── routes/ (web.js, auth.js, api.js)
|
|
535
|
+
└── models/ (user.js)
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
### HTML Template Syntax (`core/render.js`)
|
|
539
|
+
|
|
540
|
+
| Syntax | Behavior |
|
|
541
|
+
|---|---|
|
|
542
|
+
| `{{ var }}` / `{{ user.name }}` | Escaped HTML interpolation (`SafeHtml` from `html\`...\`` inserts unescaped) |
|
|
543
|
+
| `{{{ rawHtml }}}` | Raw unescaped interpolation |
|
|
544
|
+
| `{{#if cond}} … {{else}} … {{/if}}` | Conditionals (also `{{if cond}}`, `!cond`, `===`, `!==`) |
|
|
545
|
+
| `{{#each items}} … {{else}} … {{/each}}` | Loops (supports `this`, `@index`, `@number`, `@first`, `@last`, `../parent`) |
|
|
546
|
+
| `{{> header }}` | Includes `app/resources/html/partials/header.html` |
|
|
547
|
+
| `{{ vite "app/resources/styles.css" }}` | Emits Vite dev link or hashed production manifest tags |
|
|
548
|
+
| `{{ lang }}`, `{{ csrf }}`, `{{{ csrfField }}}` | Automatically injected request context |
|
|
549
|
+
| `\{{ literal }}` | Backslash escape: prints `{{ literal }}` as text |
|
|
550
|
+
|
|
551
|
+
```javascript
|
|
552
|
+
routerWeb.get("/", (req, res) =>
|
|
553
|
+
Render.html(
|
|
554
|
+
res,
|
|
555
|
+
"home",
|
|
556
|
+
{
|
|
557
|
+
title: "Storefront",
|
|
558
|
+
clientsHtml: clients.map((c) => `<span>${escapeHtml(c.name)}</span>`).join(""),
|
|
559
|
+
},
|
|
560
|
+
{ layout: "main", cache: 300, cacheQuery: ["page"] }
|
|
561
|
+
)
|
|
562
|
+
);
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
### `router.spa()` SEO Meta Tree & Skeleton
|
|
566
|
+
|
|
567
|
+
The SPA configuration lives in `app/resources/spa.js` so the web server and the static export share it:
|
|
568
|
+
|
|
569
|
+
```javascript
|
|
570
|
+
// app/resources/spa.js
|
|
571
|
+
export default {
|
|
572
|
+
mount: "/app",
|
|
573
|
+
lang: "en",
|
|
574
|
+
titleTemplate: "%s — My App",
|
|
575
|
+
head: [{ tag: "link", rel: "icon", href: "/images/favicon.ico" }],
|
|
576
|
+
skeleton: "app",
|
|
577
|
+
meta: {
|
|
578
|
+
"*": { title: "Workspace", robots: "noindex, nofollow", skeleton: "app" },
|
|
579
|
+
"/": { title: "Home", description: "App workspace", robots: "index, follow", skeleton: "page" },
|
|
580
|
+
"login": { title: "Sign In", keywords: "login, auth", skeleton: "auth", jsonld: { "@type": "WebPage" } },
|
|
581
|
+
"/app/register": { title: "Register", skeleton: "auth" },
|
|
582
|
+
"users/:id": (req, params) => ({ title: `User ${params.id}` }),
|
|
583
|
+
},
|
|
584
|
+
};
|
|
585
|
+
|
|
586
|
+
// app/routes/web.js
|
|
587
|
+
import spa from "../resources/spa.js";
|
|
588
|
+
routerWeb.spa(spa.mount, spa);
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
- Keys inside `meta` accept both **relative** (`"login"`) and **absolute** (`"/app/login"`) forms, plus `"*"` wildcard and dynamic functions.
|
|
592
|
+
- `entry` defaults to `app/resources/main.jsx` (which imports `./styles.css`), `template` defaults to `app/resources/index.html` (`false` = built-in shell), and `styles` adds extra stylesheets.
|
|
593
|
+
- Built-in inline skeleton variants (`"app"`, `"auth"`, `"page"`, `false`, or custom HTML) fill `<div id="root" class="w-full min-h-screen">` so layout width stays locked before React mounts.
|
|
594
|
+
- Static non-`noindex` entries automatically register in `/sitemap.xml` when `seo: true`.
|
|
595
|
+
|
|
596
|
+
### React Router (`createRouter`)
|
|
597
|
+
|
|
598
|
+
```javascript
|
|
599
|
+
import { createRouter } from "@seip/bluebird-js/react";
|
|
600
|
+
|
|
601
|
+
export const router = createRouter(routes, { basename: "/app" });
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
Uses `createBrowserRouter` with `basename` when served by `router.spa()`, and `createHashRouter` in static exports or under `file://` (Electron `loadFile`). Force a mode with `{ mode: "browser" | "hash" | "memory" }`.
|
|
605
|
+
|
|
606
|
+
### Static Export (`npx bluebird-js export`) for Electron, Capacitor & Static Hosts
|
|
607
|
+
|
|
608
|
+
Builds the same React code, `index.html` shell, and `spa.js` metadata into a 100% static HTML/JS/CSS folder (no Node server inside the app):
|
|
609
|
+
|
|
610
|
+
```bash
|
|
611
|
+
npx bluebird-js export --api https://api.example.com # dist/client/index.html (hash router, ./ assets)
|
|
612
|
+
npx bluebird-js export --out mobile/www --api https://api.example.com
|
|
613
|
+
npx bluebird-js export --router browser --base / --out dist/web # static host with history fallback
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
| Option | Default | Purpose |
|
|
617
|
+
|---|---|---|
|
|
618
|
+
| `--out <dir>` | `dist/client` | Output folder (refuses `app/`, `core/`, `public/`, or the project root) |
|
|
619
|
+
| `--api <url>` | `EXPORT_API_URL` or `APP_URL` | Base URL prepended by `api()` to `/api/*` |
|
|
620
|
+
| `--router <mode>` | `hash` | `hash` (works with `file://`), `browser`, or `memory` |
|
|
621
|
+
| `--base <path>` | `./` (`/` for browser) | Asset base URL; root-absolute `src`/`href` in the shell are rebased |
|
|
622
|
+
| `--auth <mode>` | `token` | `token` = `Authorization: Bearer` stored in `localStorage`; `cookie` = same-site cookies |
|
|
623
|
+
| `--config <file>` | `app/resources/spa.js` | SPA config module |
|
|
624
|
+
| `--no-public` | | Skip copying `public/` into the output |
|
|
625
|
+
|
|
626
|
+
- **Electron (static)**: `mainWindow.loadFile("dist/client/index.html")`. **Electron (embedded server)** keeps working with `desktop: true` and `app.runDesktop()` (section 13).
|
|
627
|
+
- **Capacitor**: `"webDir": "dist/client"` in `capacitor.config.json`, then `npx cap sync`.
|
|
628
|
+
- **Auth from exports**: `AuthProvider` sends `X-Auth-Mode: token`; `/api/auth/login` and `/register` return `{ user, token }` without cookies, and `Csrf.middleware()` exempts bearer requests that carry no auth cookie. Default CORS (`origin: "*"`, no credentials) already allows these requests.
|
|
629
|
+
- `isExported()` / `getExportConfig()` let components hide web-only UI (e.g. links to HTML pages).
|
|
630
|
+
|
|
631
|
+
### React Client API (`@seip/bluebird-js/react`)
|
|
632
|
+
|
|
633
|
+
| Export | Purpose |
|
|
634
|
+
|---|---|
|
|
635
|
+
| `api` (`get`, `post`, `put`, `patch`, `delete`), `ApiError`, `setApiBaseUrl`, `configureApi({ baseUrl, auth })` | Fetch helper with `X-CSRF-Token` (cookie mode) or bearer token (token mode), and `Validator` error normalization |
|
|
636
|
+
| `createRouter`, `isExported`, `getExportConfig`, `getAuthToken`, `setAuthToken`, `getAuthMode` | Router factory and static export helpers |
|
|
637
|
+
| `AuthProvider`, `useAuth`, `RequireAuth`, `GuestOnly` | Session sync with `/api/auth/me` and optional role guards (`roles={["admin"]}`) |
|
|
638
|
+
| `Link`, `Button`, `buttonVariants`, `Form`, `SubmitButton`, `Input`, `Textarea`, `Select`, `Card`, `Badge`, `Carousel`, `Modal`, `Drawer`, `Skeleton`, `PageSkeleton`, `ProgressBar`, `Spinner`, `Toaster`, `toast`, `ThemeToggle`, `useTheme`, `cn` | React UI kit built on the design system below (light + dark) |
|
|
639
|
+
| `DataTable`, `normalizeTableResponse` | Responsive table: search, sort, pagination with page sizes, view/edit/delete (confirmed) and custom actions, cards with details on narrow containers; local `rows` or server `url` (`?page&limit&search&sort&order`, reads `res.paginate()` / `Model.paginate()`), `ref.reload()` |
|
|
640
|
+
| `useLocale`, `t`, `setLocale`, `getLocale`, `addMessages`, `MESSAGES` | Component UI strings in the page language (`<html lang>`): `en`, `es`, `pt`, `fr`, `de`, `it`, with base-language and English fallback |
|
|
641
|
+
|
|
642
|
+
### Vanilla Browser Helpers (`public/js/bluebird.js`)
|
|
643
|
+
|
|
644
|
+
Includes `[data-datatable]` (same DataTable for HTML views: config in a child `<script type="application/json">` built with `safeJson()`, `data-url`, `format` for badge/number/currency/date cells, `{ action: "delete", url }` with a native confirm dialog and CSRF, `bluebird:datatable` events, and `Bluebird.dataTable(el, options)`), event-delegated `[data-carousel]`, `[data-toast]`, `[data-modal]` / `[data-modal-open]`, `[data-dropdown]`, `[data-tabs]`, `[data-theme-toggle]`, `[data-copy]`, `[data-confirm]`, `[data-password-toggle]`, and `form[data-form]` (CSRF-aware fetch with inline field errors). Exposed globally as `window.Bluebird` (including `Bluebird.i18n.t / addMessages / setLocale`). Including the script twice is harmless: the second copy is ignored.
|
|
645
|
+
|
|
646
|
+
Built-in component strings (toast badges such as `Correcto` / `Cuidado` in Spanish, close buttons, carousel controls, error fallbacks) follow `<html lang>` in both the React kit and `public/js/bluebird.js`. Never hardcode those labels in components; add new keys to `core/react/client/i18n.js` and the identical `MESSAGES` object in `public/js/bluebird.js` (the regression suite checks they match).
|
|
647
|
+
|
|
648
|
+
### Development & Production
|
|
649
|
+
|
|
650
|
+
```bash
|
|
651
|
+
npm run dev # bluebird-js dev: Express + Vite on one port (HMR + Tailwind v4), restarts on server file changes
|
|
652
|
+
npx bluebird-js build # Builds client SPA & CSS bundle to public/build/
|
|
653
|
+
npm start # Production server reading public/build/.vite/manifest.json
|
|
654
|
+
npx bluebird-js export # Static React build (dist/client) for Electron, Capacitor, or static hosting
|
|
655
|
+
```
|
|
656
|
+
|
|
657
|
+
## 17. Unified AI Client (AI & core/ai.js)
|
|
658
|
+
|
|
659
|
+
Bluebird includes a built-in unified AI client (`core/ai.js`) supporting **DeepSeek (default)**, **Google Gemini**, and **OpenAI** out of the box with no provider SDKs required. It features automated PII data masking, 0ms prompt caching, sliding window rate limiting ("Anti-Quiebra"), and structured JSON extraction with schema validation:
|
|
660
|
+
|
|
661
|
+
- **DeepSeek by Default**:
|
|
662
|
+
- Base URL `https://api.deepseek.com`, model `deepseek-flash` (served by DeepSeek-V4.1-Flash-1017; legacy names `deepseek-v4-flash`, `deepseek-chat` supported).
|
|
663
|
+
- OpenAI-compatible format with optional thinking/reasoning mode (`thinking: { type: "enabled" }`, `reasoningEffort: "high"`).
|
|
664
|
+
- **Google Gemini**:
|
|
665
|
+
- REST API with `gemini-3.5-flash` (default), `gemini-3.8-flash`, `gemini-2.5-flash`, etc.
|
|
666
|
+
- **OpenAI & Custom Endpoints**:
|
|
667
|
+
- Compatible with `gpt-4o-mini`, `gpt-4o`, Ollama, OpenRouter, and custom endpoints via `baseURL`.
|
|
668
|
+
- **Accurate Real Client IP Detection (`getClientIp`)**:
|
|
669
|
+
- Extracts real visitor IP behind Cloudflare (`cf-connecting-ip`, `true-client-ip`), Nginx (`x-real-ip`), and proxy chains (`x-forwarded-for`), and normalizes IPv6 mappings (`::ffff:`). Proxy headers are only trusted when the request comes from a local/private reverse proxy, so direct clients cannot spoof them to bypass rate limits.
|
|
670
|
+
- **Reversible Sensitive Data Masking (PII)**:
|
|
671
|
+
- Personal values (`sensitiveKeys`) in context data and prompt text are replaced with anonymous deterministic tokens (`[name_01]`, `[email_01]`, `[dni_01]`) before leaving the server.
|
|
672
|
+
- Responses (`result.text`) are returned fully restored with original user values.
|
|
673
|
+
- **0ms Prompt Cache Synergy**:
|
|
674
|
+
- Cache hashes are computed against the *anonymized* prompt. Two different users asking the same query template trigger an immediate 0ms, $0 latency/cost Cache Hit with their unique personal values restored cleanly.
|
|
675
|
+
- **Sliding Window Rate Limiting ("Anti-Quiebra")**:
|
|
676
|
+
- Protects API budgets with minute/day limits (e.g. `{ minute: 6, day: 30 }` or `{ max: 15, windowMs: 60000 }`), returning HTTP 429 clean responses before depleting credits.
|
|
677
|
+
- Express route protection middleware available via `ai.protect()`.
|
|
678
|
+
- **Response Streaming & SSE (`ai.pipe` & `askStream`)**:
|
|
679
|
+
- Stream tokens in real time directly to Express responses via `await ai.pipe(res, prompt, { sse: true })` with automatic Nginx anti-buffering (`X-Accel-Buffering: no`), or iterate manually via `for await (const chunk of ai.askStream(prompt))`.
|
|
680
|
+
|
|
681
|
+
```javascript
|
|
682
|
+
import AI, { ai } from "@seip/bluebird-js/core/ai.js";
|
|
683
|
+
|
|
684
|
+
const supportAi = new AI({
|
|
685
|
+
provider: "deepseek", // "deepseek" (default) | "gemini" | "openai" | "custom"
|
|
686
|
+
model: "deepseek-flash", // default model
|
|
687
|
+
rateLimit: { minute: 6, day: 30 }, // Sliding window protection
|
|
688
|
+
cacheTtl: 3600, // Cache responses for 1 hour
|
|
689
|
+
});
|
|
690
|
+
|
|
691
|
+
routerApi.post("/support/reply", supportAi.protect(), async (req, res) => {
|
|
692
|
+
const userData = {
|
|
693
|
+
name: "Maria Garcia",
|
|
694
|
+
email: "maria@example.com",
|
|
695
|
+
dni: "45123987",
|
|
696
|
+
issue: "Need help updating billing details",
|
|
697
|
+
};
|
|
698
|
+
|
|
699
|
+
const result = await supportAi.ask("Draft a courteous support reply for this user:", {
|
|
700
|
+
data: userData,
|
|
701
|
+
sensitiveKeys: ["name", "email", "dni"], // Masked to [name_01], [email_01], [dni_01] before sending!
|
|
702
|
+
request: req, // Automatic IP rate limiting
|
|
703
|
+
json: true,
|
|
704
|
+
});
|
|
705
|
+
|
|
706
|
+
// result.text is returned fully restored with 'Maria Garcia' and 'maria@example.com'!
|
|
707
|
+
res.ok(result);
|
|
708
|
+
});
|
|
709
|
+
|
|
710
|
+
// Stream real-time Server-Sent Events (SSE) directly to Express client response
|
|
711
|
+
routerApi.post("/support/stream", async (req, res) => {
|
|
712
|
+
await supportAi.pipe(res, req.body.message, { sse: true, request: req });
|
|
713
|
+
});
|
|
714
|
+
|
|
715
|
+
// Or iterate chunks manually via async generator
|
|
716
|
+
for await (const chunk of supportAi.askStream("Explain quantum computing in simple terms")) {
|
|
717
|
+
process.stdout.write(chunk.text);
|
|
718
|
+
}
|
|
719
|
+
```
|
|
720
|
+
|
|
721
|
+
## 18. AI Development Guidelines
|
|
722
|
+
|
|
723
|
+
1. **Views & Client SPA**: HTML `{{ }}` SSR views live in `app/resources/html/` (served via `Render.html()`, `Render.send()`, `Render.partial()`, or `Render.view()`), while React Router client code lives in `app/resources/` (shell `index.html`, config `spa.js`, mounted with `router.spa()` and exported with `npx bluebird-js export`). Static assets live in `public/`. Keep React code free of server-injected state so it stays exportable.
|
|
724
|
+
2. **JSON Responses**: Use decorated `res.ok()`, `res.created()`, `res.badRequest()`, etc.
|
|
725
|
+
3. **No inline comments**: Preserve code cleanliness. Use **ONLY JSDoc comments** (`/** ... */`).
|
|
726
|
+
4. **All documentation in English**.
|
|
727
|
+
5. **Styling**: Tailwind CSS v4 with the Bluebird design system (`core/react/client/theme.css`, injected by the Vite plugin after `@import "tailwindcss"`). Use semantic tokens (`bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-primary`, `text-destructive`) instead of raw palette colors such as `slate-*` or `sky-*`, so light and dark modes work without `dark:` variants. In HTML views use the component classes (`btn btn-primary|secondary|outline|ghost|danger|link`, `btn-sm|lg|icon`, `card`, `card-title`, `card-description`, `field`, `field-label`, `badge` + `badge-dot`, `nav-link`, `glass`, `bg-app`, `brand`); in React use `Button`, `Card`, `Input`, `Badge`, and `buttonVariants()` for links styled as buttons. Keep color minimal: one `primary` action per view, `secondary`/`outline`/`ghost` for the rest, `danger` for destructive actions, `brand` only for the logo, and tones as a small dot (badges, toasts). Projects customize the theme by overriding the CSS variables (`:root { --primary: ... }`, `.dark { ... }`), or disable it with `bluebird({ theme: false })`. Reuse the components from `@seip/bluebird-js/react` and `public/js/bluebird.js` before writing new ones.
|