@seip/bluebird-js 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.vscode/extensions.json +7 -0
  2. package/.vscode/settings.json +10 -0
  3. package/AGENTS.md +92 -60
  4. package/README.md +224 -152
  5. package/app/routes/web.js +47 -55
  6. package/app/views/about.jsx +98 -0
  7. package/app/views/components/Header.jsx +42 -0
  8. package/app/views/components/LiveCounter.jsx +67 -0
  9. package/app/views/dashboard.jsx +300 -0
  10. package/app/views/index.jsx +123 -0
  11. package/app/views/layouts/main/view.jsx +201 -0
  12. package/app/views/legal/terms.html +29 -19
  13. package/app/views/login.jsx +141 -0
  14. package/core/actions.d.ts +4 -0
  15. package/core/actions.js +329 -0
  16. package/core/app.js +38 -6
  17. package/core/cli/doctor.js +3 -4
  18. package/core/cli/init.js +20 -6
  19. package/core/cli/migrate.js +418 -145
  20. package/core/cli/view.js +76 -11
  21. package/core/database.js +6 -10
  22. package/core/debug.js +1 -1
  23. package/core/html.d.ts +54 -42
  24. package/core/html.js +473 -217
  25. package/core/index.d.ts +172 -84
  26. package/core/jsx.d.ts +38 -0
  27. package/core/jsx.js +1180 -0
  28. package/core/model.js +271 -61
  29. package/core/render-cache.js +212 -212
  30. package/core/render.d.ts +20 -2
  31. package/core/render.js +320 -43
  32. package/core/validate.js +1 -1
  33. package/core/view-loader.js +313 -22
  34. package/package.json +9 -3
  35. package/public/js/bluebird-client.js +2313 -1049
  36. package/public/js/tailwind.js +8 -0
  37. package/app/views/about.js +0 -63
  38. package/app/views/dashboard.js +0 -147
  39. package/app/views/index.js +0 -80
  40. package/app/views/layouts/main/view.js +0 -81
  41. package/app/views/login.js +0 -80
  42. package/public/css/bluebird.min.css +0 -2
  43. package/public/js/bluebird.min.js +0 -1073
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Bluebird.js Framework
2
2
 
3
- **Performance-first Node.js API and web framework with native JavaScript ESM, built-in JWT auth, HTML rendering, BaseModel, schema validation, and multi-level caching.**
3
+ **Performance-first Node.js API and web framework with native JavaScript ESM, built-in Tailwind CSS, Inter fonts, declarative UI components, JWT auth, BaseModel, smart migrations, and multi-level caching.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@seip/bluebird-js.svg)](https://www.npmjs.com/package/@seip/bluebird-js)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -10,17 +10,20 @@
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+). It provides native modern JavaScript ESM execution, HTML template rendering, multi-driver caching (in-memory by default with filesystem and Redis support), AES-256-GCM encrypted JWT authentication, BaseModel schema definitions, CSRF protection, background queues, and PM2 production clustering into a cohesive developer experience.
13
+ Bluebird.js (`@seip/bluebird-js`) is a high-performance web and API framework built on Express (Node.js 22.18+). It provides native modern JavaScript ESM execution, built-in Tailwind CSS v4 runtime and Google Fonts (`Inter`), zero-build SSR with React/Next.js-style component tags, multi-driver caching (in-memory LRU by default with filesystem and Redis support), AES-256-GCM encrypted JWT authentication, BaseModel schema definitions with smart migrations, CSRF protection, background queues, and PM2 production clustering into a cohesive developer experience.
14
14
 
15
15
  ### Key Highlights
16
16
 
