CRUD-X [XERN Stack]

A basic CRUD web application using [X]ERN stack, Where X = multiple DB but as of now MongoDB. So MERN.

NOTE : Due to Time constraint, built only fullstack web app with basic feature. Will scale it to fully functional fullstack E-commerce app with multi-DB [XERN] with proper Validation & Testing features soon.

Live Testing Link (Production Ready | Backend webservice | Node/Expressjs Server | REST API)

API Collection : Postman
Deployment (Frontend - Main): Render.com
Deployment (Backend): Render.com

Tech stack : [X]ERN

Architectural : Agile-Monolith-MVC (Future - Component based + TDD)

Frontend - client | static-site | web-asset | ui: Reactjs

Backend - Webserver/service/host/api | app-server: Nodejs/express

DBaaS [X] : mongodb atlas (Future - elephantsql (postgre) | cockroachlab | astra (cassandra) | planetscale (mysql) | elasticloud)

Installation | Deployment (local)

For Fullstack (MERN) : npm FSUpdatePkgs - to update local pkg to latest ver See this

  cd CRUD-X
  npm FSinstall
  npm FSdev (For Development - localhost)
  npm FSprod (For production)

For Backend only (Node/Express) :

  cd CRUD-X/server
  npm install
  npm dev (For Development - localhost)
  npm prod (For production)

For Frontend only (React/CRA-webpack) :

  cd CRUD-X/client
  npm install
  npm start (For Development - localhost)
  npm build (For production)

Set the environment variables:

cp .env.example .env

# open .env and modify the environment variables (if needed) [Same for .env.development & .env.test]

Features (Major)

