@seip/bluebird-js 0.1.6 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.vscode/extensions.json +7 -7
- package/.vscode/settings.json +10 -10
- package/AGENTS.md +266 -116
- package/README.md +258 -245
- package/app/models/user.js +19 -0
- package/app/resources/html/home.html +137 -0
- package/app/resources/html/layouts/main.html +54 -0
- package/app/resources/html/notFound.html +14 -0
- package/app/resources/html/terms.html +46 -0
- package/app/resources/index.html +27 -0
- package/app/resources/layouts/AppLayout.jsx +89 -0
- package/app/resources/main.jsx +18 -0
- package/app/resources/pages/Dashboard.jsx +98 -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/routes.jsx +54 -0
- package/app/resources/spa.js +67 -0
- package/app/resources/styles.css +9 -0
- package/app/routes/api.js +85 -50
- package/app/routes/auth.js +209 -0
- package/app/routes/web.js +49 -37
- package/core/ai.d.ts +151 -151
- package/core/ai.js +1071 -1051
- package/core/app.d.ts +2 -18
- package/core/app.js +978 -792
- package/core/auth.d.ts +2 -13
- package/core/auth.js +444 -326
- package/core/cli/backup.js +167 -167
- 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 +101 -332
- package/core/cli/nginx.js +1 -1
- package/core/cli/templates.js +139 -0
- package/core/cli/view.js +73 -136
- package/core/config.js +44 -2
- package/core/csrf.js +156 -24
- package/core/database.js +737 -684
- package/core/debug.js +1 -1
- package/core/html.js +8 -1
- package/core/index.d.ts +1286 -1431
- package/core/paths.js +55 -0
- package/core/ratelimit.js +10 -1
- package/core/react/client/api.js +237 -0
- package/core/react/client/auth.js +236 -0
- package/core/react/client/components.js +1321 -0
- package/core/react/client/i18n.js +338 -0
- package/core/react/client/index.d.ts +249 -0
- package/core/react/client/index.js +49 -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 +613 -603
- 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 +81 -455
- 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 +1160 -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/about.jsx +0 -98
- package/app/views/components/Header.jsx +0 -42
- package/app/views/components/LiveCounter.jsx +0 -66
- package/app/views/dashboard.jsx +0 -300
- package/app/views/index.jsx +0 -123
- package/app/views/layouts/main/view.jsx +0 -201
- package/app/views/legal/terms.html +0 -29
- package/app/views/login.jsx +0 -141
- package/core/actions.d.ts +0 -4
- package/core/actions.js +0 -329
- package/core/jsx.d.ts +0 -38
- package/core/jsx.js +0 -1432
- package/core/vite.d.ts +0 -3
- package/public/js/bluebird-client.js +0 -3161
- package/public/js/tailwind.js +0 -8
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Bluebird.js Framework
|
|
2
2
|
|
|
3
|
-
**Performance-first Node.js
|
|
3
|
+
**Performance-first Node.js framework: Express + HTML `{{ }}` SSR templates + React Router SPA with Vite, Tailwind CSS v4, JWT auth with roles, BaseModel, smart migrations, and multi-level caching.**
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@seip/bluebird-js)
|
|
6
6
|
[](https://opensource.org/licenses/MIT)
|
|
@@ -10,24 +10,23 @@
|
|
|
10
10
|
|
|
11
11
|
## Introduction
|
|
12
12
|
|
|
13
|
-
Bluebird.js (`@seip/bluebird-js`) is a high-performance web and API framework built on Express (Node.js 22.18+).
|
|
13
|
+
Bluebird.js (`@seip/bluebird-js`) is a high-performance web and API framework built on Express (Node.js 22.18+). Public landings and SEO pages render cleanly on the server with **HTML `{{ }}` templates** (`app/resources/html/`), while interactive dashboards and web applications run as **client-rendered React 19 + React Router SPAs** mounted via `router.spa()`, bundled with Vite and styled with Tailwind CSS v4 (dark and light themes). It ships with JWT authentication (with optional role checks and `/api/auth/*` routes), vanilla HTML UI helpers (`public/js/bluebird.js`), Tailwind React components, multi-driver caching (in-memory LRU, filesystem, and Redis), BaseModel with smart migrations, CSRF protection, background queues, and PM2 production clustering.
|
|
14
14
|
|
|
15
15
|
### Key Highlights
|
|
16
16
|
|
|
17
|
-
- **
|
|
18
|
-
-
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **
|
|
22
|
-
- **
|
|
17
|
+
- **HTML `{{ }}` SSR Engine:** Fast `.html` views, layouts (`{{{ body }}}`), partials (`{{> name }}`), `{{if}}`/`{{else}}`, `{{each}}`, raw `{{{ html }}}`, and `{{ vite "app/resources/styles.css" }}`, and `\{{ literal }}` escapes.
|
|
18
|
+
- **React Router SPA (`router.spa()`):** Serves the React shell `app/resources/index.html` with per-URL SEO metadata (`title`, `description`, `keywords`, `canonical`, Open Graph, `robots`, `jsonld`), custom scripts/styles, and a full-width anti-CLS skeleton inside `<div id="root">`.
|
|
19
|
+
- **One React Codebase, Web + Desktop + Mobile:** Zero server-injected props in the SPA — React talks directly to `/api/*` via `api()`. `npx bluebird-js export` turns the same code into a 100% static HTML/JS/CSS build for Electron (`loadFile`), Capacitor, or any static host, with bearer-token auth against your Bluebird API.
|
|
20
|
+
- **Vite & Tailwind CSS v4:** Vite middleware HMR on the same port as Express in development; client bundle + manifest in `public/build/` via `npx bluebird-js build`. Built-in dark and light theme synchronization.
|
|
21
|
+
- **AuthProvider & Role Guards:** Client `AuthProvider`, `useAuth()`, `RequireAuth` (with optional `roles`), `GuestOnly`, plus default `/api/auth/login`, `/logout`, `/me`, and optional `/register`.
|
|
22
|
+
- **UI Kits for Both Worlds:** React UI components (`Link`, `Button`, `Form`, `Input`, `Select`, `Textarea`, `Card`, `Badge`, `Carousel`, `Modal`, `Drawer`, `Skeleton`, `ThemeToggle`, `Toaster` / `toast`) and dependency-free vanilla `public/js/bluebird.js` (`data-carousel`, `data-toast`, `data-modal`, `data-dropdown`, `data-tabs`, `data-theme-toggle`, `data-form`).
|
|
23
23
|
- **Smart Automatic Migrations:** CLI detects schema changes across `app/models/`, resolves foreign key dependencies topologically, generates consolidated `CREATE TABLE` / `ALTER TABLE ADD COLUMN` SQL files, and executes them with interactive terminal prompts.
|
|
24
24
|
- **Lightweight BaseModel:** Static facade providing readable schemas, CRUD shortcuts, query operators (`IN`, `$gt`, `$like`), `count()`, `exists()`, `firstOrCreate()`, `updateOrCreate()`, smart relations without N+1 queries, soft deletes, and automatic query cache invalidation.
|
|
25
|
-
- **Native SQLite & Desktop Mode (Electron/Tauri):** Uses Node's built-in `node:sqlite` driver
|
|
26
|
-
- **Comprehensive Client UI Kit:** Built-in `bluebird-client.js` with toasts, snackbars, drawers, command palette (`Ctrl+K`), responsive data tables, tabs, carousels, declarative forms (`data-bb-form`), and View Transitions SPA routing.
|
|
25
|
+
- **Native SQLite & Desktop Mode (Electron/Tauri):** Uses Node's built-in `node:sqlite` driver (no native compilation), plus first-class `desktop: true` mode (`app.runDesktop()`) for read-only `.asar` bundles.
|
|
27
26
|
- **Decoupled Caching:** High-speed in-memory LRU cache by default, persistent filesystem fallback, and modular Redis support via `core/redis.js`.
|
|
28
|
-
- **Unified AI Client (`core/ai.js`):**
|
|
29
|
-
- **Atomic Database Backups & Verification:** WAL-safe, non-blocking online SQLite snapshots using `VACUUM INTO` and gzip compression, with automated retention rotation (`--keep 10
|
|
30
|
-
- **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection, built-in Rate Limiter (`rateLimit` in `App
|
|
27
|
+
- **Unified AI Client (`core/ai.js`):** Built-in client (no provider SDKs) with DeepSeek default (`deepseek-flash`), Gemini 3.5/3.8, and OpenAI, featuring reversible PII data masking, 0ms prompt caching, sliding window rate limits ("Anti-Quiebra"), and JSON schema validation.
|
|
28
|
+
- **Atomic Database Backups & Verification:** WAL-safe, non-blocking online SQLite snapshots using `VACUUM INTO` and gzip compression, with automated retention rotation (`--keep 10`, ordered by filename timestamp so same-millisecond backups never drop the newest one) and integrity-verified restore.
|
|
29
|
+
- **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection (timing-safe, rotated on login/logout, never leaked through cached pages), built-in Rate Limiter (`rateLimit` in `App`, `App.rateLimit()`), secure-by-default CORS, CSP nonces (`'nonce-{nonce}'`) applied to every inline script/style, automatic `/sitemap.xml` & `/robots.txt` generation, and secure HTTP headers.
|
|
31
30
|
- **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`).
|
|
32
31
|
|
|
33
32
|
---
|
|
@@ -48,9 +47,39 @@ npx bluebird-js
|
|
|
48
47
|
|
|
49
48
|
The interactive CLI configures:
|
|
50
49
|
- Project title and port settings
|
|
51
|
-
-
|
|
50
|
+
- Project template (see below), `blank` by default
|
|
51
|
+
- Database engine: `sqlite` (default, built into Node.js), `mysql`, `postgres`, or `none`
|
|
52
52
|
- Connection credentials and database paths
|
|
53
|
-
- Automatic generation of `index.js`, `.env`, `jsconfig.json`, `app/`, and `public/`
|
|
53
|
+
- Automatic generation of `index.js`, `vite.config.js`, `.env`, `jsconfig.json`, `app/`, and `public/`
|
|
54
|
+
|
|
55
|
+
#### Project Templates
|
|
56
|
+
|
|
57
|
+
Pick a starting point with a flag (or answer the prompt). Every template starts clean, so there is nothing to delete before building your own app:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npx bluebird-js # asks for the template (default: blank)
|
|
61
|
+
npx bluebird-js --blank # HTML {{ }} page on / + one-page React SPA on /app/*
|
|
62
|
+
npx bluebird-js --auth # + login, register, forgot/reset password, dashboard, profile
|
|
63
|
+
npx bluebird-js --blog # SEO blog (HTML list, posts, RSS, sitemap) + React admin on /app
|
|
64
|
+
npx bluebird-js --api # headless REST API: JWT auth (cookie or bearer) + CRUD example
|
|
65
|
+
npx bluebird-js --demo # full showcase used to develop the framework
|
|
66
|
+
npx bluebird-js --auth --yes --title "My App" # non-interactive
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
| Template | Server | React (`/app`) | Database |
|
|
70
|
+
|---|---|---|---|
|
|
71
|
+
| `blank` | `/` HTML page, `/api/hello` | `Home.jsx` only | optional |
|
|
72
|
+
| `auth` | `/` landing, `/api/auth/*` (me, login, logout, register, forgot/reset password, profile, password), `/api/dashboard` | Login, Register, ForgotPassword, ResetPassword, Dashboard, Profile | required (tables created on first run) |
|
|
73
|
+
| `blog` | `/`, `/blog/:slug` (cached, JSON-LD), `/feed.xml`, posts in `/sitemap.xml`, `/api/posts` (admin) | Login, one-time admin Register, Posts, PostEditor | required |
|
|
74
|
+
| `api` | `/api/auth/*`, `/api/notes` (paginated, owner-scoped CRUD), no Vite | none | required |
|
|
75
|
+
|
|
76
|
+
- In `auth` and `api`, every new account gets the `user` role; promote admins yourself, e.g. in a seed: `await User.update(id, { role: "admin" })`. In `blog`, only the first account can register: it becomes the `admin` and registration closes.
|
|
77
|
+
- Sessions are checked against the database on every protected request (`Auth.configure({ resolveUser })`): changing or resetting the password signs out every other device (the current one gets a fresh token), `POST /api/auth/logout-all` signs out everywhere, deleted accounts lose access, and role changes apply immediately. Changing the sign-in email requires `current_password`.
|
|
78
|
+
- Password reset links are printed in the server console by `app/mail.js` until you plug in a mail provider there.
|
|
79
|
+
- Tables are created with `CREATE TABLE IF NOT EXISTS` at startup (`app/database.js`); use `make:migration` / `migrate` for later schema changes.
|
|
80
|
+
- Existing files are never overwritten, so the command is safe to run inside an existing folder.
|
|
81
|
+
|
|
82
|
+
Dependencies: `express`, `react`, `react-dom`, `react-router`, `vite`, `@vitejs/plugin-react`, `tailwindcss` and `@tailwindcss/vite` are installed with the framework; database drivers, Redis, uploads, WebSockets, Swagger and Helmet are optional (`npx bluebird-js add <module>`).
|
|
54
83
|
|
|
55
84
|
### 3. Development Server
|
|
56
85
|
|
|
@@ -58,7 +87,20 @@ The interactive CLI configures:
|
|
|
58
87
|
npm run dev
|
|
59
88
|
```
|
|
60
89
|
|
|
61
|
-
The server
|
|
90
|
+
`npm run dev` runs `bluebird-js dev`: Express and Vite share one port, with React Fast Refresh and Tailwind CSS HMR for `app/resources/` (HTML `{{ }}` pages included). The server restarts when any server file under `app/` changes (routes, models, jobs, `app/lib/`...), or `index.js`, `.env`, `app/resources/spa.js`; client files in `app/resources/` hot-reload through Vite instead, and writes to `logs/`, `node_modules/`, or build output never restart it. Watch extra folders with `bluebird-js dev index.js --watch app/services`.
|
|
91
|
+
|
|
92
|
+
### 4. Production Build
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npx bluebird-js build # Builds client SPA & Tailwind CSS bundle into public/build/
|
|
96
|
+
npm start
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### 5. Static Export (Electron, Capacitor, static hosting)
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npx bluebird-js export --api https://api.example.com # dist/client/index.html + assets/
|
|
103
|
+
```
|
|
62
104
|
|
|
63
105
|
---
|
|
64
106
|
|
|
@@ -67,30 +109,29 @@ The server starts with Node's native file watcher (`--watch`) and loads `.env` a
|
|
|
67
109
|
```
|
|
68
110
|
project/
|
|
69
111
|
├── index.js # Main application entrypoint
|
|
112
|
+
├── vite.config.js # Optional Vite config (React, Tailwind, Bluebird plugins)
|
|
70
113
|
├── app/
|
|
71
|
-
│ ├──
|
|
72
|
-
│ │ ├──
|
|
73
|
-
│ │
|
|
74
|
-
│ ├──
|
|
75
|
-
│ │ ├──
|
|
76
|
-
│ │
|
|
77
|
-
│ ├──
|
|
78
|
-
│ │ ├──
|
|
79
|
-
│ │
|
|
80
|
-
│ │
|
|
81
|
-
│ │
|
|
82
|
-
│ │
|
|
83
|
-
│ │
|
|
114
|
+
│ ├── resources/ # Everything client-side
|
|
115
|
+
│ │ ├── index.html # React SPA shell (router.spa() + npx bluebird-js export)
|
|
116
|
+
│ │ ├── spa.js # SPA config: mount, title, description, per-URL meta tree
|
|
117
|
+
│ │ ├── styles.css # Tailwind CSS v4 entry (shared by HTML SSR + React SPA)
|
|
118
|
+
│ │ ├── main.jsx # createRoot + AuthProvider + RouterProvider
|
|
119
|
+
│ │ ├── routes.jsx # createRouter + lazy routes
|
|
120
|
+
│ │ ├── layouts/AppLayout.jsx
|
|
121
|
+
│ │ ├── pages/ # Home.jsx, Login.jsx, Register.jsx, Dashboard.jsx, NotFound.jsx
|
|
122
|
+
│ │ └── html/ # HTML {{ }} SSR templates
|
|
123
|
+
│ │ ├── layouts/main.html
|
|
124
|
+
│ │ ├── partials/
|
|
125
|
+
│ │ ├── home.html
|
|
126
|
+
│ │ ├── terms.html
|
|
127
|
+
│ │ └── notFound.html (404 page for unknown routes)
|
|
128
|
+
│ ├── models/ # BaseModel definitions (user.js)
|
|
129
|
+
│ ├── routes/ # Express routes (web.js, auth.js, api.js)
|
|
84
130
|
│ └── jobs/ # Background worker job handlers
|
|
85
|
-
├── public/ #
|
|
86
|
-
│ ├── js/
|
|
87
|
-
│ │ ├── tailwind.js # Built-in Tailwind CSS runtime
|
|
88
|
-
│ │ └── bluebird-client.js # Client UI kit, View Transitions & SPA router
|
|
89
|
-
│ └── images/
|
|
131
|
+
├── public/ # Static assets (js/bluebird.js, images/, build/)
|
|
90
132
|
├── core/ # Bluebird.js framework core
|
|
91
133
|
├── database/ # SQLite storage and SQL migrations
|
|
92
|
-
|
|
93
|
-
├── .env # Environment variables
|
|
134
|
+
├── .env
|
|
94
135
|
└── package.json
|
|
95
136
|
```
|
|
96
137
|
|
|
@@ -218,264 +259,215 @@ npx bluebird-js migrate --yes
|
|
|
218
259
|
|
|
219
260
|
---
|
|
220
261
|
|
|
221
|
-
### 3.
|
|
262
|
+
### 3. HTML `{{ }}` SSR Rendering & React Router SPA (`router.spa()`)
|
|
222
263
|
|
|
223
|
-
|
|
264
|
+
Bluebird separates **server-rendered HTML pages** (landings, storefronts, marketing, legal pages) from **client-rendered React Router SPAs** (dashboards, admin panels, interactive apps).
|
|
224
265
|
|
|
225
|
-
|
|
266
|
+
#### 404 Pages
|
|
226
267
|
|
|
227
|
-
|
|
268
|
+
Unknown routes return JSON under `/api` (and for JSON clients), and for browsers render `app/resources/html/notFound.html` (with `{{ path }}`) inside the `main` layout, or a built-in page when that view does not exist. Inside a `router.spa()` mount the React `NotFound` page (`{ path: "*" }` in `routes.jsx`) handles them. Disable it with `new App({ notFound: false })`.
|
|
228
269
|
|
|
229
|
-
|
|
270
|
+
#### HTML `{{ }}` Templates (`app/resources/html/`)
|
|
230
271
|
|
|
231
|
-
```
|
|
232
|
-
// app/
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
272
|
+
```javascript
|
|
273
|
+
// app/routes/web.js
|
|
274
|
+
import Router from "@seip/bluebird-js/core/router.js";
|
|
275
|
+
import Render from "@seip/bluebird-js/core/render.js";
|
|
276
|
+
|
|
277
|
+
const routerWeb = new Router("/", { seo: true });
|
|
278
|
+
|
|
279
|
+
routerWeb.get("/", (req, res) => {
|
|
280
|
+
const clientsHtml = clients.map((c) => `<span>${c.name}</span>`).join("");
|
|
281
|
+
return Render.html(
|
|
282
|
+
res,
|
|
283
|
+
"home",
|
|
284
|
+
{ title: "Welcome", clientsHtml, slides },
|
|
285
|
+
{ layout: "main", cache: 300 }
|
|
244
286
|
);
|
|
245
|
-
}
|
|
287
|
+
});
|
|
246
288
|
```
|
|
247
289
|
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
export const layout = "main";
|
|
258
|
-
export const middlewares = [Auth.protect({ redirect: "/login" })];
|
|
259
|
-
export const seo = false;
|
|
260
|
-
export const head = (data) => ({ title: `Dashboard — ${data.user?.name || "Member"}` });
|
|
261
|
-
|
|
262
|
-
// Server Actions: automatic CSRF, 16KB maxBytes guard, prototype pollution filter & Validator schema
|
|
263
|
-
export const actions = {
|
|
264
|
-
syncCount: Actions.define(
|
|
265
|
-
{
|
|
266
|
-
maxBytes: "16kb",
|
|
267
|
-
schema: { count: { required: true, number: true } },
|
|
268
|
-
},
|
|
269
|
-
async ({ body, user }) => {
|
|
270
|
-
return { syncedCount: Number(body.count), updatedBy: user?.email };
|
|
271
|
-
}
|
|
272
|
-
),
|
|
273
|
-
};
|
|
274
|
-
|
|
275
|
-
export default async function DashboardView({ user, syncedCount = 7 }) {
|
|
276
|
-
return (
|
|
277
|
-
<>
|
|
278
|
-
<Header title="Protected Dashboard" user={user} count={syncedCount} />
|
|
279
|
-
|
|
280
|
-
<div className="space-y-6 mt-6">
|
|
281
|
-
{/* Reusable imported Client component with persistent state & anti-CLS skeleton */}
|
|
282
|
-
<Client
|
|
283
|
-
component={LiveCounter}
|
|
284
|
-
props={{ initial: syncedCount }}
|
|
285
|
-
persistent={true}
|
|
286
|
-
minHeight={56}
|
|
287
|
-
skeleton={
|
|
288
|
-
<div className="h-14 rounded-xl bg-slate-900 animate-pulse flex items-center px-4 text-xs text-slate-400">
|
|
289
|
-
Loading interactive widget...
|
|
290
|
-
</div>
|
|
291
|
-
}
|
|
292
|
-
/>
|
|
290
|
+
```html
|
|
291
|
+
<!-- app/resources/html/home.html -->
|
|
292
|
+
<section>
|
|
293
|
+
<h1>{{ title }}</h1>
|
|
294
|
+
<div>{{{ clientsHtml }}}</div>
|
|
295
|
+
{{#if slides}}
|
|
296
|
+
<div data-carousel data-autoplay="5000">
|
|
297
|
+
<div data-carousel-track>
|
|
298
|
+
{{#each slides}}<div data-carousel-slide>{{ title }}</div>{{/each}}
|
|
293
299
|
</div>
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
}
|
|
300
|
+
<div data-carousel-dots></div>
|
|
301
|
+
</div>
|
|
302
|
+
{{/if}}
|
|
303
|
+
</section>
|
|
297
304
|
```
|
|
298
305
|
|
|
299
|
-
####
|
|
306
|
+
#### React Router SPA (`router.spa()`)
|
|
300
307
|
|
|
301
|
-
|
|
308
|
+
The SPA config lives in `app/resources/spa.js`, so the web server and the static export share the same title, description, and meta tree. `router.spa()` renders the React shell `app/resources/index.html` with per-URL SEO tags, JSON-LD, canonical links, custom scripts/styles, and a full-width inline skeleton inside `<div id="root">`:
|
|
302
309
|
|
|
303
|
-
```
|
|
304
|
-
// app/
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
},
|
|
314
|
-
|
|
310
|
+
```javascript
|
|
311
|
+
// app/resources/spa.js
|
|
312
|
+
export default {
|
|
313
|
+
mount: "/app",
|
|
314
|
+
lang: "en",
|
|
315
|
+
titleTemplate: "%s — My App",
|
|
316
|
+
skeleton: "app",
|
|
317
|
+
meta: {
|
|
318
|
+
"*": { title: "Workspace", robots: "noindex, nofollow", skeleton: "app" },
|
|
319
|
+
"/": { title: "Explore", description: "Interactive workspace", robots: "index, follow", skeleton: "page" },
|
|
320
|
+
"login": { title: "Sign In", keywords: "login, auth", skeleton: "auth", jsonld: { "@type": "WebPage" } },
|
|
321
|
+
"/app/register": { title: "Register", skeleton: "auth" },
|
|
322
|
+
},
|
|
323
|
+
};
|
|
324
|
+
```
|
|
315
325
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
};
|
|
326
|
+
```javascript
|
|
327
|
+
// app/routes/web.js
|
|
328
|
+
import spa from "../resources/spa.js";
|
|
320
329
|
|
|
321
|
-
|
|
322
|
-
<div class="h-14 rounded-xl border border-slate-800 bg-slate-950/90 px-4 flex items-center justify-between">
|
|
323
|
-
<span class="text-xs text-slate-300">${label}: <strong class="text-sky-400 font-mono">${count}</strong></span>
|
|
324
|
-
<div class="flex items-center gap-2">
|
|
325
|
-
<button type="button" onClick=${() => setCount(count + 1)} class="px-2.5 py-1 bg-sky-500 rounded text-xs font-bold text-slate-950">+1</button>
|
|
326
|
-
<button type="button" onClick=${actualizarDashboard} disabled=${isPending} class="px-2.5 py-1 bg-emerald-500/15 border border-emerald-500/30 rounded text-xs text-emerald-300">
|
|
327
|
-
${isPending ? "Syncing..." : "Sync Server Action"}
|
|
328
|
-
</button>
|
|
329
|
-
</div>
|
|
330
|
-
</div>
|
|
331
|
-
`;
|
|
332
|
-
}
|
|
330
|
+
routerWeb.spa(spa.mount, spa);
|
|
333
331
|
```
|
|
334
332
|
|
|
335
|
-
|
|
333
|
+
Keys inside `meta` accept both relative (`"login"`) and absolute (`"/app/login"`) formats, dynamic functions `(req, params) => ({ ... })`, and `"*"` wildcard defaults. The React entry defaults to `app/resources/main.jsx` and the shell to `app/resources/index.html` (`template: false` uses the built-in shell).
|
|
334
|
+
|
|
335
|
+
The React shell (`app/resources/index.html`) and the HTML SSR layout (`app/resources/html/layouts/main.html`) are separate files on purpose: the first one is also the entry of the static export.
|
|
336
|
+
|
|
337
|
+
#### Design System & Theming
|
|
336
338
|
|
|
337
|
-
|
|
339
|
+
Bluebird ships a neutral, shadcn-style design system shared by React components and HTML `{{ }}` views. The Vite plugin injects it right after `@import "tailwindcss"` in your stylesheet, so there is nothing to import:
|
|
340
|
+
|
|
341
|
+
- **Tokens** (light and dark): `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `border`, `input`, `ring`, `brand`, `success`, `warning`, `info`, used as Tailwind utilities (`bg-primary`, `text-muted-foreground`, `border-border`...).
|
|
342
|
+
- **Component classes** for plain HTML: `btn` + `btn-primary | btn-secondary | btn-outline | btn-ghost | btn-danger | btn-link` + `btn-sm | btn-lg | btn-icon`, `card` / `card-title` / `card-description`, `field` / `field-label` / `field-hint` / `field-error`, `badge` / `badge-dot`, `nav-link` (active with `aria-current="page"`), `glass`, `bg-app`, and `brand`.
|
|
343
|
+
- **Color is used sparingly**: `primary` (near-black in light, near-white in dark) for the main action, `secondary`/`outline`/`ghost` for the rest, `danger` for destructive actions, and `brand` only for the logo. Badges and toasts stay neutral with a small colored dot for the tone.
|
|
344
|
+
|
|
345
|
+
```html
|
|
346
|
+
<a href="/app" class="btn btn-primary">Open app</a>
|
|
347
|
+
<button class="btn btn-outline btn-sm">Cancel</button>
|
|
348
|
+
<span class="badge"><span class="badge-dot bg-success"></span>Live</span>
|
|
349
|
+
```
|
|
338
350
|
|
|
339
351
|
```jsx
|
|
340
|
-
import {
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
<UserProfileWidget userId={user.id} />
|
|
352
|
-
</ErrorBoundary>
|
|
353
|
-
</>
|
|
354
|
-
);
|
|
355
|
-
}
|
|
352
|
+
import { Button, Link, buttonVariants } from "@seip/bluebird-js/react";
|
|
353
|
+
|
|
354
|
+
<Button variant="danger" size="sm">Delete</Button>
|
|
355
|
+
<Link to="/new" className={buttonVariants({ variant: "outline" })}>New post</Link>
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Customize it by overriding the variables in `app/resources/styles.css` (your values win over the defaults), or turn the injection off with `bluebird({ theme: false })` in `vite.config.js`:
|
|
359
|
+
|
|
360
|
+
```css
|
|
361
|
+
:root { --primary: oklch(0.55 0.2 264); --primary-foreground: oklch(0.98 0 0); --brand: oklch(0.65 0.2 30); }
|
|
362
|
+
.dark { --primary: oklch(0.7 0.16 264); --primary-foreground: oklch(0.15 0 0); }
|
|
356
363
|
```
|
|
357
364
|
|
|
358
|
-
####
|
|
365
|
+
#### Component Languages (i18n)
|
|
359
366
|
|
|
360
|
-
|
|
367
|
+
Built-in UI strings (toast badges, close buttons, carousel controls, loading and error fallbacks, theme toggle labels) follow the page language from `<html lang>`: `{{ lang }}` in HTML views and `lang` in `app/resources/spa.js` for the React SPA. English, Spanish, Portuguese, French, German, and Italian are included; regional tags fall back to their base language (`es-AR` uses `es`) and unknown languages fall back to English. In Spanish, `toast.success()` shows **Correcto**, `toast.warning()` **Cuidado**, and `toast.error()` **Error**.
|
|
361
368
|
|
|
362
369
|
```jsx
|
|
363
|
-
import {
|
|
370
|
+
import { addMessages, setLocale, useLocale } from "@seip/bluebird-js/react";
|
|
364
371
|
|
|
365
|
-
|
|
372
|
+
addMessages("es", { "toast.warning": "Atención" });
|
|
373
|
+
addMessages("ja", { "toast.success": "成功", "toast.warning": "注意", "toast.error": "エラー" });
|
|
374
|
+
setLocale("es");
|
|
366
375
|
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
<div>
|
|
370
|
-
<h1>Live Activity</h1>
|
|
371
|
-
<Suspense fallback={<div className="h-40 animate-pulse bg-slate-900 rounded-xl">Loading feed...</div>}>
|
|
372
|
-
<AsyncFeedList />
|
|
373
|
-
</Suspense>
|
|
374
|
-
</div>
|
|
375
|
-
);
|
|
376
|
-
}
|
|
376
|
+
const { locale, t } = useLocale();
|
|
377
|
+
t("carousel.status", { n: 2, total: 5 });
|
|
377
378
|
```
|
|
378
379
|
|
|
379
|
-
|
|
380
|
+
HTML views get the same strings from `public/js/bluebird.js` through `Bluebird.i18n.t()`, `Bluebird.i18n.addMessages()`, and `Bluebird.i18n.setLocale()`. A custom `badge` on a toast always wins over the translated label.
|
|
380
381
|
|
|
381
|
-
|
|
382
|
+
#### Client React API (`@seip/bluebird-js/react`) & Auth
|
|
382
383
|
|
|
383
|
-
```
|
|
384
|
-
// app/
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
}
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
<
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
}
|
|
384
|
+
```jsx
|
|
385
|
+
// app/resources/main.jsx
|
|
386
|
+
import { createRoot } from "react-dom/client";
|
|
387
|
+
import { RouterProvider } from "react-router/dom";
|
|
388
|
+
import { AuthProvider, Toaster } from "@seip/bluebird-js/react";
|
|
389
|
+
import "./styles.css";
|
|
390
|
+
import { router } from "./routes.jsx";
|
|
391
|
+
|
|
392
|
+
createRoot(document.getElementById("root")).render(
|
|
393
|
+
<AuthProvider>
|
|
394
|
+
<RouterProvider router={router} />
|
|
395
|
+
<Toaster />
|
|
396
|
+
</AuthProvider>
|
|
397
|
+
);
|
|
398
398
|
```
|
|
399
399
|
|
|
400
|
-
|
|
400
|
+
```jsx
|
|
401
|
+
// app/resources/routes.jsx
|
|
402
|
+
import { createRouter } from "@seip/bluebird-js/react";
|
|
401
403
|
|
|
402
|
-
|
|
404
|
+
export const router = createRouter(routes, { basename: "/app" });
|
|
405
|
+
```
|
|
403
406
|
|
|
404
|
-
|
|
407
|
+
- **Router**: `createRouter()` uses `createBrowserRouter` (with `basename`) on the server and `createHashRouter` in static exports or under `file://`.
|
|
408
|
+
- **Auth hooks & route guards**: `useAuth()` (`user`, `loading`, `authenticated`, `registerEnabled`, `login`, `register`, `logout`, `refresh`, `hasRole`), `<RequireAuth roles={["admin"]} />` (optional `roles` — without `roles`, any signed-in user passes), and `<GuestOnly />`.
|
|
409
|
+
- **REST helper**: `api.get/post/put/patch/delete(url, body)` sends `X-CSRF-Token` (cookie sessions) or `Authorization: Bearer` (token mode), parses JSON, and normalizes `Validator` errors into `ApiError.errors`. Configure with `configureApi({ baseUrl, auth: "cookie" | "token" })`.
|
|
410
|
+
- **UI Components (Light + Dark Tailwind)**: `Link`, `Button`, `Form`, `SubmitButton`, `Input`, `Textarea`, `Select`, `Card`, `Badge`, `Carousel`, `Modal`, `Drawer`, `Skeleton`, `PageSkeleton`, `ProgressBar`, `Spinner`, `ThemeToggle`, `useTheme`, `Toaster` / `toast`, `cn()`.
|
|
411
|
+
- **Vanilla Browser Helpers (`public/js/bluebird.js`)**: `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]`.
|
|
405
412
|
|
|
406
|
-
####
|
|
413
|
+
#### Role-Protected Backend & Optional Register (`app/routes/auth.js`)
|
|
407
414
|
|
|
408
415
|
```javascript
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
description: "Your settings have been saved successfully.",
|
|
412
|
-
type: "success",
|
|
413
|
-
position: "top-right",
|
|
414
|
-
duration: 4000,
|
|
415
|
-
});
|
|
416
|
+
import Auth from "@seip/bluebird-js/core/auth.js";
|
|
417
|
+
import { createAuthRouter } from "./app/routes/auth.js";
|
|
416
418
|
|
|
417
|
-
|
|
418
|
-
```
|
|
419
|
+
const routerAuth = createAuthRouter({ register: true });
|
|
419
420
|
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
<button data-toast="Settings saved successfully!" data-toast-type="success">Save</button>
|
|
423
|
-
<button data-snackbar="Item deleted" data-snackbar-type="error">Delete</button>
|
|
421
|
+
routerApi.get("/profile", Auth.protect(), (req, res) => res.ok({ user: req.user }));
|
|
422
|
+
routerApi.get("/admin/stats", Auth.protect({ roles: "admin" }), (req, res) => res.ok({ ok: true }));
|
|
424
423
|
```
|
|
425
424
|
|
|
426
|
-
|
|
425
|
+
The auth and API routers apply `Csrf.middleware()`. Browser sessions use an HttpOnly cookie; clients sending `X-Auth-Mode: token` (static exports) receive `{ user, token }` and authenticate with `Authorization: Bearer`, which is CSRF-exempt because it is never sent automatically by the browser.
|
|
427
426
|
|
|
428
|
-
|
|
429
|
-
<button data-drawer-target="cartDrawer">Open Cart</button>
|
|
427
|
+
#### Static Export: Electron, Capacitor & Static Hosting (`npx bluebird-js export`)
|
|
430
428
|
|
|
431
|
-
|
|
432
|
-
<button data-drawer-close="cartDrawer" class="text-slate-400">×</button>
|
|
433
|
-
<h3>Shopping Cart</h3>
|
|
434
|
-
</div>
|
|
435
|
-
```
|
|
429
|
+
Builds the same React code, `index.html` shell, and `spa.js` metadata into a 100% static HTML/JS/CSS folder:
|
|
436
430
|
|
|
437
|
-
|
|
431
|
+
```bash
|
|
432
|
+
npx bluebird-js export --api https://api.example.com # dist/client (hash router, ./ assets)
|
|
433
|
+
npx bluebird-js export --out mobile/www --api https://api.example.com
|
|
434
|
+
npx bluebird-js export --router browser --base / --out dist/web # static host with history fallback
|
|
435
|
+
```
|
|
438
436
|
|
|
439
|
-
|
|
437
|
+
| Option | Default | Purpose |
|
|
438
|
+
|---|---|---|
|
|
439
|
+
| `--out <dir>` | `dist/client` | Output folder (refuses `app/`, `core/`, `public/`, or the project root) |
|
|
440
|
+
| `--api <url>` | `EXPORT_API_URL` or `APP_URL` | Base URL prepended by `api()` to `/api/*` |
|
|
441
|
+
| `--router <mode>` | `hash` | `hash` (works with `file://`), `browser`, or `memory` |
|
|
442
|
+
| `--base <path>` | `./` (`/` for browser) | Asset base URL |
|
|
443
|
+
| `--auth <mode>` | `token` | `token` (Bearer in `localStorage`) or `cookie` |
|
|
444
|
+
| `--config <file>` | `app/resources/spa.js` | SPA config module |
|
|
445
|
+
| `--no-public` | | Skip copying `public/` |
|
|
440
446
|
|
|
441
447
|
```javascript
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
{ key: "id", label: "ID", sortable: true },
|
|
445
|
-
{ key: "name", label: "Name", sortable: true },
|
|
446
|
-
{ key: "email", label: "Email" },
|
|
447
|
-
{ key: "role", label: "Role" },
|
|
448
|
-
],
|
|
449
|
-
data: usersList,
|
|
450
|
-
searchable: true,
|
|
451
|
-
pagination: true,
|
|
452
|
-
pageSize: 10,
|
|
453
|
-
onEdit: (row) => editUser(row.id),
|
|
454
|
-
onDelete: (row) => deleteUser(row.id),
|
|
455
|
-
});
|
|
448
|
+
// Electron main process (static client, no embedded server)
|
|
449
|
+
mainWindow.loadFile(path.join(__dirname, "dist/client/index.html"));
|
|
456
450
|
```
|
|
457
451
|
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
<form action="/api/profile" method="POST" data-bb-form="true">
|
|
462
|
-
<input type="text" name="name" required />
|
|
463
|
-
<button type="submit">Update</button>
|
|
464
|
-
</form>
|
|
452
|
+
```json
|
|
453
|
+
// capacitor.config.json
|
|
454
|
+
{ "appId": "com.example.app", "appName": "Example", "webDir": "dist/client" }
|
|
465
455
|
```
|
|
466
|
-
Submissions are automatically handled via `fetch`, CSRF tokens are injected, and toasts/redirects are handled seamlessly via View Transitions.
|
|
467
456
|
|
|
468
|
-
|
|
457
|
+
Use `isExported()` to hide web-only UI (for example links to HTML pages) inside the exported build. The embedded-server Electron mode (`desktop: true`) keeps working as before.
|
|
469
458
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
459
|
+
#### Development & Production
|
|
460
|
+
|
|
461
|
+
```bash
|
|
462
|
+
npm run dev # bluebird-js dev: Express + Vite on one port (HMR + Tailwind v4), restarts on server file changes
|
|
463
|
+
npx bluebird-js build # Builds client SPA & Tailwind CSS bundle into public/build/
|
|
464
|
+
npm start # Production: serves public/build/.vite/manifest.json
|
|
465
|
+
npx bluebird-js export # Static React build for Electron, Capacitor, or static hosting
|
|
466
|
+
```
|
|
475
467
|
|
|
476
468
|
---
|
|
477
469
|
|
|
478
|
-
###
|
|
470
|
+
### 4. Multi-Driver Caching (`core/cache.js`)
|
|
479
471
|
|
|
480
472
|
```javascript
|
|
481
473
|
import Cache from "@seip/bluebird-js/core/cache.js";
|
|
@@ -486,9 +478,23 @@ const metrics = await Cache.get("metrics", { driver: "memory" });
|
|
|
486
478
|
await Cache.set("report", htmlContent, 300, { driver: "file" });
|
|
487
479
|
```
|
|
488
480
|
|
|
481
|
+
HTML render caches (`Render.html(..., { cache: 300 })`, `Render.cache(300)`, `router.spa(..., { cache: 300 })`) are keyed by path. Query strings bypass the cache unless allowlisted (`cacheQuery: ["page"]` or `Render.cache(300, { query: ["page"] })`), preventing cache flooding. Cached pages restore each visitor's own CSRF token and CSP nonce.
|
|
482
|
+
|
|
483
|
+
#### Security Defaults (CORS & CSP)
|
|
484
|
+
|
|
485
|
+
```javascript
|
|
486
|
+
const app = new App({
|
|
487
|
+
routes: [routerWeb, routerApi],
|
|
488
|
+
// "*" never reflects origins nor sends credentials. Credentialed CORS requires an allowlist:
|
|
489
|
+
cors: { origin: ["https://app.example.com"], credentials: true },
|
|
490
|
+
// {nonce} becomes a per-request nonce added to every inline <script>/<style> Bluebird renders:
|
|
491
|
+
security: { csp: "default-src 'self'; script-src 'self' 'nonce-{nonce}'" },
|
|
492
|
+
});
|
|
493
|
+
```
|
|
494
|
+
|
|
489
495
|
---
|
|
490
496
|
|
|
491
|
-
###
|
|
497
|
+
### 5. Desktop Applications (Electron & Desktop Mode)
|
|
492
498
|
|
|
493
499
|
Bluebird.js runs natively embedded inside **Electron** applications with ultra-fast boot (<200ms) and minimal RAM consumption (~25–40 MB vs ~300 MB with Nextron):
|
|
494
500
|
|
|
@@ -500,15 +506,19 @@ Bluebird.js runs natively embedded inside **Electron** applications with ultra-f
|
|
|
500
506
|
npx bluebird-js add electron
|
|
501
507
|
```
|
|
502
508
|
|
|
509
|
+
The generated desktop scripts run `npx bluebird-js build` before `electron-builder`, so pages are served from the production build inside the `.asar` bundle.
|
|
510
|
+
|
|
511
|
+
Prefer a client-only desktop or mobile app that talks to a remote API? Use `npx bluebird-js export` (section 3) and load `dist/client/index.html` with `mainWindow.loadFile()` or Capacitor.
|
|
512
|
+
|
|
503
513
|
---
|
|
504
514
|
|
|
505
|
-
###
|
|
515
|
+
### 6. Unified AI Client (`core/ai.js`)
|
|
506
516
|
|
|
507
|
-
|
|
517
|
+
Built-in AI client (no provider SDKs required) supporting **DeepSeek (default)**, **Google Gemini**, and **OpenAI** with reversible PII data masking, 0ms prompt caching, sliding window rate limits, and JSON schema validation:
|
|
508
518
|
|
|
509
519
|
- **DeepSeek by Default (`deepseek-flash`):** Default endpoint `https://api.deepseek.com`, served by DeepSeek-V4.1-Flash-1017 (legacy names `deepseek-v4-flash`, `deepseek-chat` supported). Optional thinking mode (`thinking: { type: "enabled" }`, `reasoningEffort: "high"`).
|
|
510
520
|
- **Google Gemini & OpenAI:** Built-in REST connectors for `gemini-3.5-flash`, `gemini-3.8-flash`, `gemini-2.5-flash`, `gpt-4o-mini`, and custom endpoints via `baseURL`.
|
|
511
|
-
- **Accurate Real IP Detection (`getClientIp`):** Resolves real visitor IPs across Cloudflare (`cf-connecting-ip`, `true-client-ip`), Nginx (`x-real-ip`), proxy chains (`x-forwarded-for`), and cleans IPv6 mappings.
|
|
521
|
+
- **Accurate Real IP Detection (`getClientIp`):** Resolves real visitor IPs across Cloudflare (`cf-connecting-ip`, `true-client-ip`), Nginx (`x-real-ip`), proxy chains (`x-forwarded-for`), and cleans IPv6 mappings. Proxy headers are only trusted from local/private reverse proxies (`trustProxy` defaults to `"loopback, linklocal, uniquelocal"`; set it to your CDN hop count when needed), so clients cannot spoof them to bypass rate limits.
|
|
512
522
|
- **Reversible PII Masking:** Replaces sensitive user keys (`name`, `email`, `dni`, etc.) with anonymous tokens (`[name_01]`, `[email_01]`) before transmission, restoring original values in responses.
|
|
513
523
|
- **0ms Prompt Cache Hit:** Computes cache hashes on *anonymized* prompts so multiple users querying identical prompt templates trigger an immediate $0 / 0ms Cache Hit.
|
|
514
524
|
- **Rate Limit Protection ("Anti-Quiebra"):** Configurable per-minute/per-day sliding windows (e.g. `{ minute: 6, day: 30 }`), returning clean HTTP 429 errors via `ai.protect()` middleware before depleting API budget.
|
|
@@ -553,7 +563,7 @@ for await (const chunk of supportAi.askStream("Explain quantum computing in simp
|
|
|
553
563
|
|
|
554
564
|
---
|
|
555
565
|
|
|
556
|
-
###
|
|
566
|
+
### 7. Atomic Database Backups & Verification (`core/database.js`)
|
|
557
567
|
|
|
558
568
|
WAL-safe, non-blocking snapshots for SQLite using `VACUUM INTO` and gzip compression, with automated retention rotation and integrity-verified restore:
|
|
559
569
|
|
|
@@ -575,10 +585,13 @@ await Database.restore("database/backups/backup-sqlite-2026-11-03_170000_123.db.
|
|
|
575
585
|
## Developer Tooling CLI
|
|
576
586
|
|
|
577
587
|
```bash
|
|
588
|
+
npx bluebird-js [--blank|--auth|--blog|--api|--demo] # Scaffolds a project from a template (default: blank)
|
|
578
589
|
npx bluebird-js doctor # Diagnostic audit and HTTP smoke tests
|
|
579
590
|
npx bluebird-js make:model <Name> # Generates BaseModel class
|
|
580
591
|
npx bluebird-js make:route <name> [--auth] # Scaffolds REST route
|
|
581
|
-
npx bluebird-js make:view <name> [--
|
|
592
|
+
npx bluebird-js make:view <name> [--partial|--layout] # Scaffolds an HTML {{ }} template view
|
|
593
|
+
npx bluebird-js build # Builds client SPA and Tailwind CSS bundle (public/build/)
|
|
594
|
+
npx bluebird-js export [--api url] [--out dir] # Static React export (Electron, Capacitor, static hosts)
|
|
582
595
|
npx bluebird-js make:migration [name] # Smart auto-migration from app/models/
|
|
583
596
|
npx bluebird-js make:migration --model <Model> # Generates migration for specific Model
|
|
584
597
|
npx bluebird-js migrate [--yes] # Executes pending migrations
|
|
@@ -587,11 +600,11 @@ npx bluebird-js migrate:rollback # Reverts latest migration
|
|
|
587
600
|
npx bluebird-js make:seed <name> # Creates database seed file
|
|
588
601
|
npx bluebird-js seed # Executes database seeds
|
|
589
602
|
npx bluebird-js db:backup [--keep 10] [--out dir] # Compressed WAL-safe database backup with retention rotation
|
|
603
|
+
npx bluebird-js dev [entry] [--watch dir] # Dev server (Vite HMR) restarting only on server file changes
|
|
590
604
|
npx bluebird-js db:restore <file> [--yes] # Safe database restore with pre-backup & integrity check
|
|
591
605
|
npx bluebird-js nginx:conf [domain] [port] [root] # Generates Nginx reverse proxy configuration
|
|
592
606
|
npx bluebird-js make:ecosystem [--start] # Generates PM2 clustering config
|
|
593
607
|
npx bluebird-js add electron # Scaffolds Electron desktop app & desktop.js
|
|
594
|
-
npx bluebird-js add react-islands # Scaffolds React Islands, Vite & Client Router
|
|
595
608
|
npx bluebird-js add <module> # Installs optional on-demand package
|
|
596
609
|
```
|
|
597
610
|
|