Introduction
Project is a faster way to building a Node.js RESTful API in TypeScript.
Start use now and just focus on your business and not spending hours in project configuration.
Features
- Beautiful Code thanks to the awesome annotations of the libraries from pleerock.
- 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).
- Basic Security Features thanks to Helmet.
- Easy event dispatching thanks to event-dispatch.
- Fast Database Building with simple migration from TypeORM.
- Easy Data Seeding with our own factories.
- Auth System thanks to jsonwebtoken.
- Docker thanks to docker.
- Class-based to handle websocket events thanks to socket-controllers.
- Class-based to handle Cron Jobs thanks to cron-decorators.
- API Documentation thanks to swagger and routing-controllers-openapi.
- GraphQL thanks to TypeGraphQL we have a some cool decorators to simplify the usage of GraphQL.
- Queue Jobs thanks to BullMQ.
Installation
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 a MySQL database.
If you work with a mac, i recommend to use DBngin for the installation.
Step 2: Create new Project
Clone 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 installThis installs all dependencies with npm. 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 run devThis starts a local server using
nodemon, which will watch for any file changes and will restart the server according to these changes. The server address will be displayed to you ashttp://localhost:3000.
Docker
Docker is a platform for developers and sysadmins to build, run, and share applications with containers.
- Starts the containers in the background and leaves them running:
docker-compose up -d. - Stops containers and removes containers, networks, volumes, and images:
docker-compose down.
API Routes
The route prefix is /api by default, but you can change this in the .env file.
| Route | Description |
|---|---|
| / | Home page |
| /api/login | Login |
| /api/users | Example entity endpoint |
| /docs | This is the Swagger UI with our API documentation |
| /graphql | Route to the graphql editor or your query/mutations requests |
Database Migration
- Run
npm run make:migration {name}to create a new migration file. - To migrate your database run
npm run migrate.
Running Seeders
- You may execute the
npm run db:seedcommand to seed your database.
Enable Cron Jobs
To enable cron jobs you just need to update your env file by set ENABLE_CRON_JOBS to true.
Sending Mail
return await (new MailSender).text('Hello').to('example@gmail.com').send().
Upload File
@Put('/:id')
public async update(@Param('id') id: number, @UploadedFile('file') file: Express.Multer.File) {
return await (new StorageService).put(file.originalname, file.buffer)
}Pagination & Sort
Pagination and Sort are implemented on method getAll for Users, try to send an api like this: http://localhost:3000/api/users?limit=10&page=1&sortByDesc=id.
Filters
The way a filter should be formed is:
{base_url}/users?filter[columnName][operator][not]=value- columnName - (Required) - Name of column you want to filter.
- operator - (Optional | Default:
eq) Type of operator you want to use. - not - (Optional | Default:
false) Negate the filter (Accepted values: yes|true|1).
Operators
| Type | Description |
|---|---|
| ct | String contains |
| sw | Starts with |
| ew | Ends with |
| eq | Equals |
| gt | Greater than |
| gte | Greater than or equalTo |
| lt | Lesser than |
| lte | Lesser than or equalTo |
| in | In array |
| bt | Between |
Project Structure
| Name | Description |
|---|---|
| dist/ | Compiled source files will be placed here |
| src/ | Source files |
| src/config | The config directory, as the name implies, contains all of your application's configuration files. |
| src/api/controllers/ | REST API Controllers |
| src/api/responses | Response classes or interfaces to type json response bodies |
| src/api/exceptions/ | Custom HttpErrors like 404 NotFound |
| src/api/models/ | TypeORM Models |
| src/api/repositories/ | Repository / DB layer |
| src/api/services/ | Service layer |
| src/api/events/ | Events |
| src/api/requests/ | Request classes with validation rules if the body is not equal with a model |
| src/api/transformers/ | Class-transformer allows you to transform plain object to some instance of class and versa |
| src/api/cron-jobs/ | Cron Jobs |
| src/api/resolvers/ | GraphQL resolvers (query, mutation & field-resolver) |
| src/api/types/ | GraphQL types, input-types and scalar types |
| src/api/queue-jobs/ | Queue Jobs |
| src/infrastructure/ | App Infrastructure |
| src/infrastructure/middlewares/ | Express Middlewares |
| src/database/factories | Factory the generate fake entities |
| src/database/migrations | Database migration scripts |
| src/database/seeds | Seeds to create some data in the database |
| src/decorators/ | Custom decorators like @EventDispatch |
| src/public/ | Static assets (fonts, css, js, img). |
| .env.example | Environment configurations |