NoSQL database: MongoDB object data modeling using Mongoose [Future : Multi-DB]
Authentication and authorization(RBAC): using passport [JWT, Google OAuth 2.0]
Validation: request data validation using Joi
Logging: using winston and morgan
Testing: unit and integration tests using Jest [Supertest]
Error handling: centralized error handling mechanism (express middleware)
API docs: with swagger-jsdoc and swagger-ui-express
Process management: advanced production process management using PM2 [Not used in Prod]
Dependency management: with npm
Environment variables: using dotenv [Multi-Env : Dev, Prod, Test]
CORS: Cross-Origin Resource-Sharing enabled using cors
Linting: with ESLint and Prettier
Security: set security HTTP headers using helmet [#Future-Implementation]
Santizing: sanitize request data against xss and query injection [#Future-Implementation]
Compression: gzip compression with compression [#Future-Implementation]
CI: continuous integration with Travis CI [#Future-Implementation]
Code coverage: using coveralls [#Future-Implementation]
Code quality: with Codacy [#Future-Implementation]
Docker support [#Future-Implementation]

Developer environment setup : IDE | vcs/scm | deployment | devops

Local IDE : VSCode

VSCode : (See below Linter/Formatter section too)
- Preq. - Git & Node (npm)
- Git-bash : NPM global pkgs manual backup - npmGpkg File (see CRUD-X Repo)
- Ext. : Setting Sync on via Github A/C (update outdated npm global & local pkg manually | VScode ext. autoupdate)
Theme Download Links:
- Product Icon Theme - Carbon
- File Icon Theme - Material
- Color Theme (General)
  - Ligature Fonts - Cascadia Code | Fira Code
    - Note : Fira code includes Fira Mono | Editor Font size is 16 & Terminal is 15
    - Editor.FontFamily : 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace
  - Shell Theme (Terminal)
    - Nerd Fonts (Not Powerline Fonts)
      - Cascadia/Caskaydia NF
        
        Installation
        
        Terminal Font Family : 'CaskaydiaCove NF', 'CaskaydiaCove NF Mono', 'Cascadia Code', 'Fira Code', Consolas
    - Cross- Shell prompt - Starship (For bash & powershell only, not cmd) (Default configs)
    - Toggle Theme -> Ctrl+Alt+Shift+T
    - Settings.json Workbench : Search "Preferred Color Theme"
      - Dark : One Dark Pro
      - Light : Brackets Light Pro
Online Code Snippet/Sandbox : carbon.now.sh, Codepen.io

Browser : Mozilla | Chrome (Extension - React devtools, Redux devtools) (Sync Setting on - PENDING)

VCS/SCM : Github

Cloud IDE (Remote) : Github Codespace (Alternative - Repl.it [Mobile App/Hosting])

Devops (CI/CD) : Github Actions (For Dockerize : Docker/K8's)

Deployment (PaaS) :

Render.com (Frontend/Static-Site/React-CRA)
- Render.com is preferred as of now over vercel here bcz backend is implemented on it & its easy to deploy.
- Commands : build -> npm run build || publish directory -> build (No npm start command as its not hosted locally)
Render.com (Backend/webservice) | DB (MongoDB Atlas)
- Render.com is preferred as of now over railway.app/vercel/heroku bcz either they are not free or support serverless fn which is hard to deploy.
- Env Var. : Copy & paste production env file (except PORT as its assigned automatically) & change config env to prod.
- Commands : Build -> npm run prod || Install -> npm install

Linting | Formating Clean Code Style/Best Practises

NOTE : This Configuration/setups are for advanced level, skip this if u r beginner/intermediate, just install eslint & prettier vscode ext. NOTE : js/jsx & ts/tsx is not diff. it's just use to denote that js/ts is for normal & jsx/tsx is for component. But .cjs & .mjs are diff. NOTE : For browser default is CJS in html <script> tag, but if ur using MJS then u need to mention "type=module" in <script> tag. As we are using react here, we dont need to worry as react will build html for us. NOTE : Alternative Names CJS => Source Type - Script | MJS => Source Type - Module

Extensions | NPM Packages (-D)
- L1 | L2 | L3 | L4 | L5 | L6 | L7
- VSCode : Global
  - Linter : Eslint
  - Formatter : Prettier
  - (Lint+Format) : Lintel, Prettier ESlint etc. (Refer Official website of both)
- Node/NPM : Local (-D)
  - React : react, react-dom, jest
  - Linting (FE/BE)
    - Eslint : eslint, eslint-cli (CRA ESlint extends "react-app")
    - TS : typescript, ts-node, types/node, types/react, types/react-dom
  - Formatter : prettier
  - (Lint+Format) : prettier-eslint, etc. (Refer Official website of both)
  - Config (Custom) : .eslintrc.js (extends airbnb, react-app, etc), .prettierrc, .editorconfig, etc.
    - tsconfig.json (.tslintrc deprecated in favor of .eslintrc)
      - module = NodeNext for MJS & commonJS for CJS // 'import' needs .js extn. for MJS & .cjs for CJS
      - moduleResolution = NodeNext
Frontend (React v18+) : React is defaulted to ES6/MJS module system.
- Current : Javascript (ES6+)
  - Filename : .js/.jsx (js/jsx are equiv. here but as mentioned in note above, we use it for diff. purpose)
  - Module system : ES6 (.mjs) => import/export (we don't need to have .mjs extension bcz react CRA defaults to mjs so js/jsx=mjs)
- Future : Typescript (CRA --template typescript)
  - Filename : .ts/.tsx (ts/tsx are equiv. here but as mentioned in note above, we use it for diff. purpose)
  - Module system : ES6 (.mjs) => import/export (js/jsx=mjs=ts/tsx, so we use ts/tsx only)
Backend (Node v18+) : Node is defaulted to commonJS/js/cjs module system => require/module.exports
- Current : Javascript (ES6+) // Node is defaulted to CJS, but here we use MJS so following settings will change.
  - Filename : .js/.mjs (Package.json => "type": "module") // Both js/mjs are equiv here bcz "module" is mentioned in package.json, we stick to .js
  - Module system : ES6 (js/mjs) => import/export // We r using "mjs", but if you wanna use "cjs" somewhere add "abc.cjs" ext. explicitly
- Future : Typescript see
  - Filename : .ts (Package.json => "type": "module" | tsc compiler : a.ts => a.js | node a.js)
  - Module system : ES6 (.mjs) => import/export (js=mjs=ts, so we use ts only)

Fullstack flow : REST | CRUD | HTTP

Google Docs Link

Environment Variables

The environment variables can be found and modified in the .env file. They come with these default values:

NODE_ENV = development
# Port number
PORT = 3000
# URL of the Mongo DB
MONGODB_ATLAS_URL=mongodb://127.0.0.1:27017/node-boilerplate

# JWT
# JWT secret key
JWT_SECRET=thisisasamplesecret
# Number of minutes after which an access token expires
JWT_ACCESS_EXPIRATION_MINUTES=30
# Number of days after which a refresh token expires
JWT_REFRESH_EXPIRATION_DAYS=30
# Number of minutes after which a reset password token expires [RPT]
JWT_RESET_PASSWORD_EXPIRATION_MINUTES=10
# Number of minutes after which a verify email token expires [VET]
JWT_VERIFY_EMAIL_EXPIRATION_MINUTES=10

# SMTP configuration options for the email service
# For testing, you can use a fake SMTP service like Ethereal: https://ethereal.email/create
SMTP_HOST=email-server
SMTP_PORT=587
SMTP_USERNAME=email-server-username
SMTP_PASSWORD=email-server-password
EMAIL_FROM=support@yourapp.com

#Google-OAuth
GOOGLE_OAUTH_CLIENT_ID = 21321mklmklmlkmalsad.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET = KMKLK-dkfmlksdmfksd-ksdfmdslkdsfds

Project Structure (separation of concern)

**CRUD-X (Root Folder)**/
├── **Client** [Feature/funct./comp. based] (Other - MVC, group by file type, pages with global folder/colocation of related comp. etc.)/
│   ├── public
│   ├── src/
│   │   ├── Assets : images, static file etc.
│   │   ├── Components (Templates/Props)/
│   │   │   ├── core : common and basic components, such as Home,Menu components which are common to all other comp.
│   │   │   ├── post : post-related components
│   │   │   ├── user : user-related components
│   │   │   └── componentFolderN : and so on....
│   │   ├── Pages
│   │   ├── Config (To overwrite global config - .eslintrc.js, .prettierrc, .editorconfig - CRA/webpack already has eslint so gen. we dont include it)
│   │   ├── i18n
│   │   ├── navigation : Router (Navigation) -> react-router-dom
│   │   ├── redux : actions, reducers, store.js [Redux Toolkit -> Redux & Thunk Dev tools]
│   │   ├── Services - API/
│   │   │   └── auth : auth-related components and helper code, routes etc.
│   │   ├── styles
│   │   ├── utils - Helper methods, validations etc.
│   │   ├── **tests** : Jest Framework (Unit testing)
│   │   └── index.js ===> Main entry point for react
│   ├── node_modules (frontend)
│   ├── .gitignore (frontend)
│   ├── Package.json (frontend) - including package-lock.json
│   └── README.MD (frontend)
├── **Server** [Separation based on functionality - [MVC](https://www.youtube.com/watch?v=bQuBlR0T5cc) or Technical Role based => FUTURE PENDING : [Component based](https://github.com/goldbergyoni/nodebestpractices#-11-structure-your-solution-by-components)]/
│   ├── app/
│   │   ├── config
│   │   ├── controllers
│   │   ├── docs
│   │   ├── middlewares
│   │   ├── models (ORM/MongoDB)
│   │   ├── routes -> [RESTful API endpoints - CRUD](https://stackoverflow.com/questions/14554943/what-are-the-trade-offs-between-different-methods-of-constructing-api-urls-subd) | [Link 1](https://ontola.io/blog/api-design/)
│   │   ├── services
│   │   ├── utils
│   │   ├── validations
│   │   ├── views
│   │   └── index.js -> Application code (MVC part)
│   ├── env -> .env, .env.development etc.
│   ├── tests -> Unit, Integration, fixtures, utils etc.
│   ├── server.js ===> Main entry point for nodejs server - contains http server, mongoose/mongodb conn, n/w, file calls etc.
│   ├── node_modules (backend)
│   ├── .env.example (backend)
│   ├── .travis.yml (backend)
│   ├── babel.config.js (backend)
│   ├── jest.config.js (backend)
│   ├── .gitignore (backend)
│   ├── Package.json (backend) - including package-lock.json, scripts (dev/prod)
│   └── README.MD (backend)
├── node_modules (root)
├── Package.json (root) : shared b/w both FE & BE - including package-lock.json
├── License (root)
├── npmGpkg (root)
├── .gitignore (root)
└── README.MD (root)

Error Handling

The app has a centralized error handling mechanism.

Controllers should try to catch the errors and forward them to the error handling middleware (by calling next(error)). For convenience, you can also wrap the controller inside the asyncWrapTC utility wrapper, which forwards the error.

import { asyncWrapTC } from "../utils/tryCatchAsync.helper.js";

// CREATE (POST) : Creates a new user.
const createUser = asyncWrapTC(async (req, res) => {
  await userService.addUser(req, res);
  return res.status(httpStatusCodes.CREATED).send("New User Created!!");
});

The error handling middleware sends an error response, which has the following format:

{
  "code": 404,
  "message": "Not found"
}

When running in development mode, the error response also contains the error stack.

The app has a utility ApiError class to which you can attach a response code and a message, and then throw it from anywhere (asyncWrapTC will catch it).

For example, if you are trying to get a user from the DB who is not found, and you want to send a 404 error, the code should look something like:

const httpStatus = require("http-status");
const ApiError = require("../utils/ApiError");
const User = require("../models/User");

const getUser = async (userId) => {
  const user = await User.findById(userId);
  if (!user) {
    throw new ApiError(httpStatus.NOT_FOUND, "User not found");
  }
};

Validation

Request data is validated using Joi. Check the documentation for more details on how to write Joi validation schemas.

The validation schemas are defined in the src/validations directory and are used in the routes by providing them as parameters to the validate middleware.

const express = require("express");
const validate = require("../../middlewares/validate");
const userValidation = require("../../validations/user.validation");
const userController = require("../../controllers/user.controller");

const router = express.Router();

router.post(
  "/users",
  validate(userValidation.createUser),
  userController.createUser
);

API Documentation

To view the list of available APIs and their specifications, run the server and go to http://localhost:3000/v1/docs in your browser. This documentation page is automatically generated using the swagger definitions written as comments in the route files.

API Endpoints (Routes)

List of available routes:

AuthN routes (JWT):
POST /v1/auth/register - register
POST /v1/auth/login - login
POST /v1/auth/logout - logout
POST /v1/auth/refresh-tokens - refresh auth tokens
POST /v1/auth/home-jwt - JWT homepage after auth

AuthN routes (Google OAuth 2.0):
GET /SignInWithGoogleOAuth2Button - Sign In Button (index.html) (Should be added to Redirect uri in Google Cloud console creds)
GET /v1/auth/loginGoogleOAuth2 - Callback URL (Should be added to Redirect uri in Google Cloud console creds)
GET /logoutGoogleOAuth2 - Delete cookie and destroy session (backend only : bug -> back btn will still works)
GET /home - Protected route will be called after succesful login via Google OAuth2

User routes:
POST /v1/users - create a user
GET /v1/users - get all users

Other routes:
GET / - Default Route will serve index.html via express.static
GET /favicon.ico - just to ignore favicon error in logs

Authentication (AuthN : JWT & Google OAuth 2.0)

To require authentication for certain routes, you can use the auth middleware.

const express = require("express");
const auth = require("../../middlewares/auth");
const userController = require("../../controllers/user.controller");

const router = express.Router();

router.post("/users", auth(), userController.createUser);

These routes require a valid JWT access token in the Authorization request header using the Bearer schema. If the request does not contain a valid access token, an Unauthorized (401) error is thrown.

Generating Access Tokens:

An access token can be generated by making a successful call to the register (POST /v1/auth/register) or login (POST /v1/auth/login) endpoints. The response of these endpoints also contains refresh tokens (explained below).

An access token is valid for 30 minutes. You can modify this expiration time by changing the JWT_ACCESS_EXPIRATION_MINUTES environment variable in the .env file.

Refreshing Access Tokens:

After the access token expires, a new access token can be generated, by making a call to the refresh token endpoint (POST /v1/auth/refresh-tokens) and sending along a valid refresh token in the request body. This call returns a new access token and a new refresh token.

A refresh token is valid for 30 days. You can modify this expiration time by changing the JWT_REFRESH_EXPIRATION_DAYS environment variable in the .env file.

Authorization (AuthR : RBAC)

The auth middleware can also be used to require certain rights/permissions to access a route.

const express = require("express");
const auth = require("../../middlewares/auth");
const userController = require("../../controllers/user.controller");

const router = express.Router();

router.post("/users", auth("manageUsers"), userController.createUser);

In the example above, an authenticated user can access this route only if that user has the manageUsers permission.

The permissions are role-based. You can view the permissions/rights of each role in the src/config/roles.js file.

If the user making the request does not have the required permissions to access this route, a Forbidden (403) error is thrown.

Logging

Import the logger from src/config/logger.js. It is using the Winston logging library.

Logging should be done according to the following severity levels (ascending order from most important to least important):

const logger = require("<path to src>/config/logger");

logger.error("message"); // level 0
logger.warn("message"); // level 1
logger.info("message"); // level 2
logger.http("message"); // level 3
logger.verbose("message"); // level 4
logger.debug("message"); // level 5

In development mode, log messages of all severity levels will be printed to the console.

In production mode, only info, warn, and error logs will be printed to the console.
It is up to the server (or process manager) to actually read them from the console and store them in log files.
This app uses pm2 in production mode, which is already configured to store the logs in log files.

Note: API request information (request url, response code, timestamp, etc.) are also automatically logged (using morgan).

Custom Mongoose Plugins

The app also contains a custom mongoose plugins that you can attach to any mongoose model schema. You can find the plugins in src/models/plugins.

const mongoose = require("mongoose");
const { toJSON } = require("./plugins");

const userSchema = mongoose.Schema(
  {
    /* schema definition here */
  },
  { timestamps: true }
);

userSchema.plugin(toJSON);

const User = mongoose.model("User", userSchema);

toJSON

The toJSON plugin applies the following changes in the toJSON transform call:

removes __v, createdAt, updatedAt, and any schema path that has private: true
replaces _id with id

Contributing

Contributions are always Welcome. Make a Pull Request (PR) or raise an issue. Will review them when time permits.

FAQ

Is this CRUD App for commercial use ?

Nope. But if anyone wants to use it in their project as boilerplate etc. feel free to use.

Is this your Personal project ?

Yup, to clear out my basics of fullstack web app dev.

Feedback & Support

If you have any feedback, please reach out to me at sonimonish00[at]gmail[dot]com

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

CRUD-X [XERN Stack]

Tech stack : [X]ERN

Installation | Deployment (local)

Table of Contents

Features (Major)

Developer environment setup : IDE | vcs/scm | deployment | devops

Linting | Formating Clean Code Style/Best Practises

Fullstack flow : REST | CRUD | HTTP

Environment Variables

Project Structure (separation of concern)

Error Handling

Validation

API Documentation

API Endpoints (Routes)

Authentication (AuthN : JWT & Google OAuth 2.0)

Authorization (AuthR : RBAC)

Logging

Custom Mongoose Plugins

toJSON

Contributing

FAQ

Is this CRUD App for commercial use ?

Is this your Personal project ?

Feedback & Support

🚀 About Me : Hi, I'm Monish! 👋

🛠 Skills

🔗 Contact Links

Files

README.md

Latest commit

History

README.md

File metadata and controls

CRUD-X [XERN Stack]

Tech stack : [X]ERN

Installation | Deployment (local)

Table of Contents

Features (Major)

Developer environment setup : IDE | vcs/scm | deployment | devops

Linting | Formating Clean Code Style/Best Practises

Fullstack flow : REST | CRUD | HTTP

Environment Variables

Project Structure (separation of concern)

Error Handling

Validation

API Documentation

API Endpoints (Routes)

Authentication (AuthN : JWT & Google OAuth 2.0)

Authorization (AuthR : RBAC)

Logging

Custom Mongoose Plugins

toJSON

Contributing

FAQ

Is this CRUD App for commercial use ?

Is this your Personal project ?

Feedback & Support

🚀 About Me : Hi, I'm Monish! 👋

🛠 Skills

🔗 Contact Links