mern-template-tool 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# mern-template-tool
+
+> An exam-oriented, offline-first MERN stack project generator for college practical examinations and fast prototyping.
+
+Execute anywhere with:
+```bash
+npx mern-template-tool <project-name>
+```
+
+---
+
+## ⚡ What is `mern-template`?
+
+During practical examinations, internet access is often limited to a brief window. `mern-template` provides a complete, robust, ready-to-run MERN stack boilerplate with all standard requirements pre-implemented:
+
+- 🔒 **Dual Authentication**: JWT Authentication for React SPA & `express-session` for EJS Admin Portal.
+- 👥 **Role-Based Authorization**: Student & Admin roles with protected routes and ownership checking.
+- 📦 **Generic CRUD Model**: Complete MVC structure with search, filtering, and sorting (`req.query`).
+- 🛡️ **Validation & Security**: `express-validator` rules, `bcryptjs` password hashing, safe JSON responses.
+- 📎 **Multer File Handling**: Local disk storage, file validation, and file download endpoints.
+- ⚛️ **Modern React Frontend**: React 18, Vite, React Router 6, React Context API state, native `fetch` service.
+- 🔌 **Zero External Cloud Dependencies**: Local MongoDB & local filesystem storage, ready for air-gapped exam environments.
+
+---
+
+## 🚀 Quick Usage
+
+```bash
+# 1. Generate project
+npx mern-template my-exam-project
+
+# 2. Start Backend Server
+cd my-exam-project/server
+cp .env.example .env
+npm install
+npm run dev
+
+# 3. Start Frontend Client (in a second terminal)
+cd ../client
+npm install
+npm run dev
+```
+
+---
+
+## 📋 Generated Project Structure
+
+```text
+my-exam-project/
+├── client/                     # React Single Page Application (Vite)
+│   ├── src/
+│   │   ├── components/         # Navbar, Loading
+│   │   ├── context/            # AuthContext (React Context API)
+│   │   ├── pages/              # Login, Register, Dashboard, Profile, Resources, etc.
+│   │   ├── routes/             # ProtectedRoute
+│   │   ├── services/           # api.js (native fetch helper)
+│   │   ├── App.jsx             # Router definition
+│   │   ├── index.css           # Modern dark UI theme
+│   │   └── main.jsx            # Entry point
+│   ├── package.json
+│   └── vite.config.js
+│
+├── server/                     # Express API & EJS Admin Portal
+│   ├── config/                 # db.js (Mongoose connection)
+│   ├── controllers/            # authController.js, resourceController.js
+│   ├── middleware/             # authMiddleware, adminMiddleware, uploadMiddleware, validateMiddleware, errorMiddleware, sessionAuthMiddleware
+│   ├── models/                 # User.js, Resource.js
+│   ├── routes/                 # authRoutes.js, resourceRoutes.js, adminRoutes.js
+│   ├── utils/                  # jwt.js
+│   ├── views/                  # EJS admin templates (login.ejs, dashboard.ejs, partials/)
+│   ├── uploads/                # Local Multer upload storage
+│   ├── .env.example            # Environment variables
+│   ├── package.json
+│   └── server.js               # Express application entrypoint
+│
+└── README.md                   # Includes exam cheat sheet & modification guides
+```
+
+---
+
+## 📦 Publishing to npm
+
+To publish this package to npm:
+```bash
+npm login
+npm pack --dry-run
+npm publish --access public
+```
+
+---
+
+## 📄 License
+MIT