17
- - **Pure Modern JavaScript (ESM):** Zero build steps, zero transpilation, pure Node.js 22.18+ ESM.
18
- - **Root Entrypoint (`index.js`):** Clean and intuitive architecture with the entry file directly at the root.
19
- - **Pure JavaScript Views & View Transitions:** Modern zero-build SSR with tagged template literals (html\`...\`), automatic XSS escaping, shared layouts, simple inline vanilla scripts, View Transitions SPA navigation, and uninterrupted audio/video streaming (data-persist="true").
20
- - **Lightweight BaseModel:** Static facade providing readable schemas, CRUD shortcuts, smart relations, soft deletes, automatic query cache invalidation, and validation bridges.
17
+ - **Native Zero-Build React JSX SSR (`app/views/*.jsx`):** Compiles `.jsx` modules in memory via Node 22.18+ `module.registerHooks()` with zero temporary disk files and zero build steps.
18
+ - **Declarative Auto-Routes from Views:** Export `const route`, `const cache`, `const middlewares`, `const layout`, and `const seo` directly from `app/views/*.jsx` to mount cached, protected web routes automatically (`noAutoDiscoverRoutes: true` in `new App()` to disable).
19
+ - **Client Islands with Anti-Accordion Skeletons (`<Client>` / `<Island>`):** SSR by default (0 KB client JS), with `<Client>` boundaries that lock dimensions (`minHeight`, `minWidth`) and render a `skeleton` to prevent layout shift (CLS).
20
+ - **Built-In Tailwind CSS & Inter Font:** Includes the official standalone Tailwind CSS runtime (`/js/tailwind.js`) and Google Fonts `Inter` by default with zero configuration or compilers.
21
+ - **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.
22
+ - **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.
21
23
  - **Native SQLite & Desktop Mode (Electron/Tauri):** Uses Node's built-in `node:sqlite` driver with zero compilation overhead, plus first-class `desktop: true` mode (`app.runDesktop()`) for read-only `.asar` bundles.
24
+ - **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.
22
25
  - **Decoupled Caching:** High-speed in-memory LRU cache by default, persistent filesystem fallback, and modular Redis support via `core/redis.js`.
23
- - **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection, built-in Rate Limiter (`rateLimit` in `App` or `App.rateLimit()`), automatic `/sitemap.xml` & `/robots.txt` generation, and secure HTTP headers without external bloat.
26
+ - **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection, built-in Rate Limiter (`rateLimit` in `App` or `App.rateLimit()`), automatic `/sitemap.xml` & `/robots.txt` generation, and secure HTTP headers.
24
27
  - **Production Ready:** Built-in PM2 clustering CLI (`npx bluebird-js make:ecosystem`), optimized Nginx generator (`npx bluebird-js nginx:conf`), and native runner (`npm start`).
25
28
 
26
29
  ---
@@ -67,32 +70,29 @@ project/
67
70
  │ ├── routes/ # Application routes
68
71
  │ │ ├── api.js # REST API routes
69
72
  │ │ └── web.js # HTML page routes
70
- │ ├── views/ # Pure JavaScript ESM views
71
- │ │ ├── layouts/ # Shared page layouts (e.g. main/view.js)
72
- │ │ ├── index.js # Public home view
73
- │ │ ├── about.js # About page view
74
- │ │ ├── login.js # Sign-in page view
75
- │ │ └── dashboard.js # Protected dashboard view
73
+ │ ├── views/ # React JSX (.jsx) & JavaScript (.js) SSR views
74
+ │ │ ├── components/ # Reusable JSX components (e.g. Header.jsx)
75
+ │ │ ├── layouts/ # Shared page layouts (e.g. main/view.jsx)
76
+ │ │ ├── index.jsx # Public home view (Auto-Route: /)
77
+ │ │ ├── about.jsx # About page view (Auto-Route: /about)
78
+ │ │ ├── login.jsx # Sign-in page view (Auto-Route: /login)
79
+ │ │ └── dashboard.jsx # Protected dashboard view (Auto-Route: /dashboard)
76
80
  │ └── jobs/ # Background worker job handlers
77
- ├── src/ # Frontend source (React Islands)
78
- │ └── islands/ # Interactive React island components
79
81
  ├── public/ # Public static assets (CSS, JS, images, fonts)
80
- │ ├── css/
81
82
  │ ├── js/
82
- │ │ └── bluebird-client.js # View Transitions, partial swaps & islands runtime
83
- │ └── dist/ # Production Vite hashed bundles
83
+ │ │ ├── tailwind.js # Built-in Tailwind CSS runtime
84
+ │ │ └── bluebird-client.js # Client UI kit, View Transitions & SPA router
85
+ │ └── images/
84
86
  ├── core/ # Bluebird.js framework core
85
87
  ├── database/ # SQLite storage and SQL migrations
86
- │ └── migrations/
87
- ├── ecosystem.config.cjs # PM2 cluster configuration (production)
88
- ├── production.md # Production deployment guide
88
+ │ └── migrations/ # Version-controlled SQL migrations
89
89
  ├── .env # Environment variables
90
90
  └── package.json
91
91
  ```
92
92
 
93
93
  ---
94
94
 
95
- ## Usage Examples
95
+ ## Core Features & Usage Examples
96
96
 
97
97
  ### 1. Application Entrypoint (`index.js`)
98
98
 
@@ -119,11 +119,15 @@ const app = new App({
119
119
  routes: [routerWeb, routerApi],
120
120
  });
121
121
 
122
- const { url } = await app.runDesktop();
122
+ const { url, lanUrl } = await app.runDesktop({ allowLan: true });
123
123
  mainWindow.loadURL(url);
124
124
  ```
125
125
 
126
- ### 2. Defining a Model (`app/models/user.js`)
126
+ ---
127
+
128
+ ### 2. BaseModel & Smart Automatic Migrations (`app/models/`)
129
+
130
+ #### Defining a Model (`app/models/user.js`)
127
131
 
128
132
  ```javascript
129
133
  import Model from "@seip/bluebird-js/core/model.js";
@@ -144,189 +148,253 @@ export default class User extends Model {
144
148
  }
145
149
  ```
146
150
 
147
- ### 3. REST API Routes (`app/routes/api.js`)
151
+ #### Foreign Key References (`app/models/post.js`)
148
152
 
149
153
  ```javascript
150
- import App from "@seip/bluebird-js/core/app.js";
151
- import Router from "@seip/bluebird-js/core/router.js";
152
- import User from "../models/user.js";
154
+ import Model from "@seip/bluebird-js/core/model.js";
155
+
156
+ export default class Post extends Model {
157
+ static table = "posts";
158
+ static schema = {
159
+ id: { type: "int", primary: true, auto: true },
160
+ title: { type: "string", length: 200, required: true },
161
+ content: { type: "text" },
162
+ author_id: { type: "int", references: "users.id", onDelete: "cascade" },
163
+ };
164
+ }
165
+ ```
153
166
 
154
- const routerApi = new Router("/api");
167
+ #### Powerful Query Methods
155
168
 
156
- routerApi.get("/users", async (req, res) => {
157
- const users = await User.all({ limit: 50, order: "id DESC" });
158
- res.ok({ users });
169
+ ```javascript
170
+ const totalUsers = await User.count({ role: "user" });
171
+ const userExists = await User.exists({ email: "alice@example.com" });
172
+
173
+ const activeUsers = await User.all({
174
+ where: {
175
+ id: [1, 2, 3],
176
+ role: { $ne: "banned" },
177
+ views: { $gt: 100 },
178
+ },
159
179
  });
160
180
 
161
- routerApi.post(
162
- "/users",
163
- App.rateLimit({ max: 10, windowMs: 60000 }),
164
- User.validator("create").middleware(),
165
- async (req, res) => {
166
- const userId = await User.create(req.body);
167
- res.created({ id: userId }, "User created successfully");
168
- }
181
+ const user = await User.firstOrCreate(
182
+ { email: "john@example.com" },
183
+ { name: "John Doe", role: "user" }
169
184
  );
170
185
 
171
- export default routerApi;
186
+ const updated = await User.updateOrCreate(
187
+ { email: "john@example.com" },
188
+ { name: "Johnathan Doe" }
189
+ );
172
190
  ```
173
191
 
174
- ### 4. HTML Views, Layouts & Server Partials (`app/routes/web.js`)
192
+ #### Smart Automatic Migrations CLI
175
193
 
176
- When `{ seo: true }` is enabled on a router, Bluebird automatically generates `/sitemap.xml` and `/robots.txt`:
194
+ When you create or modify models, simply run:
177
195
 
178
- ```javascript
179
- import Router from "@seip/bluebird-js/core/router.js";
180
- import Render from "@seip/bluebird-js/core/render.js";
196
+ ```bash
197
+ npx bluebird-js make:migration
198
+ ```
181
199
 
182
- const routerWeb = new Router("/", { seo: true });
200
+ Bluebird inspects your models in `app/models/`, connects to your database, sorts tables by foreign key dependencies topologically, and detects all missing tables and columns (`CREATE TABLE` and `ALTER TABLE ADD COLUMN`). It generates a consolidated SQL migration file and asks:
183
201
 
184
- routerWeb.get("/", Render.view("index", { title: "Bluebird Application" }));
185
- routerWeb.get("/stats-card", (req, res) => {
186
- return Render.partial(res, "stat_card", { label: "Revenue", val: "$12,400", active: true });
187
- });
202
+ ```
203
+ [INFO] Detected database schema changes:
204
+ + CREATE TABLE: users
205
+ + CREATE TABLE: posts
206
+ [OK] Migration created: database/migrations/20261022_120000_auto_migration.sql
207
+ ? Do you want to execute pending migrations now? (Y/n):
208
+ ```
188
209
 
189
- export default routerWeb;
210
+ To run migrations directly without prompts (ideal for CI/CD):
211
+ ```bash
212
+ npx bluebird-js migrate --yes
190
213
  ```
191
214
 
192
- Inside your views (`app/views/dashboard.js`), use pure JavaScript functions with `html` tagged templates and plain vanilla `<script>` tags:
215
+ ---
216
+
217
+ ### 3. React JSX SSR, Declarative Auto-Routes & `<Client>` Skeletons
193
218
 
194
- ```javascript
195
- // app/views/dashboard.js
196
- import { html } from "@seip/bluebird-js/core/html.js";
219
+ #### Default Tailwind CSS & Inter Typography
197
220
 
198
- export const layout = "main";
199
- export const head = (data) => ({ title: `Dashboard — ${data.user?.name || "Member"}` });
221
+ The default layout (`app/views/layouts/main/view.jsx`) comes pre-wired with Google Fonts `Inter` and the standalone Tailwind CSS v4 runtime (`/js/tailwind.js`). You can write pure Tailwind utility classes immediately without running Vite, PostCSS, or Tailwind CLI.
200
222
 
201
- export default function DashboardView({ user, metrics }) {
202
- const initial = metrics?.unread || 0;
223
+ #### Native `.jsx` Views & Declarative Auto-Routes
203
224
 
204
- return html`
205
- <section class="dashboard-grid">
206
- <h1>Welcome back, ${user.name}</h1>
225
+ Bluebird compiles `.jsx` files in memory using Node's native module hooks (`core/jsx.js`)—no external bundler or disk temp files required. Even better, any view inside `app/views/` (excluding `layouts/`, `components/`, `partials/`, `islands/`, and `/api`) can export its own route configuration (`route`, `cache`, `middlewares`, `layout`, `seo`) and `App` mounts it automatically on startup (pass `noAutoDiscoverRoutes: true` to `new App()` if you prefer manual registration only):
207
226
 
208
- <div class="card">
209
- <button id="btnDec" class="btn-sm">-</button>
210
- <span id="counter" class="font-bold">${initial}</span>
211
- <button id="btnInc" class="btn-sm">+</button>
227
+ ```jsx
228
+ // app/views/components/Header.jsx
229
+ export default function Header({ title, user, count = 0 }) {
230
+ return (
231
+ <header className="flex items-center justify-between p-6 border-b border-slate-800">
232
+ <div>
233
+ <h1 className="text-2xl font-bold text-slate-100">{title}</h1>
234
+ <p className="text-sm text-slate-400">Welcome back, {user?.name || "Guest"}</p>
212
235
  </div>
213
- </section>
214
-
215
- <!-- Native inline script: clean, readable, zero build steps -->
216
- <script>
217
- (() => {
218
- let count = ${initial};
219
- const el = document.getElementById("counter");
220
- document.getElementById("btnInc")?.addEventListener("click", () => {
221
- count++;
222
- if (el) el.textContent = count;
223
- });
224
- document.getElementById("btnDec")?.addEventListener("click", () => {
225
- if (count > 0) count--;
226
- if (el) el.textContent = count;
227
- });
228
- })();
229
- </script>
230
- `;
236
+ <span className="px-3 py-1 rounded-full text-xs font-semibold bg-sky-500/10 text-sky-400 border border-sky-500/20">
237
+ Notifications: {count}
238
+ </span>
239
+ </header>
240
+ );
231
241
  }
232
242
  ```
233
243
 
234
- > **Live Reload:** When running development (`npm run dev` with `node --watch`), Bluebird automatically reloads the browser tab via native Server-Sent Events whenever changes trigger a server restart. No plugins or browser extensions needed.
244
+ ```jsx
245
+ // app/views/dashboard.jsx
246
+ import Auth from "@seip/bluebird-js/core/auth.js";
247
+ import Actions from "@seip/bluebird-js/core/actions.js";
248
+ import { Client } from "@seip/bluebird-js/core/jsx.js";
249
+ import Header from "./components/Header.jsx";
250
+ import LiveCounter from "./components/LiveCounter.js";
235
251
 
236
- > **Architecture Tip:** Keep business operations, third-party APIs, and database transactions in `app/services/` or `app/models/`. Views should remain declarative, lightweight, and focused on presentation.
252
+ export const route = "/dashboard";
253
+ export const layout = "main";
254
+ export const middlewares = [Auth.protect({ redirect: "/login" })];
255
+ export const seo = false;
256
+ export const head = (data) => ({ title: `Dashboard — ${data.user?.name || "Member"}` });
237
257
 
238
- ### 5. Multi-Driver Caching (`core/cache.js`)
258
+ // Server Actions: automatic CSRF, 16KB maxBytes guard, prototype pollution filter & Validator schema
259
+ export const actions = {
260
+ syncCount: Actions.define(
261
+ {
262
+ maxBytes: "16kb",
263
+ schema: { count: { required: true, number: true } },
264
+ },
265
+ async ({ body, user }) => {
266
+ return { syncedCount: Number(body.count), updatedBy: user?.email };
267
+ }
268
+ ),
269
+ };
270
+
271
+ export default async function DashboardView({ user, syncedCount = 7 }) {
272
+ return (
273
+ <>
274
+ <Header title="Protected Dashboard" user={user} count={syncedCount} />
275
+
276
+ <div className="space-y-6 mt-6">
277
+ {/* Reusable imported Client component with persistent state & anti-CLS skeleton */}
278
+ <Client
279
+ component={LiveCounter}
280
+ props={{ initial: syncedCount }}
281
+ persistent={true}
282
+ minHeight={56}
283
+ skeleton={
284
+ <div className="h-14 rounded-xl bg-slate-900 animate-pulse flex items-center px-4 text-xs text-slate-400">
285
+ Loading interactive widget...
286
+ </div>
287
+ }
288
+ />
289
+ </div>
290
+ </>
291
+ );
292
+ }
293
+ ```
294
+
295
+ ---
296
+
297
+ ### 4. Built-in Client UI Kit (`public/js/bluebird-client.js`)
298
+
299
+ Bluebird includes a lightweight, dependency-free client UI toolkit with Tailwind CSS styles built right into `public/js/bluebird-client.js`:
300
+
301
+ #### Toasts & Snackbars
239
302
 
240
303
  ```javascript
