Express TypeScript Boilerplate
This repo can be used as a starting point for backend development with Nodejs. It comes bundled with Docker and is CI/CD optimized. The development environment uses docker-compose
to start dependent services like mongo.
A few things to note in the project:
- Github Actions Workflows - Pre-configured Github Actions to run automated builds and publish image to Github Packages
- Dockerfile - Dockerfile to generate docker builds.
- docker-compose - Docker compose script to start service in production mode.
- Containerized Mongo for development - Starts a local mongo container with data persistence across runs.
- Mongo Connection Helper - A helper class to connect to MongoDB reliably.
- Joi - For declarative payload validation
- Middleware for easier async/await - Catches errors from routes and throws them to express error handler to prevent app crash due to uncaught errors.
- OpenAPI 3.0 Spec - A starter template to get started with API documentation using OpenAPI 3.0. This API spec is also available when running the development server at
http://localhost:3000/dev/api-docs
- .env file for configuration - Change server config like app port, mongo url etc
- Winston Logger - Uses winston as the logger for the application.
- ESLINT - ESLINT is configured for linting.
- Jest - Using Jest for running test cases
Installation
curl
Using $ bash <(curl -s https://raw.githubusercontent.com/sidhantpanda/public/master/scripts/generate-express-ts-app.sh)
Manual Method
1. Clone this repo
$ git clone git@github.com:sidhantpanda/docker-express-typescript-boilerplate.git your-app-name
$ cd your-app-name
2. Install dependencies
$ npm i
.github/workflows/latest.yml
3. Update repository name in - name: Publish image to Github Packages
uses: docker/build-push-action@v1
with:
username: $GITHUB_ACTOR
password: ${{ secrets.GITHUB_TOKEN }}
registry: docker.pkg.github.com
repository: YOUR_GITHUB_USER/YOUR_REPO_NAME/YOUR_PACKAGE_NAME
tags: latest
Development
Start dev server
Starting the dev server also starts MongoDB as a service in a docker container using the compose script at docker-compose.dev.yml
.
$ npm run dev
Running the above commands results in
- 🌏API Server running at
http://localhost:3000
- ⚙️Swagger UI at
http://localhost:3000/dev/api-docs
- 🛢️MongoDB running at
mongodb://localhost:27017
Packaging and Deployment
1. Build and run without Docker
$ npm run build && npm run start
2. Run with docker
$ docker build -t api-server .
$ docker run -t -i -p 3000:3000 api-server
3. Run with docker-compose
$ docker-compose up
Environment
To edit environment variables, create a file with name .env
and copy the contents from .env.default
to start with.
Var Name | Type | Default | Description |
---|---|---|---|
NODE_ENV | string | development |
API runtime environment. eg: staging |
PORT | number | 3000 |
Port to run the API server on |
MONGO_URL | string | mongodb://localhost:27017/books |
URL for MongoDB |
Logging
The application uses winston as the default logger. The configuration file is at src/logger.ts
.
- All logs are saved in
./logs
directory and at/logs
in the docker container. - The
docker-compose
file has a volume attached to container to expose host directory to the container for writing logs. - Console messages are prettified
- Each line in error log file is a stringified JSON.
Directory Structure
+-- scripts
| +-- dev.sh
+-- src
| +-- controllers
| | +-- book
| | | +-- add.ts
| | | +-- all.ts
| | | +-- index.ts
| | | +-- search.ts
| +-- errors
| | +-- index.ts
| +-- middleware
| | +-- request-middleware.ts
| +-- models
| | +-- Book.ts
| +-- app.ts
| +-- mongo-connection.ts
| +-- routes.ts
| +-- server.ts
+-- .env
+-- .env.default
+-- .eslintrc.json
+-- .gitignore
+-- .travis.yml
+-- docker-compose.dev.yml
+-- docker-compose.yml
+-- Dockerfile
+-- jest.config.js
+-- nodemon.json
+-- openapi.json
+-- package-lock.json
+-- package.json
+-- README.md
+-- tsconfig.json