package/bin/index.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+function printUsage() {
+  console.log(`
+\x1b[36m\x1b[1mMERN Template Generator\x1b[0m (Exam-Ready & Offline First)
+
+Usage:
+  npx mern-template-tool <project-name>
+
+Examples:
+  npx mern-template-tool my-app
+  npx mern-template-tool employee-management
+  npx mern-template-tool library-app
+`);
+}
+
+function copyDirRecursive(source, target) {
+  if (!fs.existsSync(target)) {
+    fs.mkdirSync(target, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(source, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(source, entry.name);
+    // Handle dotfiles if renamed or standard (like _gitignore -> .gitignore or .env.example)
+    let destName = entry.name;
+    if (entry.name === '_gitignore') {
+      destName = '.gitignore';
+    }
+    const destPath = path.join(target, destName);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+    printUsage();
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+
+  const projectName = args[0].trim();
+
+  if (!projectName || /^[./\\]+$/.test(projectName)) {
+    console.error('\x1b[31mError: Please provide a valid project folder name.\x1b[0m');
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    const existingFiles = fs.readdirSync(targetDir);
+    if (existingFiles.length > 0) {
+      console.error(`\x1b[31mError: Directory '${projectName}' already exists and is not empty.\x1b[0m`);
+      console.error('Please specify a new directory name or empty the existing directory.');
+      process.exit(1);
+    }
+  }
+
+  const templateDir = path.resolve(__dirname, '..', 'templates');
+
+  if (!fs.existsSync(templateDir)) {
+    console.error(`\x1b[31mError: Template directory not found at ${templateDir}\x1b[0m`);
+    process.exit(1);
+  }
+
+  console.log(`\n\x1b[32m✔\x1b[0m Generating MERN stack project in \x1b[33m${targetDir}\x1b[0m...\n`);
+
+  try {
+    copyDirRecursive(templateDir, targetDir);
+
+    // Make sure uploads directory exists in server
+    const uploadsDir = path.join(targetDir, 'server', 'uploads');
+    if (!fs.existsSync(uploadsDir)) {
+      fs.mkdirSync(uploadsDir, { recursive: true });
+    }
+
+    console.log(`\x1b[32m✔\x1b[0m Project successfully generated!\n`);
+    console.log(`\x1b[1mNext Steps to run your project:\x1b[0m`);
+    console.log(`\x1b[36m--------------------------------------------------\x1b[0m`);
+    console.log(`1. Navigate to your project directory:`);
+    console.log(`   \x1b[33mcd ${projectName}\x1b[0m\n`);
+    console.log(`2. Setup and Start Backend Server:`);
+    console.log(`   \x1b[33mcd server\x1b[0m`);
+    console.log(`   \x1b[33mcp .env.example .env\x1b[0m  (or copy .env.example to .env on Windows)`);
+    console.log(`   \x1b[33mnpm install\x1b[0m`);
+    console.log(`   \x1b[33mnpm run dev\x1b[0m  (Runs on http://localhost:5000)\n`);
+    console.log(`3. Setup and Start React Client:`);
+    console.log(`   \x1b[33mcd ../client\x1b[0m`);
+    console.log(`   \x1b[33mnpm install\x1b[0m`);
+    console.log(`   \x1b[33mnpm run dev\x1b[0m  (Runs on http://localhost:5173)\n`);
+    console.log(`4. Access Admin EJS Application:`);
+    console.log(`   Open \x1b[34mhttp://localhost:5000/admin/login\x1b[0m\n`);
+    console.log(`\x1b[36m--------------------------------------------------\x1b[0m`);
+    console.log(`\x1b[32mAll features (JWT Auth, Sessions, EJS, Multer, Generic CRUD, React Context) are ready to use!\x1b[0m\n`);
+  } catch (err) {
+    console.error(`\x1b[31mError generating project:\x1b[0m`, err);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "mern-template-tool",
+  "version": "1.0.0",
+  "description": "Exam-oriented MERN stack project generator with JWT, sessions, EJS, React Context, Multer, and generic CRUD",
+  "main": "bin/index.js",
+  "bin": {
+    "mern-template-tool": "bin/index.js",
+    "mern-template": "bin/index.js"
+  },
+  "keywords": [
+    "mern",
+    "template",
+    "generator",
+    "react",
+    "express",
+    "mongodb",
+    "exam",
+    "jwt",
+    "auth",
+    "ejs",
+    "multer"
+  ],
+  "author": "smit-mendapara",
+  "license": "MIT",
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/templates/README.md

@@ -0,0 +1,160 @@
+# Generated MERN Project (Exam-Ready & Offline First)
+
+This is a production-ready, exam-oriented full-stack MERN application generated by `mern-template`. It provides complete authentication (JWT & express-session), authorization, MVC generic resource CRUD, search/filtering/sorting, express-validator validation, Multer file upload/download, centralized error handling, React Context state management, and protected React routing.
+
+---
+
+## 📁 Project Structure
+
+```text
+.
+├── client/                     # React Single Page Application (Vite)
+│   ├── src/
+│   │   ├── components/         # Reusable UI (Navbar, Loading)
+│   │   ├── context/            # AuthContext (React Context API)
+│   │   ├── pages/              # Login, Register, Dashboard, Profile, Resources, etc.
+│   │   ├── routes/             # ProtectedRoute wrapper
+│   │   ├── services/           # api.js (native fetch HTTP client)
+│   │   ├── App.jsx             # Main router
+│   │   ├── index.css           # Modern CSS styling
+│   │   └── main.jsx            # React root
+│   ├── package.json
+│   └── vite.config.js
+│
+├── server/                     # Express.js REST API & EJS Admin Portal
+│   ├── config/                 # db.js (Mongoose connection)
+│   ├── controllers/            # authController.js, resourceController.js
+│   ├── middleware/             # authMiddleware, adminMiddleware, uploadMiddleware, validateMiddleware, errorMiddleware, sessionAuthMiddleware
+│   ├── models/                 # User.js, Resource.js
+│   ├── routes/                 # authRoutes.js, resourceRoutes.js, adminRoutes.js
+│   ├── utils/                  # jwt.js
+│   ├── views/                  # EJS admin templates (login.ejs, dashboard.ejs, partials/)
+│   ├── uploads/                # Local file storage for Multer
+│   ├── .env.example            # Environment variables example
+│   ├── package.json
+│   └── server.js               # Express application entrypoint
+│
+└── README.md
+```
+
+---
+
+## 🚀 Quick Start Guide
+
+### 1. Prerequisites
+- **Node.js** (v16+)
+- **MongoDB** running locally on `mongodb://127.0.0.1:27017`
+
+### 2. Backend Setup
+```bash
+cd server
+cp .env.example .env     # (On Windows cmd: copy .env.example .env)
+npm install
+npm run dev              # Server starts on http://localhost:5000
+```
+
+### 3. Frontend Setup
+```bash
+cd client
+npm install
+npm run dev              # Client starts on http://localhost:5173
+```
+
+---
+
+## 🌐 Endpoints & URLs Reference
+
+### 🔐 React Application
+- **URL**: `http://localhost:5173`
+- **Features**: Registration, Login, Dashboard, Profile, Resource Listing, Create/Edit/Delete, File Upload, Instant Search & Sorting.
+
+### 🛡️ EJS Admin Portal (Session Authentication)
+- **Login URL**: `http://localhost:5000/admin/login`
+- **Dashboard URL**: `http://localhost:5000/admin/dashboard`
+- **Default Behavior**: Register an admin user via React (or seed one), then sign in through the EJS portal to manage users and inspect system statistics.
+
+### 📡 REST API Routes
+| Method | Endpoint | Access | Description |
+|---|---|---|---|
+| `POST` | `/api/auth/register` | Public | Register student or admin |
+| `POST` | `/api/auth/login` | Public | Login & receive JWT |
+| `GET` | `/api/auth/me` | Protected (JWT) | Get authenticated user profile |
+| `GET` | `/api/resources` | Public | Get resources (supports `?search=&category=&sort=`) |
+| `GET` | `/api/resources/:id` | Public | Get single resource by ID |
+| `GET` | `/api/resources/:id/download`| Public | Download attached file |
+| `POST` | `/api/resources` | Protected (JWT) | Create resource (`multipart/form-data` with file) |
+| `PUT` | `/api/resources/:id` | Protected (Owner/Admin) | Update resource & replace file |
+| `DELETE` | `/api/resources/:id` | Protected (Owner/Admin) | Delete resource & remove file |
+
+---
+
+## 💡 Practical Exam Quick Reference & Cheatsheet
+
+### 1. Express Request Objects
+- `req.body`: Form or JSON payload sent in `POST`/`PUT` requests.
+- `req.params`: URL parameters (e.g. `req.params.id` from `/api/resources/:id`).
+- `req.query`: Query string parameters (e.g. `req.query.search` from `/api/resources?search=mern`).
+- `req.file`: Attached file uploaded via Multer (`upload.single('file')`).
+- `req.user`: User payload attached by JWT auth middleware (`req.user._id`, `req.user.role`).
+
+### 2. Mongoose Model Methods
+```js
+// Find all matching criteria
+const items = await Model.find({ category: 'Exam' }).sort({ createdAt: -1 });
+
+// Find single document by ID
+const item = await Model.findById(req.params.id);
+
+// Create document
+const newItem = await Model.create({ title: 'Sample', createdBy: req.user._id });
+
+// Update document by ID
+const updated = await Model.findByIdAndUpdate(req.params.id, req.body, { new: true });
+
+// Delete document by ID
+await Model.findByIdAndDelete(req.params.id);
+```
+
+### 3. Password Hashing (bcryptjs)
+```js
+const bcrypt = require('bcryptjs');
+// Hash password
+const salt = await bcrypt.genSalt(10);
+const hashedPassword = await bcrypt.hash(password, salt);
+
+// Compare password
+const isMatch = await bcrypt.compare(plainPassword, hashedPassword);
+```
+
+### 4. JWT Generation & Verification
+```js
+const jwt = require('jsonwebtoken');
+// Generate Token
+const token = jwt.sign({ id: user._id, role: user.role }, process.env.JWT_SECRET, { expiresIn: '1d' });
+
+// Verify Token
+const decoded = jwt.verify(token, process.env.JWT_SECRET);
+```
+
+### 5. React Hooks & Context
+```jsx
+import { useState, useEffect } from 'react';
+import { useAuth } from '../context/AuthContext';
+import { useNavigate, useParams } from 'react-router-dom';
+
+const { user, isAuthenticated, logout } = useAuth();
+const navigate = useNavigate();
+const { id } = useParams();
+```
+
+---
+
+## 🛠️ How to Customize for Specific Exam Questions
+
+1. **Renaming the Resource Model**:
+   - To build a **Library / Book Management System**: Rename `Resource.js` to `Book.js`, change `title` to `bookName`, `category` to `genre`, and `description` to `author`.
+   - To build an **Employee System**: Rename `Resource.js` to `Employee.js`, fields to `name`, `department`, `salary`, `designation`.
+2. **Adding New Routes**:
+   - Create router in `server/routes/xyzRoutes.js` and register in `server.js` using `app.use('/api/xyz', xyzRouter);`.
+3. **Updating Frontend Form Fields**:
+   - Update `client/src/pages/CreateResource.jsx` and `EditResource.jsx` with input elements matching your new model fields.

package/templates/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+.env
+uploads/*
+!uploads/.gitkeep
+dist
+dist-ssr
+*.local
+.DS_Store

package/templates/client/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>MERN Application</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/templates/client/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "client",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.23.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.0",
+    "vite": "^5.2.11"
+  }
+}

package/templates/client/src/App.jsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { Routes, Route, Navigate } from 'react-router-dom';
+import Navbar from './components/Navbar';
+import ProtectedRoute from './routes/ProtectedRoute';
+
+// Pages
+import Login from './pages/Login';
+import Register from './pages/Register';
+import Dashboard from './pages/Dashboard';
+import Profile from './pages/Profile';
+import Resources from './pages/Resources';
+import ResourceDetails from './pages/ResourceDetails';
+import CreateResource from './pages/CreateResource';
+import EditResource from './pages/EditResource';
+import NotFound from './pages/NotFound';
+
+function App() {
+  return (
+    <div className="app">
+      <Navbar />
+      <main>
+        <Routes>
+          {/* Public Routes */}
+          <Route path="/" element={<Navigate to="/resources" replace />} />
+          <Route path="/login" element={<Login />} />
+          <Route path="/register" element={<Register />} />
+          <Route path="/resources" element={<Resources />} />
+          <Route path="/resources/:id" element={<ResourceDetails />} />
+
+          {/* Protected Routes (JWT required) */}
+          <Route
+            path="/dashboard"
+            element={
+              <ProtectedRoute>
+                <Dashboard />
+              </ProtectedRoute>
+            }
+          />
+          <Route
+            path="/profile"
+            element={
+              <ProtectedRoute>
+                <Profile />
+              </ProtectedRoute>
+            }
+          />
+          <Route
+            path="/resources/new"
+            element={
+              <ProtectedRoute>
+                <CreateResource />
+              </ProtectedRoute>
+            }
+          />
+          <Route
+            path="/resources/:id/edit"
+            element={
+              <ProtectedRoute>
+                <EditResource />
+              </ProtectedRoute>
+            }
+          />
+
+          {/* 404 Catch All */}
+          <Route path="*" element={<NotFound />} />
+        </Routes>
+      </main>
+    </div>
+  );
+}
+
+export default App;

package/templates/client/src/components/Loading.jsx

@@ -0,0 +1,14 @@
+import React from 'react';
+
+const Loading = ({ message = 'Loading...' }) => {
+  return (
+    <div className="spinner-container">
+      <div style={{ textAlign: 'center' }}>
+        <div className="spinner" style={{ margin: '0 auto 1rem auto' }}></div>
+        <p style={{ color: 'var(--text-secondary)', fontSize: '0.9rem' }}>{message}</p>
+      </div>
+    </div>
+  );
+};
+
+export default Loading;

package/templates/client/src/components/Navbar.jsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import { Link, NavLink, useNavigate } from 'react-router-dom';
+import { useAuth } from '../context/AuthContext';
+
+const Navbar = () => {
+  const { user, isAuthenticated, logout } = useAuth();
+  const navigate = useNavigate();
+
+  const handleLogout = () => {
+    logout();
+    navigate('/login');
+  };
+
+  return (
+    <nav className="navbar">
+      <Link to="/" className="nav-brand">
+        🚀 MERN App
+      </Link>
+
+      <div className="nav-links">
+        <NavLink to="/resources">Resources</NavLink>
+
+        {isAuthenticated ? (
+          <>
+            <NavLink to="/dashboard">Dashboard</NavLink>
+            <NavLink to="/resources/new">Create Resource</NavLink>
+            <NavLink to="/profile">Profile ({user?.name})</NavLink>
+            <button
+              onClick={handleLogout}
+              className="btn btn-secondary btn-sm"
+              style={{ marginLeft: '0.5rem' }}
+            >
+              Logout
+            </button>
+          </>
+        ) : (
+          <>
+            <NavLink to="/login">Login</NavLink>
+            <NavLink to="/register" className="btn btn-primary btn-sm">
+              Register
+            </NavLink>
+          </>
+        )}
+
+        <a
+          href="http://localhost:5000/admin/login"
+          target="_blank"
+          rel="noreferrer"
+          style={{ fontSize: '0.8rem', color: '#a5b4fc', borderLeft: '1px solid #334155', paddingLeft: '0.75rem' }}
+        >
+          Admin Portal (EJS) &rarr;
+        </a>
+      </div>
+    </nav>
+  );
+};
+
+export default Navbar;