@nexa-stack/framework 1.0.0

package/.env.example

@@ -0,0 +1,46 @@
+# Nexa
+DB_PATH=./app.db
+APP_URL=http://localhost:3333
+
+# PostgreSQL
+# DATABASE_URL=postgresql://user:pass@localhost:5432/nexa
+
+# MySQL / MariaDB
+# DATABASE_URL=mysql://user:pass@localhost:3306/nexa
+
+PORT=3333
+# REQUIRED in production — use a long random string
+APP_SECRET=change-me-in-production
+APP_LOCALE=en
+
+# Optional admin seed (created only if no admin exists)
+# ADMIN_EMAIL=admin@nexa.dev
+# ADMIN_PASSWORD=123456
+
+# Mail: log (dev) | smtp
+MAIL_DRIVER=log
+MAIL_FROM=nexa@localhost
+
+# Cache: memory | file | redis
+CACHE_DRIVER=memory
+
+# Uploads (bytes) — default 5MB
+UPLOAD_MAX_BYTES=5000000
+
+# Rate limit: memory (default) | redis (multi-instance; needs CACHE_DRIVER=redis or RATE_LIMIT_DRIVER=redis)
+# RATE_LIMIT_DRIVER=redis
+# REDIS_URL=redis://127.0.0.1:6379
+
+# List API cache TTL in seconds (0 = off). Speeds read-heavy apps behind multiple instances when using redis cache.
+# LIST_CACHE_TTL=15
+
+# Optional: allow public sign-up (default: on in dev, off when NODE_ENV=production)
+# AUTH_REGISTER=true
+
+# Auth brute-force limit (POST /api/auth/* per IP per minute)
+# AUTH_RATE_LIMIT=10
+
+# Hot reload (dev only — off in NODE_ENV=production)
+# HOT_RELOAD=false
+
+LOG_LEVEL=debug

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# Nexa
+
+Write little → ship a full backend. Goal: **hours, not weeks.**
+
+Runs on **Node.js ≥ 20** (Hostinger-friendly). Default UI language is **English**.
+
+## Quick start
+
+```bash
+npx @nexa-stack/framework new my-app
+cd my-app
+npm install
+npm run serve
+```
+
+→ http://localhost:3333  
+→ http://localhost:3333/admin  
+→ Login: `admin@nexa.dev` / `123456`
+
+## The idea
+
+```ts
+import { resource, string, money, belongsTo, select } from "@nexa-stack/framework";
+
+resource("orders", {
+  client: belongsTo("clients").required().label("Client"),
+  total: money().required().label("Total"),
+  status: select(["new", "paid"]).label("Status"),
+}, { label: "Orders" }).admin();
+```
+
+That gives you: database table + REST API + admin panel.
+
+Optional power tools:
+
+```ts
+await db.from("orders").where("status", "paid").with("client").get();
+```
+
+## Commands
+
+| Command | What it does |
+|---------|----------------|
+| `nexa serve` | Start server |
+| `nexa new X` | Scaffold a project |
+| `nexa make:resource X` | Add `resources/X.ts` (auto-loaded) |
+
+## Localization
+
+- Default: `APP_LOCALE=en`
+- Arabic UI: set `APP_LOCALE=ar` and use `lang/ar.json`
+- Admin has EN / عربي switch either way
+
+## Hostinger / production
+
+Prefer MySQL on shared hosting:
+
+```env
+DATABASE_URL=mysql://user:pass@localhost:3306/dbname
+APP_SECRET=long-random-secret-at-least-32-chars
+NODE_ENV=production
+```
+
+SQLite uses `sql.js` (no Visual Studio / node-gyp).
+
+## Docs
+
+- [docs/START.md](./docs/START.md) — start here  
+- [docs/REFERENCE.md](./docs/REFERENCE.md) — full API reference  
+- After `nexa serve`: http://localhost:3333/docs  
+
+Package: [`@nexa-stack/framework`](https://www.npmjs.com/package/@nexa-stack/framework)

package/bin/nexa.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Resolve tsx from this package (works with npx / bunx / local install).
+ * Avoids bare `--import tsx` which resolves from an empty cwd cache.
+ */
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const dir = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(dir, "..");
+const require = createRequire(join(pkgRoot, "package.json"));
+
+let tsxLoader;
+try {
+  tsxLoader = require.resolve("tsx/esm");
+} catch {
+  try {
+    tsxLoader = require.resolve("tsx");
+  } catch {
+    console.error(
+      "[nexa] Missing dependency `tsx`.\n" +
+        "  Fix: npm install @nexa-stack/framework\n" +
+        "  Or:  cd your-app && npm install"
+    );
+    process.exit(1);
+  }
+}
+
+const result = spawnSync(
+  process.execPath,
+  [
+    "--import",
+    pathToFileURL(tsxLoader).href,
+    join(dir, "nexa.ts"),
+    ...process.argv.slice(2),
+  ],
+  { stdio: "inherit", env: process.env, cwd: process.cwd() }
+);
+process.exit(result.status ?? 1);

package/bin/nexa.ts

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+import { mkdirSync, existsSync, cpSync, writeFileSync, readFileSync } from "fs";
+import { join } from "path";
+import { spawnSync } from "node:child_process";
+import { moduleDir } from "../packages/core/src/runtime.js";
+
+const here = moduleDir(import.meta.url);
+const frameworkRoot = join(here, "..").replace(/\\/g, "/");
+const frameworkPkg = JSON.parse(readFileSync(join(here, "../package.json"), "utf8"));
+const PKG = frameworkPkg.name as string;
+const PKG_VERSION = frameworkPkg.version as string;
+
+const [command, ...args] = process.argv.slice(2);
+const arg = args[0];
+
+const help = `
+Nexa — ship a full backend in hours
+
+  nexa serve              Start the server
+  nexa new my-app         Create a new project
+  nexa make:resource X    New resource file (auto-loaded)
+  nexa migrate            Sync database tables
+  nexa migrate:rollback   Roll back last file migration
+  nexa db:seed            Run seeders
+  nexa queue:work         Queue worker (scale)
+  nexa queue:work once    Process one batch
+  nexa schedule:work      Run scheduled tasks
+  nexa test               Run tests
+`;
+
+const cwd = process.cwd().replace(/\\/g, "/");
+const appUrl = new URL(`file:///${cwd}/app.ts`).href;
+
+async function loadApp() {
+  await import(appUrl);
+  const { loadResources } = await import("../packages/core/src/loader.js");
+  await loadResources(cwd);
+}
+
+async function withDb() {
+  await loadApp();
+  const { runMigrations } = await import("../packages/core/src/migrate.js");
+  const { loadEnv } = await import("../packages/core/src/config.js");
+  const { dbConnection } = await import("../packages/database/src/database.js");
+  loadEnv();
+  return runMigrations(dbConnection());
+}
+
+if (command === "serve" || command === "run") {
+  await loadApp();
+  const { start } = await import("../packages/core/src/app.js");
+  await start();
+} else if (command === "new" && arg) {
+  const name = arg.toLowerCase().replace(/[^a-z0-9-_]/g, "-");
+  const dir = join(process.cwd(), name);
+  if (existsSync(dir)) {
+    console.error(`Exists: ${dir}`);
+    process.exit(1);
+  }
+  mkdirSync(join(dir, "public"), { recursive: true });
+  mkdirSync(join(dir, "resources"), { recursive: true });
+  mkdirSync(join(dir, "lang"), { recursive: true });
+  mkdirSync(join(dir, "database", "seeders"), { recursive: true });
+  const frameworkPath = frameworkRoot;
+  const isPublishedInstall = here.replace(/\\/g, "/").includes("/node_modules/");
+  const depVersion = isPublishedInstall ? `^${PKG_VERSION}` : `file:${frameworkPath}`;
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify(
+      {
+        name,
+        private: true,
+        type: "module",
+        scripts: {
+          serve: "nexa serve",
+          start: "nexa serve",
+          nexa: "nexa",
+        },
+        dependencies: { [PKG]: depVersion },
+        engines: { node: ">=20" },
+      },
+      null,
+      2
+    )
+  );
+  writeFileSync(
+    join(dir, "app.ts"),
+    `import { resource, string, text, boolean } from "${PKG}";
+
+// Prefer extra tables in resources/*.ts (auto-loaded)
+resource("posts", {
+  title: string().required().label("Title"),
+  body: text().label("Body"),
+  published: boolean().label("Published"),
+}, { label: "Posts" }).admin();
+`
+  );
+  writeFileSync(
+    join(dir, ".env"),
+    `DB_PATH=./app.db
+PORT=3333
+APP_SECRET=change-me-in-dev-only
+APP_LOCALE=en
+`
+  );
+  writeFileSync(
+    join(dir, ".gitignore"),
+    `node_modules/
+.env
+*.db
+*.db-shm
+*.db-wal
+storage/
+`
+  );
+  writeFileSync(
+    join(dir, "README.md"),
+    `# ${name}
+
+Nexa app — quick start.
+
+## Run
+
+\`\`\`bash
+npm install
+npm run serve
+\`\`\`
+
+| URL | |
+|-----|---|
+| Home | http://localhost:3333 |
+| Admin | http://localhost:3333/admin |
+| Docs | http://localhost:3333/docs |
+
+**Admin login:** \`admin@nexa.dev\` / \`123456\`
+
+Default UI language is **English**. For Arabic set \`APP_LOCALE=ar\`.
+
+## New table
+
+\`\`\`bash
+npx nexa make:resource products
+npx nexa migrate
+\`\`\`
+
+Files in \`resources/*.ts\` load automatically (hot reload in development).
+
+## Example resource
+
+\`\`\`ts
+import { resource, string, money, belongsTo } from "${PKG}";
+
+resource("orders", {
+  client: belongsTo("clients").required().label("Client"),
+  total: money().required(),
+}, { label: "Orders" }).admin();
+\`\`\`
+
+## Hostinger / production
+
+Prefer MySQL on shared hosting:
+
+\`\`\`
+DATABASE_URL=mysql://user:pass@localhost:3306/dbname
+APP_SECRET=use-a-long-random-secret
+NODE_ENV=production
+\`\`\`
+
+\`.admin()\` enables API + admin UI + auth + soft deletes by default.
+
+## Full API reference
+
+- After install: \`node_modules/${PKG}/docs/REFERENCE.md\`
+- Or http://localhost:3333/docs
+
+## Production checklist
+
+\`\`\`env
+NODE_ENV=production
+APP_SECRET=random-string-at-least-32-chars
+# AUTH_REGISTER=true   # only if you want public sign-up
+\`\`\`
+
+## Commands
+
+| Command | |
+|---------|---|
+| \`npm run serve\` | Start server |
+| \`npx nexa make:resource X\` | New resource |
+| \`npx nexa migrate\` | Sync DB |
+| \`npx nexa queue:work\` | Queue worker |
+
+---
+@${PKG} ${PKG_VERSION} · https://www.npmjs.com/package/${PKG}
+`
+  );
+  writeFileSync(
+    join(dir, "lang/en.json"),
+    JSON.stringify(
+      {
+        posts: "Posts",
+        ui: {
+          title: "Nexa",
+          dashboard: "Dashboard",
+          login: "Login",
+          logout: "Logout",
+          add: "Add",
+          delete: "Delete",
+          empty: "No data",
+          confirm_delete: "Delete?",
+        },
+      },
+      null,
+      2
+    )
+  );
+  writeFileSync(
+    join(dir, "lang/ar.json"),
+    JSON.stringify(
+      {
+        posts: "المنشورات",
+        ui: {
+          title: "Nexa",
+          dashboard: "لوحة التحكم",
+          login: "دخول",
+          logout: "خروج",
+          add: "إضافة",
+          delete: "حذف",
+          empty: "لا يوجد بيانات",
+          confirm_delete: "حذف؟",
+        },
+      },
+      null,
+      2
+    )
+  );
+  const adminSrc = join(frameworkPath, "public/admin.html");
+  if (existsSync(adminSrc)) {
+    cpSync(adminSrc, join(dir, "public/admin.html"));
+  }
+  const indexSrc = join(frameworkPath, "public/index.html");
+  if (existsSync(indexSrc)) {
+    cpSync(indexSrc, join(dir, "public/index.html"));
+  } else {
+    writeFileSync(
+      join(dir, "public/index.html"),
+      `<!DOCTYPE html><meta http-equiv="refresh" content="0;url=/admin"><a href="/admin">Admin</a>`
+    );
+  }
+  console.log(`
+Project ready: ${name}
+
+  cd ${name}
+  npm install
+  npm run serve
+
+  Read README.md for the full quickstart
+  Open http://localhost:3333/admin
+  Login: admin@nexa.dev / 123456
+
+  New table:
+    npx nexa make:resource products
+`);
+} else if (command === "migrate") {
+  await withDb();
+} else if (command === "migrate:rollback") {
+  await loadApp();
+  const { runMigrations, rollbackMigrations } = await import("../packages/core/src/migrate.js");
+  const { loadEnv } = await import("../packages/core/src/config.js");
+  const { dbConnection } = await import("../packages/database/src/database.js");
+  loadEnv();
+  const database = await runMigrations(dbConnection());
+  const n = await rollbackMigrations(database, Number(arg) || 1);
+  console.log(`Rolled back ${n} migration(s)`);
+} else if (command === "db:seed") {
+  const db = await withDb();
+  const { runSeeders } = await import("../packages/core/src/migrate.js");
+  await runSeeders(db);
+  console.log("Seed complete");
+} else if (command === "queue:work") {
+  const database = await withDb();
+  const { setupQueue, processJobs, workQueue, registerBuiltInJobs } = await import(
+    "../packages/queue/src/index.js"
+  );
+  await setupQueue(database);
+  registerBuiltInJobs();
+  // `nexa queue:work` = loop · `nexa queue:work once` or a number = single batch
+  if (arg === "once" || (arg && /^\d+$/.test(arg))) {
+    const n = await processJobs(database, arg === "once" ? 10 : Number(arg));
+    console.log(`Processed ${n} job(s)`);
+  } else {
+    console.log("Queue worker running (Ctrl+C to stop)…");
+    await workQueue(database);
+  }
+} else if (command === "schedule:work") {
+  await loadApp();
+  const { loadEnv } = await import("../packages/core/src/config.js");
+  const { startScheduler } = await import("../packages/schedule/src/index.js");
+  loadEnv();
+  try {
+    await import(new URL(`file:///${cwd}/schedule.ts`).href);
+  } catch {
+    console.log("No schedule.ts");
+  }
+  startScheduler();
+} else if (command === "make:resource" && arg) {
+  const name = arg.toLowerCase().replace(/[^a-z0-9_]/g, "");
+  mkdirSync("resources", { recursive: true });
+  let pkgJson = "";
+  try {
+    pkgJson = readFileSync("package.json", "utf8");
+  } catch {
+    /* no package.json */
+  }
+  const deps = pkgJson ? (JSON.parse(pkgJson).dependencies ?? {}) : {};
+  const pkgName = [PKG, "@nexa-stack/framework", "@nexa/framework", "@nexa/core", "nexa-bun", "nexa"].find((n) => n in deps);
+  const imp = pkgName ? `"${pkgName}"` : `"../packages/core/src/index.js"`;
+  const path = `resources/${name}.ts`;
+  writeFileSync(
+    path,
+    `import { resource, string } from ${imp};
+
+resource("${name}", {
+  name: string().required().label("Name"),
+}, { label: "${name}" }).admin();
+`
+  );
+  console.log(`Created ${path} — auto-loaded by nexa serve (no import needed)`);
+} else if (command === "test") {
+  const r = spawnSync("npx", ["vitest", "run"], { stdio: "inherit", shell: true });
+  process.exit(r.status ?? 1);
+} else {
+  console.log(help);
+}

