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
If you want to use Docker
TODO install docker
If you work with a mac, we recommend to use homebrew for the installation.
Fork this project.
Then copy the .env.example file and rename it to .env. In this file you can edit your database connection information among other stuff, but everything should really work out of the box.
Then setup your application environment.
npm run 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.
Go to the project dir and start your app with this npm script.
npm run 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 ashttp://0.0.0.0:3000.
docker-compose up
This will also start particld for you.
Go to the project dir and hit this command in your terminal.
npm run console make:resource
Apply the same information like you see in the screenshot below.
With that you just have created a complete new endpoint in your api for the resource pets.
Normally a pet belogns to a user, so we have to add the relationship between users an pets. Open the created migration file and replace the user property with these lines.
table.integer('user_id').unsigned();
table.foreign('user_id').references('id').inTable('users').onDelete('cascade');
Next we have to add this relationship also in the pets model.
public user(): User {
return this.belongsTo(User);
}
The relationship between the users and pets are set and ready. So you can migrate your database with
npm run db:migrate
To seed some cute pets we need a smart factory. So open the ./src/database/factories/index.ts and add this code.
/**
* PET - Factory
*/
factory.define(Pet, (faker: Faker.FakerStatic, args: any[]) => {
const type = args[0];
return {
name: faker.name.firstName(),
type: type || 'dog',
userId: factory.get(User).returning('id')
};
});
This factory helps us to create a fake pet to seed to the database.
Run this command in your terminal and call the new seeder create pets.
npm run console make:seed
Open the file and place this code into it.
await factory.get(Pet)
.create(10);
Now we can seed some nice cats into the database with
npm run db:seed.
That was easy! Now its your turn to make something great out of it.
All script are defined in the package.json file, but the most important ones are listed here.
- Install all dependencies with
yarn install
- Run code quality analysis using
npm run lint. This runs tslint. - There is also a vscode task for this called
lint.
- Run the unit tests using
npm test(There is also a vscode task for this calledtest). - Run the black-box tests using
npm run test:black-boxand don't forget to start your application and your Auth0 Mock Server.
- Run
npm run serveto start nodemon with ts-node, to serve the app. - The server address will be displayed to you as
http://0.0.0.0:3000
- Run
npm run buildto generated all JavaScript files from the TypeScript sources (There is also a vscode task for this calledbuild). - To start the builded app located in
distusenpm start.
- Run
npm run db:migrateto migrate schema changes to the database - Run
npm run db:migrate:rollbackto rollback one migration - Run
npm run db:seedto seed sample data into the database - Run
npm run db:resetto rollback all migrations and migrate any migration again
- To run your own created command enter
npm run console <command-name>. - This list all your created commands
npm run console:help.
All the templates for the commands are located in src/console/templates.
npm run console make:resource <file>- Generates a controller, service, requests, repo, model and a migration with CRUD operations.npm run console make:controller <file>- Generates a controller.npm run console make:service <file>- Generates a service.npm run console make:repo <file>- Generates a repository.npm run console make:model <file>- Generates a model with the props and configurations.npm run console make:middleware <file>- Generates a basic middleware.npm run console make:request <file>- Generates a basic request.npm run console make:listener <file>- Generates a basic listener.npm run console make:exception <file>- Generates a basic exception.npm run console make:enum <file>- Generates a basic enum.npm run console make:api-test <file>- Generates an api test.npm run console update:targets <file>- Reads all the API files and generate a newconstants/Targets.tsfile out of it.
Example
$ npm run console make:controller auth/auth
// -> creates `api/controllers/auth/AuthController.ts
$ npm run console make:model user
// -> creates `api/models/User.ts
Our IoC automatically looks through the controllers, listeners , middlewares, services,
repositories and models folders in src/api/ for files to bound automatically into the IoC - Container, so you have nothing to do.
However it is very important to keep the naming right, because otherwise our IoC will not find your created files!!
Just set a breakpoint and hit F5 in your Visual Studio Code.
The route prefix is /api by default, but you can change this in the .env file.
| Route | Description |
|---|---|
| /api/info | Shows us the name, description and the version of the package.json |
| /api/docs | This is the Swagger UI with our API documentation |
| /status | Shows a small monitor page for the server |
| 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/exceptions/ | Exceptions like 404 NotFound |
| src/api/listeners/ | Event listeners |
| src/api/middlewares/ | Express Middlewares like populateUser |
| src/api/models/ | Bookshelf Models |
| src/api/repositories/ | Repository / DB layer |
| src/api/requests/ | Request bodys with validations |
| src/api/services/ | Service layer |
| src/api/ swagger.json | Swagger documentation |
| src/console/ | Command line scripts |
| src/config/ | Configurations like database or logger |
| src/constants/ | Global Constants |
| src/core/ | The core framework |
| src/database/factories/ | Model factories to generate database records |
| src/database/migrations/ | Migrations scripts to build up the database schema |
| src/database/seeds/ | Seed scripts to fake sample data into the database |
| 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/black-box/ *.test.ts | Black-Box tests (like e2e) |
| test/unit/ *.test.ts | Unit tests |
| .env.example | Environment configurations |
| knexfile.ts | This file is used for the migrations and seed task of knex |
This project is based on Express Typescript Boilerplate
A delightful way to building a RESTful API with NodeJs & TypeScript. An Node.js RESTful API boilerplate featuring Express, Inversify, Winston, TypeScript, TsLint, @types, Jest, Swagger, validatejs, knex and bookshelf by w3tech
- Beautiful Syntax thanks to the awesome annotations from Inversify Express Utils.
- Easy API Testing with included black-box testing.
- Dependency Injection done with the nice framework from Inversify.
- Fast Database Building with simple migration and seeding from Knex.
- Simplified Database Query with the ORM of Knex called Bookshelf.
- Clear Structure with controllers, services, repositories, models, middlewares...
- Easy Exception Handling with our own simple and easy to adopt logic. You will love it.
- 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.
- Smart Validation thanks to class-validator with some nice annotations.
- API Documentation thanks to swagger.
- API Monitoring thanks to express-status-monitor.
- Integrated Testing Tool thanks to Wallaby.js
- 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 black-box testing or faking an oAuth server