Mongoose Node.js Express TypeScript application boilerplate with best practices for API development.

The main purpose of this repository is to show a good end-to-end project setup and workflow for writing a Mongoose Node.js Express code in TypeScript complete with middleware, models, routes, and types.

This example comes with a complete REST API to handle Authentication and CRUD features on Users and their corresponding Profile. You may view the API documentation on the Wiki.

Why TypeScript?

While it's true that developing applications on an Untyped language such as JavaScript, is easier to learn and is faster to develop, it will undeniably get harder and harder to grasp as the application grows in scale. This in turn, leads to more run-time errors consuming more development hours, as the team gets accustomed to the growing codebase. And this is what this boilerplate hopes to achieve. By using the TypeScript standard, you'll have better team and code stability with Interface Oriented Development, leading to better standardized codes. TypeScript allows developers to focus more on exposed Interfaces or API, rather than having to know all the code by heart. This makes the codebase easier to maintain with big teams, especially if those teams are composed of developers of different skill levels.

Prerequisites

To build and run this app locally you will need a few things:

• Install Node.js
• Install VS Code

Getting started

• Clone the repository

git clone --depth=1 https://github.com/polcham/mongoose-express-ts.git <project_name>

• Install dependencies

cd <project_name>
npm install
npm run tsc

• Build and run the project with auto reload (nodemon)

npm run server

• Build and run the project

npm run start

Finally, navigate to http://localhost:5000/ and you should see the API running!

Project Structure

The most obvious difference in a TypeScript + Node project is the folder structure. In a TypeScript project, it's best to have separate source and distributable files. TypeScript (.ts) files live in your src folder and after compilation are output as JavaScript (.js) in the dist folder.

The full folder structure of this app is explained below:

Note! Make sure you have already built the app using npm run start

Configuring TypeScript compilation

TypeScript uses the file tsconfig.json to adjust project compile options.Let's dissect this project's tsconfig.json, starting with the compilerOptions which details how your project is compiled.

"compilerOptions": {
    "module": "commonjs",
    "esModuleInterop": true,
    "target": "es6",
    "noImplicitAny": true,
    "moduleResolution": "node",
    "sourceMap": true,
    "outDir": "dist",
    "baseUrl": ".",
    "paths": {
      "*": ["node_modules/*", "src/types/*"]
    }
  }

The rest of the file define the TypeScript project context.The project context is basically a set of options that determine which files are compiled when the compiler is invoked with a specific tsconfig.json.In this case, we use the following to define our project context:

"include": [
        "src/**/*"
    ]

include takes an array of glob patterns of files to include in the compilation. This project is fairly simple and all of our .ts files are under the src folder.

Running the build

All the different build steps are orchestrated via npm scripts.Npm scripts basically allow us to call (and chain) terminal commands via npm.This is nice because most JavaScript tools have easy to use command line utilities allowing us to not need grunt or gulp to manage our builds.If you open package.json, you will see a scripts section with all the different scripts you can call.To call a script, simply run npm run <script-name> from the command line.You'll notice that npm scripts can call each other which makes it easy to compose complex builds out of simple individual build scripts.Below is a list of all the scripts this template has available:

Since we're developing with TypeScript, it is important for the codes to be transpiled first to JavaScript before running the node server. It is best to deploy the app using: npm run server or npm run start command.

VSCode Extensions

To enhance your development experience while working in VSCode, I provided you with a list of suggested extensions while working on this project:

• REST Client
• Version Lens
• Prettier - Code formatter
• Bracket Pair Colorizer
• index-rainbow
• Material Icon Theme

Dependencies

Dependencies are managed through package.json.In that file you'll find two sections:

dependencies

devDependencies

Since TypeScript is used, dependencies should be accompanied with their corresponding DefinitelyTyped @types package.

To install or update these dependencies you can use npm install or npm update.