create-nodejs-express-starter 1.7.0

package/.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+.git
+.gitignore

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

package/.env.example

@@ -0,0 +1,22 @@
+# Application
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=info
+CORS_ORIGIN=*
+
+# Database
+MONGODB_URL=mongodb://127.0.0.1:27017/node-boilerplate
+
+# JWT
+JWT_SECRET=your-super-secret-key-change-in-production
+JWT_ACCESS_EXPIRATION_MINUTES=30
+JWT_REFRESH_EXPIRATION_DAYS=30
+JWT_RESET_PASSWORD_EXPIRATION_MINUTES=10
+JWT_VERIFY_EMAIL_EXPIRATION_MINUTES=10
+
+# SMTP (optional - for email verification and password reset)
+SMTP_HOST=email-server
+SMTP_PORT=587
+SMTP_USERNAME=email-server-username
+SMTP_PASSWORD=email-server-password
+EMAIL_FROM=support@yourapp.com

package/.eslintignore

@@ -0,0 +1,2 @@
+node_modules
+bin

package/.eslintrc.json

@@ -0,0 +1,32 @@
+{
+  "env": {
+    "node": true,
+    "jest": true
+  },
+  "extends": ["airbnb-base", "plugin:jest/recommended", "plugin:prettier/recommended"],
+  "plugins": ["jest", "security", "prettier"],
+  "parserOptions": {
+    "ecmaVersion": 2018
+  },
+  "rules": {
+    "no-console": "error",
+    "func-names": "off",
+    "no-underscore-dangle": "off",
+    "consistent-return": "off",
+    "jest/expect-expect": "off",
+    "security/detect-buffer-noassert": "warn",
+    "security/detect-child-process": "warn",
+    "security/detect-disable-mustache-escape": "warn",
+    "security/detect-eval-with-expression": "warn",
+    "security/detect-new-buffer": "warn",
+    "security/detect-no-csrf-before-method-override": "warn",
+    "security/detect-non-literal-fs-filename": "warn",
+    "security/detect-non-literal-regexp": "warn",
+    "security/detect-non-literal-require": "warn",
+    "security/detect-object-injection": "off",
+    "security/detect-possible-timing-attacks": "warn",
+    "security/detect-pseudoRandomBytes": "warn",
+    "security/detect-unsafe-regex": "warn",
+    "security/detect-bidi-characters": "warn"
+  }
+}

package/.gitignore

@@ -0,0 +1,14 @@
+# Dependencies
+node_modules
+
+# yarn error logs
+yarn-error.log
+
+# Environment varibales
+.env*
+!.env*.example
+
+# Code coverage
+coverage
+
+meow

package/.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+coverage
+

package/.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "printWidth": 125
+}

package/Dockerfile