241
- import Cache from "@seip/bluebird-js/core/cache.js";
304
+ toast({
305
+ title: "Profile Updated",
306
+ description: "Your settings have been saved successfully.",
307
+ type: "success",
308
+ position: "top-right",
309
+ duration: 4000,
310
+ });
242
311
 
243
- await Cache.set("metrics", { activeUsers: 450 }, 60, { driver: "memory" });
244
- const metrics = await Cache.get("metrics", { driver: "memory" });
312
+ snackbar({ message: "Network connection restored", type: "info" });
313
+ ```
245
314
 
246
- await Cache.set("report", htmlContent, 300, { driver: "file" });
315
+ Or trigger them declaratively via HTML attributes:
316
+ ```html
317
+ <button data-toast="Settings saved successfully!" data-toast-type="success">Save</button>
318
+ <button data-snackbar="Item deleted" data-snackbar-type="error">Delete</button>
247
319
  ```
248
320
 
249
- ### 6. Raw Static HTML Delivery (`Render.html`)
321
+ #### Drawers & Mobile Navigation
250
322
 
251
- For static legal documents, terms of service, or offline pages without server-side templating overhead:
323
+ ```html
324
+ <button data-drawer-target="cartDrawer">Open Cart</button>
252
325
 
253
- ```javascript
254
- routerWeb.get("/terms", (req, res) => Render.html(res, "legal/terms.html", { ttl: 86400 }));
326
+ <div id="cartDrawer" class="hidden fixed top-0 right-0 h-full w-80 bg-slate-900 p-6 z-50">
327
+ <button data-drawer-close="cartDrawer" class="text-slate-400">&times;</button>
328
+ <h3>Shopping Cart</h3>
329
+ </div>
255
330
  ```
