Skip to content

Commit 1282a94

Browse files
author
hirsch88
committedNov 19, 2017
Starts with documentation
·
3.2.03.0.0-beta
1 parent dd412a2 commit 1282a94

File tree

13 files changed

+209
-96
lines changed

13 files changed

+209
-96
lines changed
 

‎README.new.md

+197
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# Express Typescript Boilerplate
2+
3+
[![Dependency Status](https://david-dm.org/w3tecch/express-typescript-boilerplate/status.svg?style=flat)](https://david-dm.org/w3tecch/express-typescript-boilerplate)
4+
[![Build Status](https://travis-ci.org/w3tecch/express-typescript-boilerplate.svg?branch=master)](https://travis-ci.org/w3tecch/express-typescript-boilerplate)
5+
[![Build status](https://ci.appveyor.com/api/projects/status/f8e7jdm8v58hcwpq/branch/master?svg=true&passingText=Windows%20passing&pendingText=Windows%20pending&failingText=Windows%20failing)](https://ci.appveyor.com/project/dweber019/express-typescript-boilerplate/branch/master)
6+
7+
> A delightful way to building a RESTful API with NodeJs & TypeScript.
8+
> An Node.js Web-Serice boilerplate/skeleton/starter-kit featuring
9+
[TypeScript](https://www.typescriptlang.org/),
10+
[Express](https://expressjs.com/),
11+
[Winston](https://github.com/winstonjs/winston),
12+
[Microframework](https://github.com/pleerock/microframework),
13+
[TypeDI](https://github.com/pleerock/typedi),
14+
[TypeORM](https://github.com/typeorm/typeorm),
15+
[TsLint](http://palantir.github.io/tslint/),
16+
[@types](https://www.npmjs.com/~types),
17+
[Jest](https://facebook.github.io/jest/),
18+
[Swagger](http://swagger.io/),
19+
[validatejs](https://validatejs.org/),
20+
by [w3tech](https://github.com/w3tecch)
21+
22+
## Why
23+
24+
Our main goal with this project is a feature complete server application.
25+
We like you to be focused on your business and not spending hours in project configuration.
26+
27+
Try it!! We are happy to hear your feedback or any kind of new features.
28+
29+
## Features
30+
31+
- **Beautiful Code** thanks to the awesome annotations of the libraries from [pleerock](https://github.com/pleerock).
32+
- **Easy API Testing** with included e2e testing.
33+
- **Dependency Injection** done with the nice framework from [TypeDI](https://github.com/pleerock/typedi).
34+
- **Simplified Database Query** with the ORM [TypeOrm](https://github.com/typeorm/typeorm).
35+
- **Clear Structure** with different layers such as controllers, services, repositories, models, middlewares...
36+
- **Easy Exception Handling** thanks to [routing-controllers](https://github.com/pleerock/routing-controllers).
37+
- **Smart Validation** thanks to [class-validator](https://github.com/pleerock/class-validator) with some nice annotations.
38+
- **Custom Validators** to validate your request even better and stricter. [custom-validation-classes](https://github.com/pleerock/class-validator#custom-validation-classes)
39+
- **API Documentation** thanks to [swagger](http://swagger.io/).
40+
- **API Monitoring** thanks to [express-status-monitor](https://github.com/RafalWilinski/express-status-monitor).
41+
- **Integrated Testing Tool** thanks to [Wallaby.js](https://wallabyjs.com/)
42+
- **Basic Security Features** thanks to [Helmet](https://helmetjs.github.io/)
43+
44+
### Comming soon
45+
46+
- **Fast Database Building** with simple migration and seeding from [Knex](http://knexjs.org/).
47+
- **Easy Data Seeding** with our own factories.
48+
- **Custom Commands** are also available in our setup and really easy to use or even extend.
49+
- **Scaffolding Commands** will speed up your development tremendously as you should focus on business code and not scaffolding.
50+
51+
## Getting Started
52+
53+
### Step 1: Set up the Development Environment
54+
55+
You need to set up your development environment before you can do anything.
56+
57+
Install [Node.js and NPM](https://nodejs.org/en/download/)
58+
59+
- on OSX use [homebrew](http://brew.sh) `brew install node`
60+
- on Windows use [chocolatey](https://chocolatey.org/) `choco install nodejs`
61+
62+
Install yarn globally
63+
64+
```bash
65+
npm install yarn -g
66+
```
67+
68+
Install a MySQL database.
69+
70+
> If you work with a mac, we recommend to use homebrew for the installation.
71+
72+
### Step 2: Create new Project
73+
74+
Fork or download this project. Configure your package.json for your new project.
75+
76+
Then copy the `.env.example` file and rename it to `.env`. In this file you have to add your database connection information.
77+
78+
Create a new database with the name you have in your `.env`-file.
79+
80+
Then setup your application environment.
81+
82+
```bash
83+
nps setup
84+
```
85+
86+
> 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.
87+
88+
### Step 3: Serve your App
89+
90+
Go to the project dir and start your app with this npm script.
91+
92+
```bash
93+
nps serve
94+
```
95+
96+
> This starts a local server using `nodemon`, which will watch for any file changes and will restart the sever according to these changes.
97+
> The server address will be displayed to you as `http://0.0.0.0:3000`.
98+
99+
## Scripts / Tasks
100+
101+
All script are defined in the package.json file, but the most important ones are listed here.
102+
103+
### Install
104+
105+
- Install all dependencies with `yarn install`
106+
107+
### Linting
108+
109+
- Run code quality analysis using `nps lint`. This runs tslint.
110+
- There is also a vscode task for this called `lint`.
111+
112+
### Tests
113+
114+
- Run the unit tests using `nps test` (There is also a vscode task for this called `test`).
115+
- Run the e2e tests using `nps test:e2e` and don't forget to start your application and your [Auth0 Mock Server](https://github.com/hirsch88/auth0-mock-server).
116+
117+
### Running in dev mode
118+
119+
- Run `nps serve` to start nodemon with ts-node, to serve the app.
120+
- The server address will be displayed to you as `http://0.0.0.0:3000`
121+
122+
### Building the project and run it
123+
124+
- Run `nps build` to generated all JavaScript files from the TypeScript sources (There is also a vscode task for this called `build`).
125+
- To start the builded app located in `dist` use `npm start`.
126+
127+
## Using the debugger in VS Code
128+
129+
Just set a breakpoint and hit `F5` in your Visual Studio Code.
130+
131+
## API Routes
132+
133+
The route prefix is `/api` by default, but you can change this in the .env file.
134+
The swagger and the monitor route can be altered in the `.env` file.
135+
136+
| Route | Description |
137+
| ------------ | ----------- |
138+
| **/api** | Shows us the name, description and the version of the package.json |
139+
| **/swagger** | This is the Swagger UI with our API documentation |
140+
| **/monitor** | Shows a small monitor page for the server |
141+
142+
## Project Structure
143+
144+
| Name | Description |
145+
| ----------------------------- | ----------- |
146+
| **.vscode/** | VSCode tasks, launch configuration and some other settings |
147+
| **dist/** | Compiled source files will be placed here |
148+
| **src/** | Source files |
149+
| **src/api/controllers/** | REST API Controllers |
150+
| **src/api/errors/** | Custom HttpErrors like 404 NotFound |
151+
| **src/api/interceptors/** | Interceptors are used to change or replace the data returned to the client. |
152+
| **src/api/middlewares/** | Express Middlewares like helmet security features |
153+
| **src/api/models/** | Bookshelf Models |
154+
| **src/api/repositories/** | Repository / DB layer |
155+
| **src/api/services/** | Service layer |
156+
| **src/api/validators/** | Custom validators, which can be used in the request classes |
157+
| **src/api/** swagger.json | Swagger documentation |
158+
| **src/console/** | Command line scripts |
159+
| **src/constants/** | Global Constants |
160+
| **src/core/** | The core features like logger and env variables |
161+
| **src/public/** | Static assets (fonts, css, js, img). |
162+
| **src/types/** *.d.ts | Custom type definitions and files that aren't on DefinitelyTyped |
163+
| **test** | Tests |
164+
| **test/e2e/** *.test.ts | End-2-End tests (like e2e) |
165+
| **test/unit/** *.test.ts | Unit tests |
166+
| .env.example | Environment configurations |
167+
168+
## Related Projects
169+
170+
- [Microsoft/TypeScript-Node-Starter](https://github.com/Microsoft/TypeScript-Node-Starter) - A starter template for TypeScript and Node with a detailed README describing how to use the two together.
171+
- [express-graphql-typescript-boilerplate](https://github.com/w3tecch/express-graphql-typescript-boilerplate) - A starter kit for building amazing GraphQL API's with TypeScript and express by @w3tecch
172+
- [aurelia-typescript-boilerplate](https://github.com/w3tecch/aurelia-typescript-boilerplate) - An Aurelia starter kit with TypeScript
173+
- [Auth0 Mock Server](https://github.com/hirsch88/auth0-mock-server) - Useful for e2e testing or faking an oAuth server
174+
175+
## Documentations of our main dependencies
176+
177+
| Name & Link | Description |
178+
| --------------------------------- | --------------------------------- |
179+
| [Express](https://expressjs.com/) | Express is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications. |
180+
| [Microframework](https://github.com/pleerock/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. |
181+
| [TypeDI](https://github.com/pleerock/typedi) | Dependency Injection for TypeScript. |
182+
| [routing-controllers](https://github.com/pleerock/routing-controllers) | Create structured, declarative and beautifully organized class-based controllers with heavy decorators usage in Express / Koa using TypeScript and Routing Controllers Framework. |
183+
| [TypeORM](http://typeorm.io/#/) | TypeORM is highly influenced by other ORMs, such as Hibernate, Doctrine and Entity Framework. |
184+
| [class-validator](https://github.com/pleerock/class-validator) | Validation made easy using TypeScript decorators. |
185+
| [class-transformer](https://github.com/pleerock/class-transformer) | Proper decorator-based transformation / serialization / deserialization of plain javascript objects to class constructors |
186+
| [event-dispatcher](https://github.com/pleerock/event-dispatch) | Dispatching and listening for application events in Typescript |
187+
| [Helmet](https://helmetjs.github.io/) | Helmet helps you secure your Express apps by setting various HTTP headers. It’s not a silver bullet, but it can help! |
188+
| [Auth0 API Documentation](https://auth0.com/docs/api/management/v2) | Authentification service |
189+
| [Jest](http://facebook.github.io/jest/) | Delightful JavaScript Testing Library for unit and e2e tests |
190+
| [swagger Documentation](http://swagger.io/) | API Tool to describe and document your api. |
191+
192+
## License
193+
194+
[MIT](/LICENSE)
195+
196+
---
197+
Made with ♥ by w3tech ([w3tech](https://github.com/w3tecch)), Gery Hirschfeld ([@GeryHirschfeld1](https://twitter.com/GeryHirschfeld1)) and [contributors](https://github.com/w3tecch/express-typescript-boilerplate/graphs/contributors)

‎README.md ‎README.old.md

File renamed without changes.

‎src/api/interceptors/.gitkeep

Whitespace-only changes.

‎src/api/validators/.gitkeep

Whitespace-only changes.

‎src/auth/AuthService.ts

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import * as request from 'request';
2+
import * as express from 'express';
23
import { Service } from 'typedi';
34
import { env } from '../core/env';
45
import { ITokenInfo } from './ITokenInfo';
@@ -7,7 +8,7 @@ import { ITokenInfo } from './ITokenInfo';
78
@Service()
89
export class AuthService {
910

10-
public parseTokenFromRequest(req: myExpress.Request): string | null {
11+
public parseTokenFromRequest(req: express.Request): string | null {
1112
const authorization = req.header('authorization');
1213

1314
// Retrieve the token form the Authorization header

‎src/constants/.gitkeep

Whitespace-only changes.

‎src/core/Log.ts

-5
Original file line numberDiff line numberDiff line change
@@ -29,16 +29,11 @@ export class Log {
2929
}
3030

3131
private scope: string;
32-
private adapter: interfaces.LoggerAdapter;
3332

3433
constructor(scope?: string) {
3534
this.scope = Log.parsePathToScope((scope) ? scope : Log.DEFAULT_SCOPE);
3635
}
3736

38-
public getAdapter(): interfaces.LoggerAdapter {
39-
return this.adapter;
40-
}
41-
4237
public debug(message: string, ...args: any[]): void {
4338
this.log('debug', message, args);
4439
}

‎src/core/env.ts

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ export const env = {
1111
description: pkg.description,
1212
route: getOsEnv('APP_ROUTE'),
1313
routePrefix: getOsEnv('APP_ROUTE_PREFIX'),
14-
port: normalizePort(process.env.PORT || '3000')
14+
port: normalizePort(process.env.PORT || '3000'),
15+
banner: toBool(getOsEnv('APP_BANNER'))
1516
},
1617
log: {
1718
level: getOsEnv('LOG_LEVEL'),

‎src/loaders/expressLoader.ts

+5-4
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,15 @@ export const expressLoader: MicroframeworkLoader = (settings: MicroframeworkSett
1616
*/
1717
const expressApp = createExpressServer({
1818
cors: true,
19+
classTransformer: true,
1920
routePrefix: env.app.routePrefix,
2021
/**
21-
* TODO: We can add options about how routing-controllers should configure itself.
22+
* We can add options about how routing-controllers should configure itself.
2223
* Here we specify what controllers should be registered in our express server.
2324
*/
24-
controllers: [path.join(__dirname, '..', 'api/controllers/*{.js,.ts}')],
25-
middlewares: [path.join(__dirname, '..', 'api/middlewares/*{.js,.ts}')],
26-
interceptors: [path.join(__dirname, '..', 'api/interceptors/*{.js,.ts}')],
25+
controllers: [path.join(__dirname, '..', 'api/**/*Controller{.js,.ts}')],
26+
middlewares: [path.join(__dirname, '..', 'api/**/*Middleware{.js,.ts}')],
27+
interceptors: [path.join(__dirname, '..', 'api/**/*Interceptor{.js,.ts}')],
2728

2829
/**
2930
* Authorization features

‎src/loaders/homeLoader.ts

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import * as express from 'express';
12
import * as monitor from 'express-status-monitor';
23
import { MicroframeworkSettings, MicroframeworkLoader } from 'microframework';
34
import { env } from '../core/env';
@@ -9,7 +10,7 @@ export const homeLoader: MicroframeworkLoader = (settings: MicroframeworkSetting
910
expressApp.use(monitor());
1011
expressApp.get(
1112
env.app.routePrefix,
12-
(req: myExpress.Request, res: myExpress.Response) => {
13+
(req: express.Request, res: express.Response) => {
1314
return res.json({
1415
name: env.app.name,
1516
version: env.app.version,

‎src/types/interfaces.d.ts

+1-23
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,6 @@
11
declare namespace interfaces {
22

3-
interface Middleware {
4-
use(req: myExpress.Request, res: myExpress.Response, next: myExpress.NextFunction): void;
5-
}
6-
7-
interface Listener {
8-
act<T>(value?: T): void;
9-
act(...args: any[]): void;
10-
}
11-
12-
interface Configurable {
13-
configure<T>(instance: T): void;
14-
}
15-
16-
interface LoggerAdapter {
17-
debug(message: string, ...args: any[]): void;
18-
info(message: string, ...args: any[]): void;
19-
warn(message: string, ...args: any[]): void;
20-
error(message: string, ...args: any[]): void;
21-
}
22-
23-
interface LoggerAdapterConstructor {
24-
new (scope: string): LoggerAdapter;
25-
}
3+
// Here you can declare global interfaces
264

275
}
286

‎src/types/my-express.d.ts

-47
This file was deleted.

‎src/types/resources/user.d.ts

-14
This file was deleted.

0 commit comments

Comments
 (0)
Please sign in to comment.