🚀 Nucleus Framework

Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs

Overview

Nucleus Framework is a batteries-included backend framework built on top of Elysia.js and Drizzle ORM. It provides everything you need to build secure, scalable, multi-tenant APIs with minimal boilerplate.

Tech Stack

| Category | Technology | |----------|------------| | Runtime | Bun | | Framework | Elysia.js | | ORM | Drizzle ORM | | Database | PostgreSQL | | Cache | Redis | | Messaging | Dapr | | Language | TypeScript | | Linter | Biome |

Installation

bun add nucleus-core-ts

Quick Start

import { NucleusElysiaPlugin } from "nucleus-core-ts";
import { Elysia } from "elysia";

const app = new Elysia()
  .use(NucleusElysiaPlugin({
    database: {
      host: process.env.DB_HOST,
      port: 5432,
      database: process.env.DB_NAME,
      user: process.env.DB_USER,
      password: process.env.DB_PASSWORD,
    },
    redis: {
      host: process.env.REDIS_HOST,
      port: 6379,
    },
    jwt: {
      secret: process.env.JWT_SECRET,
      accessTokenExpiry: "15m",
      refreshTokenExpiry: "7d",
    },
  }))
  .listen(3000);

console.log("🚀 Server running on http://localhost:3000");

Features

🔐 Authentication & Authorization

• JWT Access & Refresh Tokens - Secure token-based authentication
• Session Cookies - HttpOnly secure session management
• Device Fingerprinting - Track and manage user devices
• Proactive Token Refresh - WebSocket-based token refresh
• Role-Based Access Control - Granular claim-based permissions
• Automatic Claim Generation - Auto-generate claims from database tables

🗄️ Database & ORM

• Drizzle ORM Integration - Type-safe database operations
• Auto Migrations - Automatic schema migrations
• Multi-tenant Support - Built-in tenant isolation
• Generic CRUD Routes - Auto-generated REST endpoints
• Relational Operations - Deep nested relations support
• Bulk Operations - Batch create, update, delete

🔍 Query Capabilities

• Advanced Filtering - Complex where clauses
• Sorting - Multi-column sorting
• Pagination - Cursor and offset pagination
• Search - Full-text search support
• Field Selection - GraphQL-like field selection

📁 File Management

• File Upload - Multipart file uploads
• Local CDN - Serve static files
• Streaming - Large file streaming support

📊 Monitoring & Logging

• Smart Logger - Structured logging with levels
• Server Monitoring - CPU, memory, request metrics
• Rate Limiting - Configurable rate limits
• Alerting - Threshold-based alerts

📧 Notifications

• Email Integration - Gmail API integration
• Platform Notifications - In-app notifications
• Triggers - Event-based notifications

📚 Documentation

• Auto Swagger - Auto-generated OpenAPI docs
• Type-safe Client - Generated TypeScript client

Subpath Exports

// Main framework
import { NucleusElysiaPlugin } from "nucleus-core-ts";

// Client utilities (for frontend)
import { createApiHook } from "nucleus-core-ts/client";

// Frontend components
import { ... } from "nucleus-core-ts/fe";

// Proxy utilities
import { ... } from "nucleus-core-ts/proxy";

Configuration

Create a config.nucleus.json in your project root:

{
  "$schema": "node_modules/nucleus-core-ts/schemas/config.nucleus.json",
  "appId": "my-app",
  "mode": "development",
  
  "database": {
    "url": "DATABASE_URL",
    "type": "postgres",
    "isMultiTenant": false,
    "schemas": ["main"]
  },
  
  "redis": {
    "url": "REDIS_URL"
  },
  
  "authentication": {
    "enabled": true,
    "accessToken": {
      "secret": "JWT_SECRET",
      "expiresIn": "15m",
      "algorithm": "HS256"
    },
    "refreshToken": {
      "secret": "JWT_REFRESH_SECRET",
      "expiresIn": "7d"
    },
    "login": { "enabled": true },
    "register": { "enabled": true },
    "logout": { "enabled": true },
    "sessions": {
      "enabled": true,
      "maxActiveSessions": 5,
      "allowMultipleDevices": true
    }
  },
  
  "authorization": {
    "enabled": true,
    "autoSeedClaims": true,
    "godminEmail": "[email protected]"
  },
  
  "rateLimit": {
    "enabled": true,
    "strategy": "sliding-window",
    "authRoutes": {
      "login": { "window": "1m", "max": 5 },
      "register": { "window": "1h", "max": 10 }
    }
  },
  
  "monitoring": {
    "enabled": true,
    "system": {
      "enabled": true,
      "collectInterval": "30s",
      "metrics": { "cpu": true, "memory": true, "disk": true }
    },
    "alerts": {
      "enabled": true,
      "thresholds": {
        "cpuPercent": 80,
        "memoryPercent": 85
      }
    }
  },
  
  "storage": {
    "enabled": true,
    "basePath": "./uploads",
    "maxFileSizeBytes": 10485760,
    "cdn": { "enabled": true }
  },
  
  "entities": []
}

Config Options

| Section | Description | |---------|-------------| | database | PostgreSQL connection, multi-tenant support | | redis | Redis connection, Dapr integration | | authentication | JWT tokens, sessions, login/register/logout routes | | authorization | Role-based access, auto claim generation | | rateLimit | Request throttling per route/user/IP | | monitoring | System metrics, alerts, streaming endpoints | | storage | File uploads, CDN serving | | notification | Email & platform notifications | | verification | Approval workflows with signatures | | audit | Action logging per operation type |

License

This is proprietary software. See LICENSE for details.

Author

Hidayet Can Özcan
📧 [email protected]