256
331
 
257
- ---
332
+ #### Responsive Data Table (`ResponsiveDataTable`)
258
333
 
259
- ## Desktop Applications (Electron & Desktop Mode)
334
+ Transforms tables dynamically into touch-friendly cards on mobile devices:
260
335
 
261
- Bluebird.js runs natively embedded inside **Electron** applications with zero child processes, ultra-fast boot (<200ms), and minimal RAM consumption (~25–40 MB vs ~300 MB with Nextron/Next.js):
336
+ ```javascript
337
+ new ResponsiveDataTable("usersTableContainer", {
338
+ columns: [
339
+ { key: "id", label: "ID", sortable: true },
340
+ { key: "name", label: "Name", sortable: true },
341
+ { key: "email", label: "Email" },
342
+ { key: "role", label: "Role" },
343
+ ],
344
+ data: usersList,
345
+ searchable: true,
346
+ pagination: true,
347
+ pageSize: 10,
348
+ onEdit: (row) => editUser(row.id),
349
+ onDelete: (row) => deleteUser(row.id),
350
+ });
351
+ ```
262
352
 
263
- - **Automatic Writable Paths:** Routes SQLite database, `logs/`, `app/cache/`, and file uploads (`Upload.storage()`) to `Config.userDataDir()` (`app.getPath("userData")`) to avoid read-only errors inside `.asar` archives.
264
- - **Dynamic Port & LAN / QR Access:** Binds to dynamic port `0` and generates LAN URLs (`allowLan: true`) for companion mobile/QR code access.
265
- - **Clean WAL Shutdown:** `await app.close()` truncates SQLite WAL and frees file locks cleanly on Windows/Mac/Linux.
353
+ #### Declarative SPA Forms (`data-bb-form`)
266
354
 
