Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

express-typeorm-rest-boilerplate

bymi1596MIT0.4.3TypeScript support: included

Boilerplate code to get started with building RESTful API Services

express-typeorm-rest-boilerplate, javascript, typescript, nodejs, express, typeorm, typedi, boilerplate, api, rest, jest, validation, mongodb

readme

Express TypeORM REST API Boilerplate

Quality Gate Status travis stackshare npm

Awesome boilerplate code to get started with building RESTful API Services!
Typescript with NodeJS and Express as well as MongoDB integration with TypeORM
JSON Web Tokens (JWT) based User Authentication,

TypeDI dependency injections, testing with Jest, and a bunch more.
Made with ❤️ by Brian Min


Why?

The main reason I decided to start this project is to provide a boilerplate for the NodeJS, Express, Typescript, TypeORM, MongoDB stack. Also with TypeORM, this boilerplate code can easily be modified to use MySQL, PostGreSQL, and many more. Tedious setting up of project structure, logging, testing, env and eslint is all done for you! Now you can focus on actually implementing the core functionalities and not spending hours setting up and configuring your project.

Try it out and feel free to raise any issues or create pull requests if you would like to contribute!

Features

  • JWT based user authentication with jsonwebtoken and express-jwt.
  • Dependency Injection with TypeDI.
  • ORM with support for many databases (MySQL, PostgreSQL, MariaDB, SQLite, MongoDB, and more) with TypeORM.
  • Clear and organised structure with different layers such as entities, services, middlewares, loaders, etc.
  • Validation thanks to class-validator.
  • Unit and Integration Testing with Jest.
  • Security Features with Helmet.
  • Role-based access control using a custom-built middleware.
  • Simple Data Seeding with custom-built factories and Faker.js.
  • Code generator for entity, service, route, factory, seed, test with a custom-built generator script and CLI tool Commander.

Getting Started

Step 1: Set up the Development Environment

Install Node.js and NPM

Install a MongoDB server or use MongoDB Atlas

Step 2: Create a new project

Fork or download this project and modify package.json for your new project.

Make a copy of the .env.example file and rename it to .env.

Create a new database and add the connection string in the .env file.

Install the required packages.

npm install

This installs all the dependencies with NPM.

Now your development environment should be ready to use!

Step 3: Serve your application

Go to the root directory and start your app with this npm script.

npm run dev

This starts a local server using nodemon and ts-node. The server base endpoint will be http://127.0.0.1:3000 where 3000 is the PORT variable you set in the .env file.

Scripts and Tasks

Install

  • Install all dependencies with npm install

Linting

  • Run code syntax and format checking using npm run lint which runs eslint.
  • Automatically fix lint errors with npm run lint:fix.

Running MongoDB locally

For this step you need to install MongoDB Server

  • Run npm run mongodb to start a local MongoDB server with it's data stored in .mongodb in the root directory.
  • This is very useful for unit / integration testing.
  • It's always a good idea to use a separate database for testing.

Tests

  • Run unit tests using npm run test (for Windows users) or npm run test:unix (for Mac and Linux users).

Running the app in development

  • Run npm run dev to start nodemon with ts-node.
  • The server base endpoint will be http://127.0.0.1:3000 where 3000 is the PORT variable you set in the .env file.

Building and running the app in production

  • Run npm run build to compile all the Typescript sources and generate JavaScript files.
  • To start the built app located in build use npm start.

API Routes

The route prefix is /api by default, but you can change this in the .env file.

Route Description
/api Base endpoint
/api/auth/login Auth - login endpoint
/api/auth/register Auth - register endpoint
/api/user Example entity endpoint - returns all users
/api/user/current Example entity endpoint - returns current logged in user
/api/company Example entity endpoint - returns all companies
/api/company/:id Example entity endpoint - returns a company by id
/api/jobApplication Example entity endpoint - returns all job applications
... ...

Project Structure

Name Description
.mongodb/ Local MongoDB server data
build/ Compiled source files will be placed here
commands/ Custom CLI command tools used with npm scripts
src/ Source files
src/api/middlewares/ Custom middlewares
src/api/entities/ TypeORM Entities (Database models)
src/api/services/ Service layer
src/config/ The configuration file which loads env variables
src/database/factories Factories generate entities with mock data
src/database/seeds Seeds use factories to save mock data in the database
src/loaders/ Loader is where the app is configured and database is loaded
src/types/ *.d.ts Custom type definitions
test *.spec.ts Unit and integration tests
.env.example Environment configurations

