Express Typescript Boilerplate

A delightful way to building a RESTful API Services with beautiful code written in TypeScript. An Node.js Web-Service boilerplate/skeleton/starter-kit featuring Inspired by the awesome framework laravel in PHP and of the repositories from pleerock. TypeScript, Express, Winston, Microframework, TypeDI, TypeORM, TsLint, @types, Jest, Swagger, validatejs, by w3tech

Why

Our main goal with this project is a feature complete server application. We like you to be focused on your business and not spending hours in project configuration.

Try it!! We are happy to hear your feedback or any kind of new features.

Features

• Beautiful Code thanks to the awesome annotations of the libraries from pleerock.
• Easy API Testing with included e2e testing.
• Dependency Injection done with the nice framework from TypeDI.
• Simplified Database Query with the ORM TypeOrm.
• Clear Structure with different layers such as controllers, services, repositories, models, middlewares...
• Easy Exception Handling thanks to routing-controllers.
• Smart Validation thanks to class-validator with some nice annotations.
• Custom Validators to validate your request even better and stricter. custom-validation-classes.
• API Documentation thanks to swagger.
• API Monitoring thanks to express-status-monitor.
• Integrated Testing Tool thanks to Jest.
• Basic Security Features thanks to Helmet.
• Easy event dispatching thanks to event-dispatch.
• Fast Database Building with simple migration from TypeOrm.

Comming soon

• Easy Data Seeding with our own factories.
• Custom Commands are also available in our setup and really easy to use or even extend.
• Scaffolding Commands will speed up your development tremendously as you should focus on business code and not scaffolding.

Table of Contents

• Getting Started
• Scripts and Tasks
• Debugger in VSCode
• API Routes
• Project Structure
• Logging
• Event Dispatching
• Further Documentations
• Related Projects
• License

Getting Started

Step 1: Set up the Development Environment

You need to set up your development environment before you can do anything.

Install Node.js and NPM

• on OSX use homebrew brew install node
• on Windows use chocolatey choco install nodejs

Install yarn globally

npm install yarn -g

Install a MySQL database.

If you work with a mac, we recommend to use homebrew for the installation.

Step 2: Create new Project

Fork or download this project. Configure your package.json for your new project.

Then copy the .env.example file and rename it to .env. In this file you have to add your database connection information.

Create a new database with the name you have in your .env-file.

Then setup your application environment.

npm start setup

This installs all dependencies with yarn. After that it migrates the database and seeds some test data into it. So after that your development environment is ready to use.

Step 3: Serve your App

Go to the project dir and start your app with this npm script.

npm start serve

This starts a local server using nodemon, which will watch for any file changes and will restart the sever according to these changes. The server address will be displayed to you as http://0.0.0.0:3000.

Scripts and Tasks

All script are defined in the package.json file, but the most important ones are listed here.

Install

• Install all dependencies with yarn install

Linting

• Run code quality analysis using npm start lint. This runs tslint.
• There is also a vscode task for this called lint.

Tests

• Run the unit tests using npm start test (There is also a vscode task for this called test).
• Run the e2e tests using npm start test:e2e and don't forget to start your application and your Auth0 Mock Server.

Running in dev mode

• Run npm start serve to start nodemon with ts-node, to serve the app.
• The server address will be displayed to you as http://0.0.0.0:3000

Building the project and run it

• Run npm start build to generated all JavaScript files from the TypeScript sources (There is also a vscode task for this called build).
• To start the builded app located in dist use npm start.

Database

• Run ./node_modules/.bin/typeorm create -n <migration-file-name> to create a new migration file.
• To migrate your database run npm start migrate.
• To revert your latest migration run npm start migrate.revert.

Debugger in VSCode

Just set a breakpoint and hit F5 in your Visual Studio Code.

API Routes

The route prefix is /api by default, but you can change this in the .env file. The swagger and the monitor route can be altered in the .env file.

Route	Description
/api	Shows us the name, description and the version of the package.json
/swagger	This is the Swagger UI with our API documentation
/monitor	Shows a small monitor page for the server

Project Structure

Name	Description
.vscode/	VSCode tasks, launch configuration and some other settings
dist/	Compiled source files will be placed here
src/	Source files
src/api/controllers/	REST API Controllers
src/api/errors/	Custom HttpErrors like 404 NotFound
src/api/interceptors/	Interceptors are used to change or replace the data returned to the client.
src/api/middlewares/	Express Middlewares like helmet security features
src/api/models/	Bookshelf Models
src/api/repositories/	Repository / DB layer
src/api/services/	Service layer
src/api/subscribers/	Event subscribers
src/api/validators/	Custom validators, which can be used in the request classes
src/api/ swagger.json	Swagger documentation
src/console/	Command line scripts
src/core/	The core features like logger and env variables
src/public/	Static assets (fonts, css, js, img).
src/types/ *.d.ts	Custom type definitions and files that aren't on DefinitelyTyped
test	Tests
test/e2e/ *.test.ts	End-2-End tests (like e2e)
test/unit/ *.test.ts	Unit tests
.env.example	Environment configurations

Logging

Our logger is winston. To log http request we use the express middleware morgan. We created a simple annotation to inject the logger in your service (see example below).

import { Logger, ILogger } from '../../decorators/Logger';

@Service()
export class UserService {

    constructor(
        @Logger(__filename) private log: ILogger
    ) { }

    ...

Event Dispatching

Our we use this awesome repository event-dispatch for event dispatching. We created a simple annotation to inject the EventDispatcher in your service (see example below). All events are listed in the events.ts file.

import { events } from '../subscribers/events';
import { EventDispatcher, IEventDispatcher } from '../../decorators/EventDispatcher';

@Service()
export class UserService {

    constructor(
        @EventDispatcher() private eventDispatcher: IEventDispatcher
    ) { }

    public async create(user: User): Promise<User> {
        ...
        this.eventDispatcher.dispatch(events.user.created, newUser);
        ...
    }

Further Documentations

Name & Link	Description
Express	Express is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications.
Microframework	Microframework is a simple tool that allows you to execute your modules in a proper order, helping you to organize bootstrap code in your application.
TypeDI	Dependency Injection for TypeScript.
routing-controllers	Create structured, declarative and beautifully organized class-based controllers with heavy decorators usage in Express / Koa using TypeScript and Routing Controllers Framework.
TypeORM	TypeORM is highly influenced by other ORMs, such as Hibernate, Doctrine and Entity Framework.
class-validator	Validation made easy using TypeScript decorators.
class-transformer	Proper decorator-based transformation / serialization / deserialization of plain javascript objects to class constructors
event-dispatcher	Dispatching and listening for application events in Typescript
Helmet	Helmet helps you secure your Express apps by setting various HTTP headers. It’s not a silver bullet, but it can help!
Auth0 API Documentation	Authentification service
Jest	Delightful JavaScript Testing Library for unit and e2e tests
swagger Documentation	API Tool to describe and document your api.

Related Projects

• Microsoft/TypeScript-Node-Starter - A starter template for TypeScript and Node with a detailed README describing how to use the two together.
• express-graphql-typescript-boilerplate - A starter kit for building amazing GraphQL API's with TypeScript and express by @w3tecch
• aurelia-typescript-boilerplate - An Aurelia starter kit with TypeScript
• Auth0 Mock Server - Useful for e2e testing or faking an oAuth server

License

MIT

---

Made with ♥ by w3tech (w3tech), Gery Hirschfeld (@GeryHirschfeld1) and contributors