@njinlabs/njin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PT Njin Daya Teknologi
+
+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,223 @@
+# njin
+
+A modern framework for building company profiles, landing pages, and content-driven websites. Define your data model once — get a full REST API, admin panel schema, and server-rendered website out of the box.
+
+## Stack
+
+- **[Bun](https://bun.sh)** — runtime, package manager, bundler (njin is Bun-only — no Node/Deno support)
+- **[Elysia](https://elysiajs.com)** — HTTP framework with type-safe CRUD generation
+- **[SurrealDB](https://surrealdb.com)** — embedded multi-model database (no separate server)
+- **[EdgeJS](https://edgejs.dev)** — server-side template engine with file-based routing
+- **[Vite](https://vitejs.dev)** + **[Tailwind CSS v4](https://tailwindcss.com)** + **[Alpine.js](https://alpinejs.dev)** — frontend tooling
+
+## Quick start
+
+```bash
+bun create njin-app my-web
+cd my-web
+bunx njin dev
+```
+
+## Project structure
+
+```
+config.ts           ← registers models, db, file adapter, etc. (see below)
+src/
+  models/            ← your data models
+  views/
+    layouts/         ← base layout templates
+    pages/           ← file-based routes (.edge files)
+    components/      ← reusable .edge components
+  client/
+    main.ts          ← frontend entry point
+    app.css          ← Tailwind CSS
+_admin/              ← optional — drop a built admin panel SPA here (not bundled with njin)
+vite.config.ts       ← Vite config
+```
+
+`@njinlabs/njin` itself lives in `node_modules/@njinlabs/njin` — there's no framework source to look at or modify inside your project.
+
+## Defining a model
+
+```ts
+// src/models/post.ts
+import { makeModel, text, date, select } from "@njinlabs/njin";
+import z from "zod";
+
+const post = makeModel("post", {
+  name: "Post",
+  searchFields: ["title"],
+  schema: z.object({
+    title:     text({ label: "Title" }),
+    body:      text({ label: "Body" }),
+    status:    select({ label: "Status" }, ["DRAFT", "PUBLISH"]),
+    publishedAt: date({ label: "Published At" }),
+  }),
+});
+
+export default post;
+```
+
+Register it in `config.ts` at the project root:
+
+```ts
+// config.ts
+import { defineConfig } from "@njinlabs/njin/config";
+
+export default defineConfig({
+  models: [
+    () => import("./src/models/post"),
+  ],
+});
+```
+
+This automatically generates:
+
+| Method | Endpoint | Description |
+|--------|----------|--------------|
+| `GET` | `/api/post` | List with pagination, search, filter, sort |
+| `POST` | `/api/post` | Create |
+| `GET` | `/api/post/:id` | Show (with relations fetched) |
+| `PUT` | `/api/post/:id` | Update |
+| `DELETE` | `/api/post/:id` | Delete |
+| `GET` | `/api/schema` | Full schema for admin panel |
+
+## File-based routing
+
+Files in `src/views/pages/` map to routes automatically:
+
+```
+pages/index.edge          → GET /
+pages/about.edge          → GET /about
+pages/blog/index.edge     → GET /blog
+pages/blog/[slug].edge    → GET /blog/:slug
+```
+
+## Template example
+
+Models are available as global async functions in every template:
+
+```edge
+@component('layouts/main')
+  @slot('title') Blog @end
+
+  @slot('main')
+    @let(result = await post.read({ filters: { status: 'PUBLISH' }, limit: 10 }))
+
+    @each(item in result.data)
+      <article>
+        <h2>{{ item.title }}</h2>
+        <time>{{ item.publishedAt }}</time>
+      </article>
+    @end
+  @end
+@end
+```
+
+Available template context:
+
+```edge
+{{ params.slug }}       {{-- URL params --}}
+{{ query.page }}        {{-- Query string --}}
+{{ request.path }}      {{-- Current path, e.g. /blog --}}
+{{ request.url }}       {{-- Full URL --}}
+```
+
+## API query parameters
+
+```
+GET /api/post?page=1&limit=10&sort=publishedAt&order=desc
+GET /api/post?search=hello
+GET /api/post?filters[status][$eq]=PUBLISH
+GET /api/post?filters[title][$contains]=hello
+GET /api/post?populate=author,thumbnail
+GET /api/post?populate=none
+```
+
+## Setup (first run)
+
+On first startup, create the admin user:
+
+```bash
+# Check if setup is needed
+GET /api/setup/status
+
+# Create first admin user
+POST /api/setup
+{ "name": "Admin", "email": "admin@example.com", "password": "yourpassword" }
+# Returns: { data: { token, user } }
+```
+
+After the first user is created, this endpoint is permanently disabled.
+
+## Auth
+
+```bash
+POST   /api/auth/login         # { email, password } → { data: { token, user } }
+GET    /api/auth/check-token   # Bearer <token> → { data: user }
+DELETE /api/auth/logout        # Bearer <token>
+```
+
+All `/api/*` endpoints require `Authorization: Bearer <token>`.
+
+## Admin panel
+
+njin doesn't bundle an admin panel — `_admin/` at your project root is just a static folder the server looks for at startup (`GET /_admin`). Drop a built admin SPA's `index.html`/assets into it (your own, or one shared by the community) and it's served automatically; if it's missing, the startup banner just notes it wasn't found.
+
+## Configuration
+
+Everything that used to be an environment variable now lives in a `config.ts` you write at the project root — njin no longer owns `.env` parsing, so reading from `process.env` (or not) is entirely your call:
+
+```ts
+// config.ts
+import { defineConfig } from "@njinlabs/njin/config";
+import bunFilesystemAdapter from "@njinlabs/njin/adapters/bun_filesystem";
+
+export default defineConfig({
+  port: Number(process.env.PORT ?? 3000),
+  db: {
+    path: process.env.DB_PATH ?? "rocksdb://data",
+    namespace: process.env.DB_NAMESPACE ?? "general",
+    database: process.env.DB_DATABASE ?? "general",
+  },
+  img: {
+    hosts: ["cdn.example.com"], // external hosts allowed for GET /img besides same-origin/localhost
+  },
+  adapters: {
+    file: bunFilesystemAdapter({ dir: "./uploads" }), // default — omit entirely to use this with its own default ("./uploads")
+  },
+  models: [
+    () => import("./src/models/post"),
+  ],
+});
+```
+
+To store uploads in S3 (or an S3-compatible service like R2/Spaces/MinIO) instead:
+
+```ts
+import s3Adapter from "@njinlabs/njin/adapters/s3";
+
+adapters: {
+  file: s3Adapter({
+    bucket: process.env.S3_BUCKET!,
+    region: process.env.S3_REGION,
+    accessKeyId: process.env.S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+    endpoint: process.env.S3_ENDPOINT, // for R2/Spaces/MinIO
+  }),
+}
+```
+
+## Commands
+
+```bash
+bunx njin dev       # Start dev server (Elysia + Vite HMR)
+bunx njin build     # Build for production -> ./out (public/, _admin/, views/, compiled server)
+bunx njin start     # Run from source in production mode (no compile)
+```
+
+Wire these as `package.json` scripts (`"dev": "njin dev"`, etc.) if you'd rather run `bun run dev`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@njinlabs/njin",
+  "version": "0.1.0",
+  "description": "A modern framework for building company profiles, landing pages, and content-driven websites.",
+  "type": "module",
+  "keywords": ["bun", "elysia", "surrealdb", "edgejs", "cms", "framework"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/njinlabs/njin.git"
+  },
+  "homepage": "https://github.com/njinlabs/njin",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": ["src", "LICENSE"],
+  "scripts": {
+    "test": "bun test"
+  },
+  "bin": {
+    "njin": "./src/cli/index.ts"
+  },
+  "exports": {
+    ".": "./src/core/model/index.ts",
+    "./config": "./src/core/config.ts",
+    "./boot": "./src/core/boot.ts",
+    "./banner": "./src/core/banner.ts",
+    "./adapters/*": "./src/core/adapters/*.ts"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.0",
+    "@types/alpinejs": "^3.13.11",
+    "@types/bun": "latest",
+    "@types/geoip-lite": "^1.4.4",
+    "alpinejs": "^3.15.12",
+    "pino-pretty": "^13.1.3",
+    "vite": "^8.0.14",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "alpinejs": "^3.0.0",
+    "typescript": "^5",
+    "vite": "^8.0.0",
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "@elysia/bearer": "^1.4.4",
+    "@elysia/cors": "^1.4.2",
+    "@paralleldrive/cuid2": "^3.3.0",
+    "@surrealdb/node": "^3.0.3",
+    "edge.js": "^6.5.1",
+    "elysia": "^1.4.28",
+    "geoip-lite": "^2.0.3",
+    "moment": "^2.30.1",
+    "pino": "^10.3.1",
+    "surrealdb": "^2.0.3"
+  }
+}

package/src/cli/build.ts

@@ -0,0 +1,162 @@
+import type { BunPlugin } from "bun";
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = process.cwd();
+const outDir = join(root, "out");
+
+console.log("Building for production...\n");
+
+await rm(outDir, { recursive: true, force: true });
+await mkdir(outDir, { recursive: true });
+
+// Vite build — outDir is forced here regardless of what the project's own
+// vite.config.ts says, so `njin build` always lands in a predictable place.
+const { build } = await import("vite");
+await build({
+  configFile: join(root, "vite.config.ts"),
+  build: { outDir: join(outDir, "public"), emptyOutDir: true },
+});
+console.log("✓ Built client assets -> out/public");
+
+// view.ts resolves views from process.cwd()/src/views at runtime, so the build
+// output preserves that same relative layout instead of flattening it.
+const viewsDir = join(root, "src/views");
+if (existsSync(viewsDir)) {
+  await cp(viewsDir, join(outDir, "src/views"), { recursive: true });
+  console.log("✓ Copied views -> out/src/views");
+} else {
+  console.log("• No src/views found — skipped");
+}
+
+const adminDir = join(root, "_admin");
+if (existsSync(adminDir)) {
+  await cp(adminDir, join(outDir, "_admin"), { recursive: true });
+  console.log("✓ Copied admin panel -> out/_admin");
+} else {
+  console.log("• No _admin found — skipped");
+}
+
+// surreal.ts statically imports @surrealdb/node unconditionally, and module.ts always wires
+// up the surreal module, so every compiled binary needs this native binding to boot — even
+// for projects using a remote SurrealDB instance. Its loader resolves the platform .node file
+// via `const require = createRequire(import.meta.url); require("./surrealdb-node.<platform>.node")`
+// — using a local `require` value rather than the literal CJS keyword means Bun's bundler never
+// statically recognizes that call as an import to resolve/embed, so it survives bundling
+// untouched and then fails at runtime in a compiled binary (no real filesystem path next to
+// `import.meta.url` to load it from). So instead of embedding it, the matching platform binary
+// is copied next to the executable as a plain file, and a build plugin patches the loader's
+// source to read from there (via `process.execPath`'s directory) at runtime.
+const NATIVE_FILE: Record<string, string> = {
+  "win32-x64": "surrealdb-node.win32-x64-msvc.node",
+  "win32-arm64": "surrealdb-node.win32-arm64-msvc.node",
+  "darwin-x64": "surrealdb-node.darwin-x64.node",
+  "darwin-arm64": "surrealdb-node.darwin-arm64.node",
+  // musl isn't detected here (njin build doesn't cross-compile); glibc is assumed on Linux.
+  "linux-x64": "surrealdb-node.linux-x64-gnu.node",
+  "linux-arm64": "surrealdb-node.linux-arm64-gnu.node",
+};
+const nativeFile = NATIVE_FILE[`${process.platform}-${process.arch}`];
+if (!nativeFile) {
+  console.error(`\n✗ Unsupported platform for @surrealdb/node: ${process.platform}-${process.arch}`);
+  process.exit(1);
+}
+
+const surrealNodeDistDir = dirname(fileURLToPath(import.meta.resolve("@surrealdb/node")));
+const bindingsDir = join(outDir, "bindings");
+await mkdir(bindingsDir, { recursive: true });
+await cp(join(surrealNodeDistDir, nativeFile), join(bindingsDir, nativeFile));
+console.log(`✓ Copied native binding -> out/bindings/${nativeFile}`);
+
+const surrealNativePlugin: BunPlugin = {
+  name: "surrealdb-native-binding",
+  setup(build) {
+    build.onLoad({ filter: /surrealdb-node\.mjs$/ }, async (args) => {
+      const original = await Bun.file(args.path).text();
+      const marker = "const require = createRequire(import.meta.url);";
+      if (!original.includes(marker)) {
+        throw new Error("@surrealdb/node's loader shape changed — expected createRequire marker not found");
+      }
+      // Wrap `require` so the host platform's own .node lookup is redirected to the copy in
+      // out/bindings/; every other platform's file and the optional sibling npm packages fall
+      // through to the real require() and fail exactly as they would unpatched (still recorded
+      // in the loader's own loadErrors, so a genuinely missing binding still throws clearly).
+      const patched = original.replace(
+        marker,
+        `const __realRequire = createRequire(import.meta.url);
+const require = (specifier) => {
+  if (specifier === ${JSON.stringify(`./${nativeFile}`)}) {
+    const path = __realRequire("node:path");
+    return __realRequire(path.join(path.dirname(process.execPath), "bindings", ${JSON.stringify(nativeFile)}));
+  }
+  return __realRequire(specifier);
+};`,
+      );
+      return { contents: patched, loader: "js" };
+    });
+  },
+};
+
+// Generated build entry — a static, literal import of the project's config.ts so
+// `bun build --compile` can trace and embed it (and the model files it dynamically
+// imports) straight into the binary. loadConfig()'s normal dynamic-file-read path
+// only works when running from source (`njin dev`/`njin start`), not from a
+// standalone compiled executable with no source files alongside it.
+//
+// boot/banner are imported dynamically, AFTER loadConfig(config) — static imports are
+// hoisted and evaluated before this file's own body runs, so a static `import { boot }`
+// would pull in config/module.ts (and every module's init(), which read getConfig()) before
+// loadConfig(config) below ever executes. Same reasoning as dev.ts/start.ts.
+const entryPath = join(root, ".njin-build-entry.ts");
+const configPath = join(root, "config.ts").replace(/\\/g, "/");
+
+try {
+  await Bun.write(
+    entryPath,
+    `import config from ${JSON.stringify(configPath)};
+import { loadConfig } from "@njinlabs/njin/config";
+
+await loadConfig(config);
+
+const { boot } = await import("@njinlabs/njin/boot");
+const { printBanner } = await import("@njinlabs/njin/banner");
+
+await boot();
+printBanner({ mode: "production" });
+`,
+  );
+
+  const exeName = process.platform === "win32" ? "server.exe" : "server";
+
+  const result = await Bun.build({
+    entrypoints: [entryPath],
+    compile: { outfile: join(outDir, exeName) },
+    // vite is dev-only (view.ts gates it behind `if (isDev)`, dead in production) — bundling
+    // it would also drag in its own internal (not-installed) lazy `import("esbuild")`.
+    external: ["vite"],
+    plugins: [surrealNativePlugin],
+    // The CLI's `bun build --compile` implicitly inlines process.env.NODE_ENV as "production";
+    // the Bun.build() JS API doesn't, so view.ts's top-level `isDev` check would otherwise read
+    // undefined and take the dev branch (importing the externalized, not-on-disk `vite`).
+    define: {
+      "process.env.NODE_ENV": JSON.stringify("production"),
+    },
+  });
+
+  if (!result.success) {
+    console.error("\n✗ Build failed");
+    for (const message of result.logs) console.error(message);
+    process.exit(1);
+  }
+
+  console.log(`\n✓ Compiled server -> out/${exeName}`);
+  console.log(
+    "\nNote: out/bindings/ must ship alongside the executable — it holds the native SurrealDB " +
+      "binding loaded at runtime.",
+  );
+  console.log(`\nRun it with:\n  cd out && ./${exeName}`);
+} finally {
+  await rm(entryPath, { force: true });
+}

package/src/cli/dev.ts

@@ -0,0 +1,11 @@
+// Static imports are hoisted and evaluated before this file's own body runs, so setting
+// NODE_ENV here would be too late if "../core/boot" were a static import — view.ts
+// (reached transitively) reads NODE_ENV at module-load time. Dynamic imports execute in
+// normal program order, so they run after the line below.
+process.env.NODE_ENV ??= "development";
+
+const { boot } = await import("../core/boot");
+const { printBanner } = await import("../core/banner");
+
+await boot();
+printBanner({ mode: "development" });

package/src/cli/index.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+const [command] = process.argv.slice(2);
+
+switch (command) {
+  case "dev":
+    await import("./dev");
+    break;
+  case "start":
+    await import("./start");
+    break;
+  case "build":
+    await import("./build");
+    break;
+  default:
+    console.log(`Usage: njin <dev|build|start>
+
+  dev    Run the dev server (Vite HMR + live reload)
+  build  Build for production -> ./out (public/, _admin/, views/, server)
+  start  Run from source in production mode (no compile)`);
+    process.exit(command ? 1 : 0);
+}

package/src/cli/start.ts

@@ -0,0 +1,9 @@
+// See dev.ts for why these are dynamic imports — NODE_ENV must be set before
+// view.ts (reached transitively) evaluates, and static imports would run first.
+process.env.NODE_ENV = "production";
+
+const { boot } = await import("../core/boot");
+const { printBanner } = await import("../core/banner");
+
+await boot();
+printBanner({ mode: "production" });

package/src/config/module.ts

@@ -0,0 +1,34 @@
+import { loadConfig } from "../core/config";
+import admin from "../modules/admin";
+import analytics from "../modules/analytics";
+import api from "../modules/api";
+import auth from "../modules/auth";
+import elysia from "../modules/elysia";
+import file from "../modules/file";
+import img from "../modules/img";
+import logger from "../modules/logger";
+import setup from "../modules/setup";
+import surreal from "../modules/surreal";
+import users from "../modules/users";
+import view from "../modules/view";
+
+// Must resolve before anything below reads getConfig() — db path, port, file
+// adapter, and the model registry all come from the consuming project's config.ts.
+await loadConfig();
+
+const modules = [
+  logger.init(),
+  surreal.init(),
+  elysia.init(),
+  await file.init(),
+  await auth.init(),
+  await setup.init(),
+  await api.init(),
+  await img.init(),
+  await analytics.init(),
+  await users.init(),
+  await admin.init(),
+  await view.init(),
+] as const;
+
+export default modules;

package/src/core/adapters/bun_filesystem.ts

@@ -0,0 +1,37 @@
+import type { FileAdapter } from "../../modules/file";
+import { init } from "@paralleldrive/cuid2";
+import { join } from "node:path";
+import z from "zod";
+
+const createId = init({
+  random: Math.random,
+  length: 10,
+  fingerprint: "file",
+});
+
+const meta = z.null();
+
+const bunFilesystemAdapter = ({ dir = "./uploads" }: { dir?: string } = {}): FileAdapter<typeof meta> => {
+  return {
+    meta,
+    dir,
+    write: async (file) => {
+      const [fileName, ...exts] = file.name.split(".");
+
+      const name = `${fileName}_${createId()}.${exts.join(".")}`;
+
+      await Bun.write(join(dir, name), await file.arrayBuffer());
+
+      return {
+        meta: null,
+        name,
+        size: file.size,
+        type: file.type,
+        url: `/uploads/${name}`,
+      };
+    },
+    unlink: (file) => Bun.file(join(dir, file.name)).delete(),
+  };
+};
+
+export default bunFilesystemAdapter;

package/src/core/adapters/s3.ts

@@ -0,0 +1,60 @@
+import type { FileAdapter } from "../../modules/file";
+import { init } from "@paralleldrive/cuid2";
+import type { S3Options } from "bun";
+import z from "zod";
+
+const createId = init({
+  random: Math.random,
+  length: 10,
+  fingerprint: "file",
+});
+
+const meta = z.null();
+
+type ResolveUrlOptions = {
+  publicUrl?: string;
+  endpoint?: string;
+  bucket?: string;
+  region?: string;
+};
+
+// Path-style works for AWS S3 and S3-compatible services alike (R2, Spaces, MinIO).
+// No process.env fallback here on purpose — the consuming project's config.ts is the
+// single place that decides whether a value comes from an env var or is hardcoded.
+export const resolveUrl = (key: string, options: ResolveUrlOptions = {}): string => {
+  if (options.publicUrl) return `${options.publicUrl.replace(/\/$/, "")}/${key}`;
+
+  if (options.endpoint) return `${options.endpoint.replace(/\/$/, "")}/${options.bucket}/${key}`;
+
+  const region = options.region ?? "us-east-1";
+  return `https://${options.bucket}.s3.${region}.amazonaws.com/${key}`;
+};
+
+// `bucket` is required (unlike Bun.S3Client itself, which would otherwise fall back to
+// S3_BUCKET/AWS_BUCKET env vars) — resolveUrl() needs to know it regardless, and reading
+// it here directly would bypass the project's own config.ts as the single source of truth.
+const s3Adapter = (options: S3Options & { bucket: string; publicUrl?: string }): FileAdapter<typeof meta> => {
+  const { publicUrl, ...s3Options } = options;
+  const bucket = new Bun.S3Client(s3Options);
+
+  return {
+    meta,
+    write: async (file) => {
+      const [fileName, ...exts] = file.name.split(".");
+      const key = `${fileName}_${createId()}.${exts.join(".")}`;
+
+      await bucket.write(key, file, { acl: "public-read", type: file.type });
+
+      return {
+        meta: null,
+        name: key,
+        size: file.size,
+        type: file.type,
+        url: resolveUrl(key, { publicUrl, endpoint: s3Options.endpoint, bucket: s3Options.bucket, region: s3Options.region }),
+      };
+    },
+    unlink: (file) => bucket.delete(file.name),
+  };
+};
+
+export default s3Adapter;