267
- ### Scaffold with a Single Command:
268
- ```bash
269
- npx bluebird-js add electron
355
+ ```html
356
+ <form action="/api/profile" method="POST" data-bb-form="true">
357
+ <input type="text" name="name" required />
358
+ <button type="submit">Update</button>
359
+ </form>
270
360
  ```
271
- This installs `electron` and `electron-builder`, generates `desktop.js`, and configures build scripts in your `package.json`.
361
+ Submissions are automatically handled via `fetch`, CSRF tokens are injected, and toasts/redirects are handled seamlessly via View Transitions.
272
362
 
273
- ### `desktop.js` Entrypoint:
274
- ```javascript
275
- import { app as electronApp, BrowserWindow, shell } from "electron";
276
- import App from "@seip/bluebird-js/core/app.js";
277
- import routerWeb from "./app/routes/web.js";
278
- import routerApi from "./app/routes/api.js";
363
+ #### Declarative DOM Helpers
279
364
 
280
- const app = new App({
281
- desktop: true,
282
- appPath: electronApp.getAppPath(),
283
- userDataPath: electronApp.getPath("userData"),
284
- routes: [routerWeb, routerApi],
285
- });
365
+ - `data-copy="Text to copy"`: Copies text to clipboard on click.
366
+ - `data-confirm="Are you sure?"`: Confirms before link navigation or button click.
367
+ - `data-toggle="theme"`: Switches between dark and light modes and updates the `dark` class on `<html>`.
368
+ - `data-password-toggle="passwordFieldId"`: Toggles password visibility.
369
+ - `data-filter-target="tableId"`: Live filters rows or cards matching input value.
286
370
 