@@ -0,0 +1,15 @@
+FROM node:alpine
+
+RUN mkdir -p /usr/src/node-app && chown -R node:node /usr/src/node-app
+
+WORKDIR /usr/src/node-app
+
+COPY package.json package-lock.json ./
+
+USER node
+
+RUN npm ci
+
+COPY --chown=node:node . .
+
+EXPOSE 3000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Hagop Jamkojian
+
+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,440 @@
+# RESTful API Node Server Boilerplate
+
+[![Coverage Status](https://coveralls.io/repos/github/Ahlyab/express-backend-starter-js/badge.svg?branch=main)](https://coveralls.io/github/Ahlyab/express-backend-starter-js?branch=main)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+
+A boilerplate/starter project for quickly building RESTful APIs using Node.js, Express, and Mongoose.
+
+By running a single command, you will get a production-ready Node.js app installed and fully configured on your machine. The app comes with many built-in features, such as authentication using JWT, request validation, unit and integration tests, continuous integration, docker support, API documentation, pagination, etc. For more details, check the features list below.
+
+## Quick Start
+
+To create and initialize a new project in one command:
+
+```bash
+npx nodejs-express-starter <project-name>
+```
+
+Or:
+
+```bash
+npm init nodejs-express-starter <project-name>
+```
+
+This will create a new folder with the project name, copy the template, install dependencies (`npm install`), and set up `.env` from `.env.example`. Then:
+
+```bash
+cd <project-name>
+# edit .env if needed
+npm run dev
+```
+
+## Manual Installation
+
+If you prefer to clone and set up manually:
+
+Clone the repo:
+
+```bash
+git clone --depth 1 https://github.com/Ahlyab/express-backend-starter-js.git
+cd express-backend-starter-js
+npx rimraf ./.git
+```
+
+Install the dependencies:
+
+```bash
+npm install
+```
+
+Set the environment variables:
+
+```bash
+cp .env.example .env
+
+# open .env and modify the environment variables (if needed)
+```
+
+## Table of Contents
+
+- [Features](#features)
+- [Commands](#commands)
+- [Environment Variables](#environment-variables)
+- [Project Structure](#project-structure)
+- [API Documentation](#api-documentation)
+- [Error Handling](#error-handling)
+- [Validation](#validation)
+- [Authentication](#authentication)
+- [Authorization](#authorization)
+- [Logging](#logging)
+- [Custom Mongoose Plugins](#custom-mongoose-plugins)
+- [Linting](#linting)
+- [Contributing](#contributing)
+
+## Features
+
+- **NoSQL database**: [MongoDB](https://www.mongodb.com) object data modeling using [Mongoose](https://mongoosejs.com)
+- **Authentication and authorization**: using [passport](http://www.passportjs.org)
+- **Validation**: request data validation using [Joi](https://github.com/hapijs/joi)
+- **Logging**: using [winston](https://github.com/winstonjs/winston) and [morgan](https://github.com/expressjs/morgan)
+- **Testing**: unit and integration tests using [Jest](https://jestjs.io)
+- **Error handling**: centralized error handling mechanism
+- **API documentation**: with [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc) and [swagger-ui-express](https://github.com/scottie1984/swagger-ui-express)
+- **Production start**: run with `node src/index.js` (add a process manager like PM2 or systemd if you need clustering)
+- **Dependency management**: with [npm](https://www.npmjs.com)
+- **Environment variables**: using [dotenv](https://github.com/motdotla/dotenv) and [cross-env](https://github.com/kentcdodds/cross-env#readme)
+- **Security**: set security HTTP headers using [helmet](https://helmetjs.github.io)
+- **Santizing**: sanitize request data against xss and query injection
+- **CORS**: Cross-Origin Resource-Sharing enabled using [cors](https://github.com/expressjs/cors)
+- **Compression**: gzip compression with [compression](https://github.com/expressjs/compression)
+- **CI**: continuous integration with [Travis CI](https://travis-ci.org)
+- **Docker support**
+- **Code coverage**: reported to [Coveralls](https://coveralls.io) via GitHub Actions
+- **Code quality**: with [Codacy](https://www.codacy.com)
+- **Git hooks**: with [husky](https://github.com/typicode/husky) and [lint-staged](https://github.com/okonet/lint-staged)
+- **Linting**: with [ESLint](https://eslint.org) and [Prettier](https://prettier.io)
+- **Editor config**: consistent editor configuration using [EditorConfig](https://editorconfig.org)
+
+## Commands
+
+Running locally:
+
+```bash
+npm run dev
+```
+
+Running in production:
+
+```bash
+npm start
+```
+
+Testing:
+
+```bash
+# run all tests
+npm test
+
+# run all tests in watch mode
+npm run test:watch
+
+# run test coverage
+npm run coverage
+```
+
+Docker:
+
+```bash
+# run docker container in development mode
+npm run docker:dev
+
+# run docker container in production mode
+npm run docker:prod
+
+# run all tests in a docker container
+npm run docker:test
+```
+
+Linting:
+
+```bash
+# run ESLint
+npm run lint
+
+# fix ESLint errors
+npm run lint:fix
+
+# run prettier
+npm run prettier
+
+# fix prettier errors
+npm run prettier:fix
+```
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and modify as needed. Required variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| NODE_ENV | Environment (development, test, production) | required |
+| PORT | Server port | 3000 |
+| LOG_LEVEL | Log level (error, warn, info, http, verbose, debug) | info |
+| CORS_ORIGIN | Allowed CORS origins (comma-separated, use * for all) | * |
+| MONGODB_URL | MongoDB connection URL | required |
+| JWT_SECRET | JWT signing secret | required |
+| JWT_ACCESS_EXPIRATION_MINUTES | Access token expiry | 30 |
+| JWT_REFRESH_EXPIRATION_DAYS | Refresh token expiry | 30 |
+| SMTP_* | Email configuration (optional, for verification/reset) | - |
+
+## Project Structure
+
+```
+src\
+ |--config\         # Environment variables and configuration related things
+ |--controllers\    # Route controllers (controller layer)
+ |--docs\           # Swagger files
+ |--middlewares\    # Custom express middlewares
+ |--models\         # Mongoose models (data layer)
+ |--routes\         # Routes
+ |--services\       # Business logic (service layer)
+ |--utils\          # Utility classes and functions
+ |--validations\    # Request data validation schemas
+ |--app.js          # Express app
+ |--index.js        # App entry point
+```
+
+## 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](https://swagger.io/) definitions written as comments in the route files.
+
+### API Endpoints
+
+List of available routes:
+
+**Health** (for load balancers, orchestration):\
+`GET /health` - liveness check\
+`GET /health/ready` - readiness check (includes DB status)
+
+**Auth routes**:\
+`POST /v1/auth/register` - register\
+`POST /v1/auth/login` - login\
+`POST /v1/auth/refresh-tokens` - refresh auth tokens\
+`POST /v1/auth/forgot-password` - send reset password email\
+`POST /v1/auth/reset-password` - reset password\
+`POST /v1/auth/send-verification-email` - send verification email\
+`POST /v1/auth/verify-email` - verify email
+
+**User routes**:\
+`POST /v1/users` - create a user\
+`GET /v1/users` - get all users\
+`GET /v1/users/:userId` - get user\
+`PATCH /v1/users/:userId` - update user\
+`DELETE /v1/users/:userId` - delete user
+
+## 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 catchAsync utility wrapper, which forwards the error.
+
+```javascript
+const catchAsync = require('../utils/catchAsync');
+
+const controller = catchAsync(async (req, res) => {
+  // this error will be forwarded to the error handling middleware
+  throw new Error('Something wrong happened');
+});
+```
+
+The error handling middleware sends an error response, which has the following format:
+
+```json
+{
+  "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 (catchAsync 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:
+
+```javascript
+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](https://joi.dev/). Check the [documentation](https://joi.dev/api/) 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.
+
+```javascript
+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);
+```
+
+## Authentication
+
+To require authentication for certain routes, you can use the `auth` middleware.
+
+```javascript
+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
+
+The `auth` middleware can also be used to require certain rights/permissions to access a route.
+
+```javascript
+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](https://github.com/winstonjs/winston) logging library.
+
+Logging should be done according to the following severity levels (ascending order from most important to least important):
+
+```javascript
+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.\
+In production, ensure your process manager or environment captures stdout/stderr (e.g. Docker, systemd, or a logging service) so logs are stored as needed.
+
+Note: API request information (request url, response code, timestamp, etc.) are also automatically logged (using [morgan](https://github.com/expressjs/morgan)).
+
+## Custom Mongoose Plugins
+
+The app also contains 2 custom mongoose plugins that you can attach to any mongoose model schema. You can find the plugins in `src/models/plugins`.
+
+```javascript
+const mongoose = require('mongoose');
+const { toJSON, paginate } = require('./plugins');
+
+const userSchema = mongoose.Schema(
+  {
+    /* schema definition here */
+  },
+  { timestamps: true }
+);
+
+userSchema.plugin(toJSON);
+userSchema.plugin(paginate);
+
+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
+
+### paginate
+
+The paginate plugin adds the `paginate` static method to the mongoose schema.
+
+Adding this plugin to the `User` model schema will allow you to do the following:
+
+```javascript
+const queryUsers = async (filter, options) => {
+  const users = await User.paginate(filter, options);
+  return users;
+};
+```
+
+The `filter` param is a regular mongo filter.
+
+The `options` param can have the following (optional) fields:
+
+```javascript
+const options = {
+  sortBy: 'name:desc', // sort order
+  limit: 5, // maximum results per page
+  page: 2, // page number
+};
+```
+
+The plugin also supports sorting by multiple criteria (separated by a comma): `sortBy: name:desc,role:asc`
+
+The `paginate` method returns a Promise, which fulfills with an object having the following properties:
+
+```json
+{
+  "results": [],
+  "page": 2,
+  "limit": 5,
+  "totalPages": 10,
+  "totalResults": 48
+}
+```
+
+## Linting
+
+Linting is done using [ESLint](https://eslint.org/) and [Prettier](https://prettier.io).
+
+In this app, ESLint is configured to follow the [Airbnb JavaScript style guide](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb-base) with some modifications. It also extends [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier) to turn off all rules that are unnecessary or might conflict with Prettier.
+
+To modify the ESLint configuration, update the `.eslintrc.json` file. To modify the Prettier configuration, update the `.prettierrc.json` file.
+
+To prevent a certain file or directory from being linted, add it to `.eslintignore` and `.prettierignore`.
+
+To maintain a consistent coding style across different IDEs, the project contains `.editorconfig`
+
+## Contributing
+
+Contributions are more than welcome! Please check out the [contributing guide](CONTRIBUTING.md).
+
+## Inspirations
+
+- [hagopj13/node-express-boilerplate](https://github.com/hagopj13/node-express-boilerplate) – boilerplate this project is based on
+- [danielfsousa/express-rest-es2017-boilerplate](https://github.com/danielfsousa/express-rest-es2017-boilerplate)
+- [madhums/node-express-mongoose](https://github.com/madhums/node-express-mongoose)
+- [kunalkapadia/express-mongoose-es6-rest-api](https://github.com/kunalkapadia/express-mongoose-es6-rest-api)
+
+## License
+
+[MIT](LICENSE)

package/bin/createNodejsApp.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'coverage', 'bin']);
+const EXCLUDE_FILES = new Set(['.env']);
+
+function copyRecursive(src, dest, templateRoot, excludeDirName) {
+  const stat = fs.statSync(src);
+  const basename = path.basename(src);
+
+  if (EXCLUDE_DIRS.has(basename)) return;
+  if (excludeDirName && basename === excludeDirName) return;
+  if (basename === '.env' || (basename.startsWith('.env') && !basename.endsWith('.example'))) return;
+
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, name), path.join(dest, name), templateRoot, excludeDirName);
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function main() {
+  const projectName = process.argv[2];
+  if (!projectName) {
+    console.error('Usage: npx nodejs-express-starter <project-name>');
+    console.error('Example: npx nodejs-express-starter my-api');
+    process.exit(1);
+  }
+
+  const templateRoot = path.resolve(__dirname, '..');
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    console.error(`Error: "${projectName}" already exists in this directory.`);
+    process.exit(1);
+  }
+
+  console.log(`Creating a new Express app in ./${projectName}...`);
+
+  try {
+    fs.mkdirSync(targetDir, { recursive: true });
+  } catch (err) {
+    if (err.code === 'EACCES') {
+      console.error(`Error: Permission denied creating folder at ${targetDir}`);
+      console.error('Run the command from a directory you can write to (e.g. your home or Desktop):');
+      console.error(`  cd ~/Desktop && npx nodejs-express-starter ${projectName}`);
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exit(1);
+  }
+
+  const entries = fs.readdirSync(templateRoot, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === 'bin') continue;
+    if (entry.name === projectName) continue; // avoid copying a same-named folder (e.g. from a previous run) into itself
+    const srcPath = path.join(templateRoot, entry.name);
+    const destPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      if (!EXCLUDE_DIRS.has(entry.name)) {
+        copyRecursive(srcPath, destPath, templateRoot, projectName);
+      }
+    } else {
+      const skip =
+        EXCLUDE_FILES.has(entry.name) ||
+        entry.name === '.env' ||
+        (entry.name.startsWith('.env') && !entry.name.endsWith('.example'));
+      if (!skip) fs.copyFileSync(srcPath, destPath);
+    }
+  }
+
+  // Copy .env.example to .env in the new project
+  const envExample = path.join(templateRoot, '.env.example');
+  if (fs.existsSync(envExample)) {
+    fs.copyFileSync(envExample, path.join(targetDir, '.env'));
+  }
+
+  console.log('Installing dependencies...');
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+const install = spawnSync(npmCmd, ['install'], {
+  cwd: targetDir,
+  stdio: 'inherit',
+});
+  if (install.status !== 0) {
+    console.error('npm install failed. You can run it manually inside the project.');
+    process.exit(install.status || 1);
+  }
+
+  console.log('');
+  console.log(`Done! Your app is in ./${projectName}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log(`  cd ${projectName}`);
+  console.log('  cp .env.example .env   # then edit .env with your settings');
+  console.log('  npm run dev            # start development server');
+  console.log('');
+}
+
+main();

package/docker-compose.dev.yml

@@ -0,0 +1,4 @@
+services:
+  node-app:
+    container_name: node-app-dev
+    command: npm run dev