Logging

For logging we use winston.

License

MIT

changelog

0.4.3 (2021-11-17)

Bug Fixes

  • CRUD: fix update function (a95ad55)
  • express: replace map with foreach (3338f60)

0.4.2 (2020-10-16)

Bug Fixes

  • CRUD: fix update CRUD method (31a79a4)
  • jobApplicationRoute: fix /:id endpoint by adding object permission (446f31c)

0.4.1 (2020-10-11)

Bug Fixes

  • CRUD: make id strictly type string (2378d4a)
  • routes: add checkRole('staff') middleware for delete,post,put endpoints (b3a98bf)
  • routes: refactor delete route status code to 204 (56bdf83)
  • UserFactory: add user role (6a026f7)
  • UserService: refactor id param to be strictly of type string (fee0993)

0.4.0 (2020-10-10)

Bug Fixes

  • app: separate app and server for e2e testing (a6d2cbb)
  • ErrorHandler: fix imports and add error handler in express loader (5571f23)
  • expressLoader: add celebrate validation error handler (f8421bc)
  • JobApplicationFactory: fix ObjectID bug with typeorm (8878c14)
  • services: add undefined check for JobApplication service (604c195)

Features

  • ErrorHandler: add custom error handler with status code (d742c3e)

0.3.0 (2020-10-06)

Bug Fixes

  • CRUD: fix update bug with fill (d9a1658)
  • Generator: add missing export route code (b6dede6)
  • jest: jest run in series instead of parallel (57d0c6f)
  • JobApplication: remove default appliedDate causing bug in update (45ab09e)
  • ormconfig.js: fix TS_NODE env not set (7e615d6)

Features

  • CRUD: add fillObjectIdField function (319588c)
  • factories: add JobApplication factory (510b0a5)
  • JobApplication: add JobApplication entity (a3b2d86)
  • jobApplicationRoute: add jobApplication endpoints (41b4dcb)
  • JobApplicationService: add update function (0bebf19)
  • seeds: add JobApplication seed (cc72beb)
  • services: add JobApplication service (80afac2)

0.2.0 (2020-10-06)

Bug Fixes

  • companyroute: refactor response json format (d9dd2bd)
  • CRUD: make identifier optional in create function (7b6e584)
  • generator: refactor route code generator response json format (5026a5f)
  • middlewares: add checkRole to middleware index (f9813b6)
  • middlewares: refactor attachUser to use UserService findOne (9249b5a)

Features

  • middlewares: add checkRole middleware (0f0bd5b)
  • services: add UserService find and findOne which removes password field (994c370)
  • UserEntity: add role (88ad053)
  • userRoute: add / and /current endpoints to user route (42324c5)

0.1.1 (2020-10-05)

Bug Fixes

  • build: fix running compiled app by adding ormconfig for dist (811423f)
  • package.json: fix test env variable for ormconfig in build (308fd37)

0.1.0 (2020-10-05)

Bug Fixes

  • .releaserc: fix semantic-release branch was set to master instead of main (5a752c5)

Features

  • package.json: add husky and commitlint (7946e6a)

0.0.4 (2020-10-05)

Features

  • commands: add seed command (8d282da)
  • companyRoute: add delete and update endpoints (70b3d93)
  • Generator: add generate command (e00b2b5)

0.0.3 (2020-10-03)

Bug Fixes

  • database: rename case-sensitive (223a854)

Features

  • CRUD: add and integrate generic CRUD service (e6233b3)
  • CRUD.spec.ts: add CRUD service integration test (8848538)
  • EntitySeed: add generic entity seeder (0429230)
  • issues: update issue templates (7c26510)
  • test: update company and user tests (32b2b8a)
  • types: add generic factory type (5242ff8)

0.0.2 (2020-10-02)

Bug Fixes

  • config: remove .env check (bd47140)
  • tests: fix userService jest mock logger path (6fced9f)
  • update travis config and package.json for ci (86795fc)

Features

  • .travis.yml: add travis config (52c35b9)
  • CompanyFactory: add company factory (d2fa5f2)
  • CompanySeed: add company seeder (38c9636)
  • entities: add Company entity (87c06a3)
  • routes: add company route (d213994)
  • services: add company service (42c4b46)
  • test: add companyService integration test (e72c56d)
  • types: add ICompanyInputDTO interface (396fabf)

0.0.1 (2020-10-01)

Features