package/docs/AI.md

@@ -0,0 +1,69 @@
+# AI Instructions — Nexa Framework
+
+> **Read this before generating any code for this project.**
+
+## Context
+
+This project uses **Nexa** — a Node.js ≥ 20 framework (`@nexa-stack/framework`).
+
+NOT Express. NOT NestJS. NOT Laravel.
+
+## No controllers, routes, or page files
+
+| Do NOT generate | Nexa equivalent |
+|-----------------|-----------------|
+| Controller.php | `resource()` in app.ts |
+| routes/web.php | auto `/api/{name}` |
+| models/ | `resource()` fields |
+| add.blade.php | `.admin()` auto UI |
+| Manual i18n everywhere | `{ label: "Clients" }` or `labelKey` |
+
+## Import
+
+```ts
+import {
+  start, resource, string, number, money, email, text, boolean, belongsTo, getDb,
+} from "@nexa-stack/framework";
+```
+
+## Template
+
+```ts
+resource("MODULE", {
+  field: string().required(),
+  price: money().required(),
+  parent: belongsTo("OTHER").required(),
+}, { label: "Label" }).admin().auth();
+
+await start();
+```
+
+## Example modules
+
+| Resource | Label | Auth |
+|----------|-------|------|
+| clients | Clients | no |
+| suppliers | Suppliers | no |
+| products | Products | no |
+| employees | Employees | yes |
+| orders | Orders | yes |
+| invoices | Invoices | yes |
+| payments | Payments | yes |
+
+## Checklist
+
+- [ ] Edit `app.ts` / `resources/*.ts`
+- [ ] Use `resource()` for each module
+- [ ] English labels by default: `{ label: "..." }`
+- [ ] `.admin()` for UI
+- [ ] `.auth()` for protected modules
+- [ ] No manual routes/controllers/pages
+- [ ] Default locale is English (`APP_LOCALE=en`)
+
+## Test
+
+```bash
+npm run serve
+```
+
+http://localhost:3333/admin