287
- electronApp.whenReady().then(async () => {
288
- const { url, lanUrl } = await app.runDesktop({ allowLan: true });
289
-
290
- const mainWindow = new BrowserWindow({
291
- width: 1280,
292
- height: 800,
293
- minWidth: 900,
294
- minHeight: 600,
295
- webPreferences: {
296
- nodeIntegration: false,
297
- contextIsolation: true,
298
- },
299
- });
371
+ ---
300
372
 
301
- mainWindow.loadURL(url);
373
+ ### 5. Multi-Driver Caching (`core/cache.js`)
302
374
 
303
- mainWindow.webContents.setWindowOpenHandler(({ url }) => {
304
- if (!url.startsWith("http://127.0.0.1") && !url.startsWith("http://localhost")) {
305
- shell.openExternal(url);
306
- return { action: "deny" };
307
- }
308
- return { action: "allow" };
309
- });
375
+ ```javascript
376
+ import Cache from "@seip/bluebird-js/core/cache.js";
310
377
 
311
- electronApp.on("before-quit", async () => {
312
- await app.close();
313
- });
314
- });
378
+ await Cache.set("metrics", { activeUsers: 450 }, 60, { driver: "memory" });
379
+ const metrics = await Cache.get("metrics", { driver: "memory" });
380
+
381
+ await Cache.set("report", htmlContent, 300, { driver: "file" });
315
382
  ```
316
383
 
317
384
  ---
318
385
 
319
- ## Production Deployment
386
+ ### 6. Desktop Applications (Electron & Desktop Mode)
320
387
 
321
- Bluebird.js supports direct Node.js execution and PM2 process clustering out of the box:
388
+ 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):
389
+
390
+ - **Automatic Writable Paths:** Routes SQLite database, `logs/`, `app/cache/`, and file uploads (`Upload.storage()`) to `Config.userDataDir()` (`app.getPath("userData")`) to avoid read-only errors inside `.asar` archives.
391
+ - **Dynamic Port & LAN / QR Access:** Binds to dynamic port `0` and generates LAN URLs (`allowLan: true`) for companion mobile/QR code access.
392
+ - **Clean WAL Shutdown:** `await app.close()` truncates SQLite WAL and frees file locks cleanly on Windows/Mac/Linux.
322
393
 
323
394
  ```bash
324
- npm start # Starts via Node.js
325
- npx bluebird-js make:ecosystem --start # Generates ecosystem config and launches via PM2
395
+ npx bluebird-js add electron
326
396
  ```
327
397
 
328
- For complete instructions covering PM2, systemd services, Nginx reverse proxy setup, and optional standalone Docker configurations, read the [Production Guide](production.md).
329
-
330
398
  ---
331
399
 
332
400
  ## Developer Tooling CLI
@@ -336,12 +404,16 @@ npx bluebird-js doctor # Diagnostic audit and HTT
336
404
  npx bluebird-js make:model <Name> # Generates BaseModel class
337
405
  npx bluebird-js make:route <name> [--auth] # Scaffolds REST route
338
406
  npx bluebird-js make:view <name> [--ejs] # Scaffolds HTML/EJS template
339
- npx bluebird-js make:migration <name> [--model <M>] # Generates database migration
340
- npx bluebird-js migrate # Executes pending migrations
407
+ npx bluebird-js make:migration [name] # Smart auto-migration from app/models/
408
+ npx bluebird-js make:migration --model <Model> # Generates migration for specific Model
409
+ npx bluebird-js migrate [--yes] # Executes pending migrations
410
+ npx bluebird-js migrate:status # Displays applied migration batches
411
+ npx bluebird-js migrate:rollback # Reverts latest migration batch
412
+ npx bluebird-js make:seed <name> # Creates database seed file
341
413
  npx bluebird-js seed # Executes database seeds
342
414
  npx bluebird-js nginx:conf [domain] [port] [root] # Generates Nginx reverse proxy configuration
343
415
  npx bluebird-js make:ecosystem [--start] # Generates PM2 clustering config
344
- npx bluebird-js add electron # Scaffolds Electron desktop app, desktop.js & build config
416
+ npx bluebird-js add electron # Scaffolds Electron desktop app & desktop.js
345
417
  npx bluebird-js add react-islands # Scaffolds React Islands, Vite & Client Router
346
418
  npx bluebird-js add <module> # Installs optional on-demand package
347
419
  ```
package/app/routes/web.js CHANGED
@@ -1,55 +1,47 @@
1
- import Router from "@seip/bluebird-js/core/router.js";
2
- import Render from "@seip/bluebird-js/core/render.js";
3
- import Auth from "@seip/bluebird-js/core/auth.js";
4
-
5
- const routerWeb = new Router("/", { seo: true });
6
-
7
- routerWeb.get("/", Render.cache(300), Render.view("index"));
8
-
9
- routerWeb.get("/about", Render.cache(300), Render.view("about"));
10
-
11
- routerWeb.get("/terms", (req, res) => Render.html(res, "legal/terms.html", { ttl: 86400 }));
12
-
13
- routerWeb.get("/login", Render.view("login"));
14
-
15
- routerWeb.post("/login", async (req, res) => {
16
- const email = req.body?.email || "alex@example.com";
17
- const rawPrefix = email.split("@")[0] || "alex";
18
- const name = req.body?.name || (rawPrefix.charAt(0).toUpperCase() + rawPrefix.slice(1));
19
-
20
- const user = {
21
- id: 1,
22
- name,
23
- email,
24
- role: "admin",
25
- };
26
-
27
- await Auth.login(res, user);
28
- return res.redirect("/dashboard");
29
- });
30
-
31
- routerWeb.get("/logout", async (req, res) => {
32
- if (
33
- req.headers["x-bluebird-prefetch"] ||
34
- req.headers.purpose === "prefetch" ||
35
- req.headers["sec-purpose"] === "prefetch"
36
- ) {
37
- return res.status(204).end();
38
- }
39
- await Auth.logout(res);
40
- return res.redirect("/login");
41
- });
42
-
43
- routerWeb.post("/logout", async (req, res) => {
44
- await Auth.logout(res);
45
- return res.redirect("/login");
46
- });
47
-
48
- routerWeb.get("/dashboard", Auth.protect({ redirect: "/login" }), async (req, res) => {
49
- await Render.send(res, "dashboard", {
50
- title: "Dashboard — Blue Bird",
51
- user: req.user,
52
- });
53
- });
54
-
55
- export default routerWeb;
1
+ import Router from "@seip/bluebird-js/core/router.js";
2
+ import Render from "@seip/bluebird-js/core/render.js";
3
+ import Auth from "@seip/bluebird-js/core/auth.js";
4
+
5
+ /**
6
+ * Web Router for custom actions and static HTML files.
7
+ * Page GET routes (`/`, `/about`, `/login`, `/dashboard`) are automatically
8
+ * generated from `app/views/*.jsx` via declarative exports (`route`, `cache`, `middlewares`, `layout`, `seo`).
9
+ */
10
+ const routerWeb = new Router("/", { seo: true });
11
+
12
+ routerWeb.get("/terms", (req, res) => Render.html(res, "legal/terms.html", { ttl: 86400 }));
13
+
14
+ routerWeb.post("/login", async (req, res) => {
15
+ const email = req.body?.email || "alex@example.com";
16
+ const rawPrefix = email.split("@")[0] || "alex";
17
+ const name = req.body?.name || (rawPrefix.charAt(0).toUpperCase() + rawPrefix.slice(1));
18
+
19
+ const user = {
20
+ id: 1,
21
+ name,
22
+ email,
23
+ role: "admin",
24
+ };
25
+
26
+ await Auth.login(res, user);
27
+ return res.redirect("/dashboard");
28
+ });
29
+
30
+ routerWeb.get("/logout", async (req, res) => {
31
+ if (
32
+ req.headers["x-bluebird-prefetch"] ||
33
+ req.headers.purpose === "prefetch" ||
34
+ req.headers["sec-purpose"] === "prefetch"
35
+ ) {
36
+ return res.status(204).end();
37
+ }
38
+ await Auth.logout(res);
39
+ return res.redirect("/login");
40
+ });
41
+
42
+ routerWeb.post("/logout", async (req, res) => {
43
+ await Auth.logout(res);
44
+ return res.redirect("/login");
45
+ });
46
+
47
+ export default routerWeb;