Nexus Core Framework 🚀

@praveenkumar-s/nexus-core

Nexus Core is an opinionated, zero-boilerplate backend framework for MERN Stack + Prisma applications. It abstracts away Controllers, Services, and Routes, allowing you to build production-ready CRUD APIs with Authentication, File Uploads, and Role-Based Access Control (RBAC) in minutes.

✨ Features

• Zero Boilerplate: No more writing repetitive Controllers, Services, or Routes.
• Auto-CRUD: Instantly generates GET, POST, PUT, DELETE endpoints for any Prisma model.
• Built-in Auth: JWT Authentication (Login, Register, Me) out of the box.
• RBAC (Role-Based Access Control): Granular permission control (e.g., "Only Managers can Create").
• File Uploads: Automatic FormData handling, local storage, and type sanitization.
• Modular Architecture: Keep your logic clean with resource-based configuration.
• Type-Safe: Built with TypeScript.

📦 Installation

# 1. Install the framework
npm install @praveenkumar-s/nexus-core

# 2. Install required peer dependencies
npm install prisma @prisma/client express cors bcryptjs jsonwebtoken multer uuid
npm install -D typescript ts-node @types/node @types/express @types/cors

⚡️ Quick Start

1. Setup Database (prisma/schema.prisma) You must have a User model for authentication to work.

    datasource db {
    provider = "mongodb"
    url      = env("DATABASE_URL")
}

    generator client {
    provider = "prisma-client-js"
}

// REQUIRED: User model for Auth
model User {
    id       String @id @default(auto()) @map("_id") @db.ObjectId
    email    String @unique
    password String
    role     String @default("user") // admin, manager, user
}

// YOUR DATA: Example Resource
model Project {
    model Project {
  id          String   @id @default(auto()) @map("_id") @db.ObjectId
  name        String
  budget      Int
  proposalUrl String[]
  isActive    Boolean  @default(true)
}
}

2. Create the Server (src/server.ts)

import { PrismaClient } from '@prisma/client';
import { NexusApp } from '@praveenkumar-s/nexus-core';

const prisma = new PrismaClient();

const app = new NexusApp({
prisma: prisma,
jwtSecret: process.env.JWT_SECRET || "super-secret-key",
port: 4000,

// Auth Settings
auth: {
    registrationStrategy: 'open', // 'open' or 'admin_only'
},

// Resource Definitions
resources: {
    Project: {
    publicMethods: ['GET'], // GET is open to everyone
    enableUpload: true,     // Enable file uploads
    uploadField: 'proposalUrl', // Database field to store file path
    
    // Role-Based Access Control
    methodRoles: {
        POST: ['admin', 'manager'], // Only Admin/Manager can Create
        DELETE: ['admin']           // Only Admin can Delete
    }
    }
}
});

app.start();

Run it: npx nodemon src/server.ts

📖 Advanced Usage

1. Modular Resources (Best Practice) For larger apps, define resources in separate files.

src/resources/TicketResource.ts

import { ResourceDefinition } from '@praveenkumar-s/nexus-core';
import { Router, Request, Response } from 'express';

export const TicketResource: ResourceDefinition = {
  methodRoles: {
    POST: ['user', 'admin'], // Users can create tickets
    DELETE: ['admin']        // Only admin can delete
  },
  
  // Add Custom Endpoints
  extend: (router: Router, model: any) => {
    router.get('/stats/count', async (req: Request, res: Response) => {
      const count = await model.count();
      res.json({ success: true, count });
    });
  }
};

src/server.ts

import { TicketResource } from './resources/TicketResource';

const app = new NexusApp({
  // ...
  resources: {
    Ticket: TicketResource
  }
});

2. Handling File Uploads (Frontend) When enableUpload: true is set, the backend expects multipart/form-data.

React Example:

const handleCreate = async () => {
  const formData = new FormData();
  formData.append('name', 'New Project');
  formData.append('budget', 5000); 
  // Nexus Core automatically converts "5000" (string) -> 5000 (int)
  
  formData.append('file', fileInput.files[0]); // Key must be 'file'

  await fetch('http://localhost:4000/api/projects', {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` }, // Do NOT set Content-Type
    body: formData
  });
};

🔌 API Reference

Once you register a resource (e.g., Project), these endpoints are auto-generated:

| Method | Endpoint | Access Control | Description | | :--- | :--- | :--- | :--- | | GET | /api/projects | Configurable | Get all projects | | GET | /api/projects/:id | Configurable | Get one project | | POST | /api/projects | Configurable | Create project (supports Upload) | | PUT | /api/projects/:id | Configurable | Update project | | DELETE | /api/projects/:id | Configurable | Delete project |

Auth Endpoints

| Method | Endpoint | Description | | :--- | :--- | :--- | | POST | /api/auth/register | Register (Email, Password, Role) | | POST | /api/auth/login | Login (Returns Token + User) | | GET | /api/auth/me | Get Current User Profile |

⚛️ React Context Adapter

Copy this file into your frontend to instantly connect with Nexus Core.

src/context/NexusAuthContext.tsx

import React, { createContext, useContext, useState, useEffect } from 'react';

const AuthContext = createContext<any>(null);

export const NexusAuthProvider = ({ children, apiUrl }: any) => {
  const [user, setUser] = useState(null);
  const [token, setToken] = useState(localStorage.getItem('token'));

  const login = async (email: string, pass: string) => {
    const res = await fetch(`${apiUrl}/api/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password: pass }),
    });
    const json = await res.json();
    if (json.success) {
      localStorage.setItem('token', json.data.token);
      setToken(json.data.token);
      setUser(json.data.user);
    } else {
      throw new Error(json.message);
    }
  };

  const logout = () => {
    localStorage.removeItem('token');
    setToken(null);
    setUser(null);
  };

  return (
    <AuthContext.Provider value={{ user, token, login, logout }}>
      {children}
    </AuthContext.Provider>
  );
};

export const useNexusAuth = () => useContext(AuthContext);

📄 License

Copyright © 2025 Praveenkumar S.

This project is licensed under the MIT License. You are free to use, modify, and distribute this software for any purpose, including commercial applications.

See the LICENSE file for more details.

👨‍💻 Developer & Maintainer

Nexus Core is built and maintained by Praveen Kumar.

I created this framework to solve the frustration of writing repetitive boilerplate code for every new MERN project. My goal is to help developers go from "Idea" to "Deployment" in minutes, not days.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

⭐️ Show your support

Give a ⭐️ if this project helped you!