package/docs/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# Nexa — Architecture
+
+## What Nexa does NOT have
+
+Nexa is **not** Laravel / Express. There are no:
+
+| Traditional | In Nexa |
+|-------------|---------|
+| Controllers | ❌ — auto-generated from `resource()` |
+| Routes file | ❌ — auto: `/api/{name}` |
+| Models | ❌ — `resource()` defines the table |
+| Migrations | ❌ — tables created on `start()` |
+| Add/Edit pages | ❌ — `.admin()` generates UI |
+| Language files (lang/) | ❌ — labels inline in `resource()` |
+
+---
+
+## What Nexa HAS
+
+```
+app.ts          → your entire backend (resources + start)
+packages/       → the framework engine
+public/         → custom HTML pages (optional)
+docs/           → documentation
+```
+
+---
+
+## How to add a module
+
+**One line in `app.ts`:**
+
+```ts
+resource("clients", {
+  name: string().required(),
+  phone: string().required(),
+}, { label: "Clients" }).admin();
+```
+
+This gives you:
+- Database table `clients`
+- API: GET/POST/PUT/DELETE `/api/clients`
+- Admin page with add form + list
+- Validation
+
+**No controller. No route. No add page file.**
+
+---
+
+## How to add a custom page
+
+Only when `.admin()` is not enough (e.g. cashier POS):
+
+```
+public/my-page.html  →  http://localhost:3333/my-page
+```
+
+The page uses `fetch()` to call Nexa API.
+
+---
+
+## Flow
+
+```
+app.ts
+  resource("clients", {...}).admin()
+       ↓
+  start()
+       ↓
+  ┌─────────────┬──────────────┬─────────────┐
+  │  SQLite DB  │  REST API    │  Admin UI   │
+  │  clients    │  /api/clients│  /admin     │
+  └─────────────┴──────────────┴─────────────┘
+```