
In this blog, we will generate TypeScript files from the protobuf files and publish them as an npm package.
We will be using <a href="https://github.com/rsbh/nodejs-microservices/tree/main/packages/protos" target="_blank">the protobuf files</a> that were created in [my last post](/blogs/grpc-with-nodejs-typescript).

The protobuf files are in a monorepo, causing some issues when containerizing the services with docker. Thus we will publish these protobuf files to a registry as an npm package and use the registry package inside the services instead of the symlink.

Some sections of this blog will be about versioning and publishing packages from a monorepo. You can skip those parts if you don't have a monorepo.

To manage the versions of the packages we will use `changesets`. There are other tools like `lerna` etc which can do same thing, but I prefer `changesets`. Read more about changesets <a href="https://github.com/changesets/changesets" target="_blank">here</a>

We will install the `@changesets/cli` package and run the `init` command. This will create the `config.json` file for `changesets` inside the `.changeset/` directory.

```sh
npm install @changesets/cli && npx changeset init
```

Lets change the current working directory to the protos package. We will make few changes in `package.json` and `build.sh` files.

```sh
cd packages/protos
```

First, we will update the output path for TypeScript files to `dist/ts`. We are doing this so that we can support other languages as well.

`build.sh`

```sh
#!/bin/bash
protoc --plugin=$(npm root)/.bin/protoc-gen-ts_proto \
 --ts_proto_out=dist/ts \
 --ts_proto_opt=outputServices=grpc-js \
 --ts_proto_opt=esModuleInterop=true \
 -I=src/ src/**/*.proto
```

We also need to install 2 packages as dev dependencies. `mkdirp` and `rimraf`. We need them to clean the `dist/ts` directory before every build.

```sh
npm i -D mkdirp rimraf
```

Then in the `package.json` file, we will add the `prebuild` and `postbuild` scripts. The `pre` and `post` prefix scripts auto-run before and after the script with the matching name. Read more about them <a href="https://docs.npmjs.com/cli/v9/using-npm/scripts#pre--post-scripts" target="_blank">here</a>.

`package.json`

```json
  "scripts": {
    "prebuild": "rimraf dist/ts && mkdirp dist/ts",
    "build": "./build.sh",
    "postbuild": "cp package.json ./dist/ts",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
```

The `prebuild` script will delete the `dist/ts` and recreate it. So every time we run the `build` script, we will get new files and not any files from previous builds.

The `postbuild` script will copy the `package.json` file to the `/dist/ts` folder. As we will publish only that folder as an npm package. This is because the current directory will have other files as well like `.proto` files, and other language generate files. We don't want them in the npm package. Plus the import paths will look clean as the files are next to the `package.json` file.

We will publish the `protos` package to npm with github actions. Thus we need to create a workflow file to build and release the package. The file should be in the `.github/workflows` directory otherwise the action will not run.

```sh
mkdir -p .github/workflows
touch .github/workflows/proto-npm-release.yml
```

In the workflow file, we will configure that the action will only run when a tag with the prefix as the package name is pushed. We will create a job named `publish` in the file. In the `Setup Node` step, we will pass `registry-url` and `scope`. This will create a `.npmrc` file that uses the `NODE_AUTH_TOKEN` environment variable for auth. So update the `org-name` as per your npm org. And in the `Publish packages`, we will change the current directory to `packages/protos/dist/ts` and run the `npm publish` command from there.

`.github/workflows/proto-npm-release.yml`

```yaml
name: Release

on:
  push:
    tags:
      - "@<org-name>/protos@*"

jobs:
  publish:
    name: Build and Publish
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: "16.x"
          registry-url: "https://registry.npmjs.org/"
          scope: "@<org-name>"

      - name: Install Protoc
        uses: arduino/setup-protoc@master
        with:
          version: "3.x"

      - name: Install and Build Packages
        run: |
          cd packages/protos
          npm install
          npm run build

      - name: Publish packages
        run: |
          cd packages/protos/dist/ts
          npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
```

We need to generate a token in npm to publish the packages.

![1687,1586](/publish-protobuf-typescript-to-npm/npm-token.png "Npm New Access Token page")

After generating the token, we need to create an environment variable in the github repo. The name of the variable will be `NODE_AUTH_TOKEN`. and copy the npm token as the secret here.

![1152,1920](/publish-protobuf-typescript-to-npm/github-env.png "Github env variable")

After this, we just need to create and publish a new tag to github and then github action will publish the package to the npm registry.

We will use using `changesets` to create a new tag. It will update the version in the `package.json` file and create a tag with the package name & version. If you don't want to use `changesets` then you can manually bump the `package.json` version and create a tag.

First, we need to run the `npx changeset` command from the root of the repo root. It will ask which package we need to update and what is the bump type.

```
npx changeset
```

Then we need to run the `version` command on the `changesets`. This will auto update the `package.json` versions.

```
npx changeset version
```

Then we need to run the `tag` command on the `changesets`. This will create the tags for the version updates. If `n` number of packages are updated then `n` number of tags will be created with their respective version. After that, we need to push the tags to the git repo.

```
npx changeset tag
git push --follow-tags
```

This will trigger the github action workflow and the package will be published to the npm. Then in the dependent apps, we need to uninstall the old local package and install the new one.

```sh
cd services/product-service
npm uninstall @nodejs-microservices/protos
```

We also need to remove the `packages/protos` from the root `package.json` workspaces, delete the root `node_modules` directory, and the lockfiles and reinstall the package. This will install the package from the registry instead of the local symlink one.

```
npm i @rsbh-nodejs-microservices/protos
```

I have changed the package name from `@nodejs-microservices/protos` to `@rsbh-nodejs-microservices/protos` as there is already an org with the name `nodejs-microservices`. We also need to update the package name and the import paths in the files as well.

`src/main.ts`

```diff
- import { ProductServiceService } from "@nodejs-microservices/protos/dist/product/product";
+ import { ProductServiceService } from "@rsbh-nodejs-microservices/protos/product/product";
```

`src/server.ts`

```diff
- import {
-  CreateProductRequest,
-  CreateProductResponse,
-  GetProductRequest,
-  GetProductResponse,
-  ListProductsRequest,
-  ListProductsResponse,
-  Product,
-  ProductServiceServer,
- } from "@nodejs-microservices/protos/dist/product/product";
+ import {
+  CreateProductRequest,
+  CreateProductResponse,
+  GetProductRequest,
+  GetProductResponse,
+  ListProductsRequest,
+  ListProductsResponse,
+  Product,
+  ProductServiceServer,
+ } from "@rsbh-nodejs-microservices/protos/product/product";
```

After removing the `protos` package from the root `package.json` workspaces, the `changesets` command will not show it during the version update. We need to manually copy it again in the `package.json` file and remove it after updating the version.

All the source code for this blog is available on <a href="https://github.com/rsbh/nodejs-microservices" target="_blank">GitHub</a>.


Publish Typescript files generated from protobuf to npm. Use Github Action to publish and Changesets to update the verions.

Publish protobuf as an NPM package

Create NodeJS microservices with gRPC, and TypeScript. Use ts-proto to generate TypeScript files from protobuf. Test gRPC endpoint with grpcurl

NodeJS Microservice with gRPC and TypeScript


In this post, we will dockerize a React application. We will setup Docker with auto-reloading for development setup and optimized multistage docker build for production deployment. We can even dockerize Next.js or Gatsby Static builds with the same process.

There are many advantages of using Docker. Right now Docker is the defacto standard of containerizing applications. It is easy to build, package, share, and ship applications with Docker. As Docker images are portable it is easy to deploy the application to any modern cloud provider.

## Initialize React application

Let's start by creating a React application. You can use your existing React project. For this blog post, I am creating a new React application with `create-react-app`.

```bash
$ npx create-react-app react-docker
```

Here I created a new React app named `react-docker`. Let's verify the app by running the `npm start` command inside the project directory.

```bash
$ npm start
```

It will start the app and we can verify by visiting [http://localhost:3000](http://localhost:3000) in the browser. The application should be running.

## Write Dockerfile.

Now let's create a Docker image for the React application. We need a Dockerfile to create Docker images. Let's create a file named `Dockerfile` in the root directory of the React application.

`Dockerfile`

```dockerfile
FROM node:14-alpine

WORKDIR /app

COPY package.json ./

COPY yarn.lock ./

RUN yarn install --frozen-lockfile

COPY . .

EXPOSE 3000

CMD ["npm", "start"]
```

Here We are using node v14 alpine as the base image to build and run the application. We are running the `npm start` command the default command which will run the React development server. We also need the `.dockerignore` file which will prevent `node_modules` and other unwanted files to get copied in the Docker image.

`.dockerignore`

```ignore
node_modules
npm-debug.log
Dockerfile
.dockerignore
```

Let's build the Docker image from the Dockerfile by running the `docker build` command. Here we are tagging it with the name `react-docker`.

```bash
$ docker build -t react-docker .
```

After building the docker images we can verify the image by running the `docker images` command. We can see an image with the name `react-docker` is created.

```bash
$ docker images

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
react-docker        latest              6b782301e271        2 minutes ago       438MB
```

We can run the Docker image with the `docker run` command. Here we are mapping the system port 3000 to Docker container port 3000. We can verify if the application is running or not by visiting [http://localhost:3000](http://localhost:3000).

```bash
$ docker run -p 3000:3000 react-docker
```

## Add Docker Compose

The React application is working fine inside the docker container, but we need to build and run the docker container every time we make any changes in the source files as auto reloading is not working with this setup. We need to mount the local `src` folder to the docker container `src` folder, so every time we make any change inside the `src` folder, it will auto-reload the page on any code changes.

We will add the `docker-compose.yml` file to the root of the project to mount the local `src` folder to the `/app/src` folder of the container.

`docker-compose.yml`

```yaml
version: "3"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./src:/app/src
    ports:
      - "3000:3000"
```

Run the `docker-compose up` command to start the container. The React development server will be running inside the container and will be watching the `src` folder.

```bash
$ docker-compose up
```

We can't ship this docker image to the production as it is not optimized and runs a development server inside. Let's rename the `Dockerfile` as `Dockerfile.dev` and update the `docker-compose.yaml` file to use the `Dockerfile.dev` file. We will use docker-compose and the `Dockerfile.dev` file only for development. We will create a new Dockerfile for the production build.

```bash
$ mv Dockerfile Dockerfile.dev
```

`docker-compose.yml`

```yaml
version: "3"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - ./src:/app/src
    ports:
      - "8000:8000"
```

## Add Production Dockerfile

Let's first verify the React application production config by running the `yarn build` command to build the app for production.

```bash
$ yarn build
```

We can verify the production build by running it locally. I am using `serve` to serve the `build` folder files.

```bash
$ npx serve -s build
```

After verifying the server locally we can create a new Dockerfile for the production build. We will be using multi-stage builds to create the docker image. One Stage to build the production files and the other stage to serve them.

`Dockerfile`

```dockerfile
FROM node:14-alpine AS builder
WORKDIR /app
COPY package.json ./
COPY yarn.lock ./
RUN yarn install --frozen-lockfile
COPY . .
RUN yarn build

FROM nginx:1.19-alpine AS server
COPY --from=builder ./app/build /usr/share/nginx/html
```

The `builder` stage is nearly the same as the previous Dockerfile. Instead of running the `npm start` command here, we are running the `yarn build` command to build the production files.

We will use `Nginx` to serve the files. It will create a very lightweight image. From the builder stage, we need to copy the files of the `build` folder to the `/usr/share/nginx/html` folder. Nginx docker image uses this folder to serve the contents. Nginx docker image will use the port `80` to serve the files and auto expose that port.

Let's build the image again by running the `docker build` command and verify if the image is built or not by running the `docker images` command.

```bash
$ docker build -t react-docker .
```

```bash
$ docker images

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
react-docker        latest              5f885aeca09e        7 seconds ago       23.1MB
```

The size of the production docker image will be very less in comparison to the development one. Let's run the docker image with the `docker run` command. Here we are mapping the host `3000` port with the container's port `80`

```bash
docker run -p 3000:80 react-docker
```

The application should be running fine on [http://localhost:3000](http://localhost:3000). Now let's verify if the client-side routing is working fine or not. For that, we need to install the `react-router-dom` to the application.

```bash
$ yarn add react-router-dom
```

We also need to add a few routes and links to verify. I just copied the example from the [react-router website](https://reactrouter.com/web/guides/quick-start/1st-example-basic-routing) to test.

```jsx
import React from "react";
import { BrowserRouter as Router, Switch, Route, Link } from "react-router-dom";

export default function App() {
  return (
    <Router>
      <div>
        <nav>
          <ul>
            <li>
              <Link to="/">Home</Link>
            </li>
            <li>
              <Link to="/about">About</Link>
            </li>
            <li>
              <Link to="/users">Users</Link>
            </li>
          </ul>
        </nav>
        <Switch>
          <Route path="/about">
            <About />
          </Route>
          <Route path="/users">
            <Users />
          </Route>
          <Route path="/">
            <Home />
          </Route>
        </Switch>
      </div>
    </Router>
  );
}

function Home() {
  return <h2>Home</h2>;
}

function About() {
  return <h2>About</h2>;
}

function Users() {
  return <h2>Users</h2>;
}
```

Let's verify the local setup by running the development server and **visit the web page and click on every link and refresh the pages.**

```bash
$ npm start
```

The application should be working fine on the local development server. Now try the same thing with docker-compose. First, we need to build the image again as auto-reload works only with the `src` folder as we only mount that. For changes outside the `src` folder, we need to build the image again with the `docker-compose build` command.

```bash
$ docker-compose build
$ docker-compose up
```

Now Let's try the same thing with the production docker build. First, we need to build the docker image and run the image again.

```bash
docker build -t react-docker .
docker run -p 3000:80 react-docker
```

Accessing the pages other than the index directly should throw a 404 error. The React application here is a single-page application. Thus the routing is happing on the client-side with JavaScript and when we hit any route it first hits the Nginx server and tries to find the file there and when it was unable to find the fine it throws the 404 error.

We need to pass a custom Nginx configuration to the docker image. We will create an `etc` folder in the project's root directory and create an `nginx.conf` file there.

`etc/nginx.conf`

```nginx
server {
    listen   80;
    listen   [::]:80 default ipv6only=on;

    root /usr/share/nginx/html;
    index index.html;

    server_tokens  off;
    server_name _;

    gzip on;
    gzip_disable "msie6";

    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_buffers 16 8k;
    gzip_http_version 1.1;
    gzip_min_length 0;
    gzip_types text/plain application/javascript text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript application/vnd.ms-fontobject application/x-font-ttf font/opentype;

    location / {
        try_files $uri /index.html;
    }
}
```

Here we are configuring Nginx to fallback to `/index.html` if it is unable to find the route. We also enable gzip compression for the contents.

We need to copy the custom Nginx configuration file to the `/etc/nginx/conf.d` folder. Ngnix will auto-read all the configurations from that folder.

```dockerfile
FROM node:14-alpine AS builder
WORKDIR /app
COPY package.json ./
COPY yarn.lock ./
RUN yarn install --frozen-lockfile
COPY . .
RUN yarn build

FROM nginx:1.19-alpine AS server
COPY ./etc/nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=builder ./app/build /usr/share/nginx/html
```

After copying the custom Nginx configuration file we need to build and run the docker image again.

```bash
$ docker build -t react-docker .
$ docker run -p 3000:80 react-docker
```

Visiting all the routes and refreshing the pages should work fine.

All the source code for this tutorial is available on [GitHub](https://github.com/rsbh/react-docker).

For dockerizing node backend app please read the [other blog post](https://rsbh.dev/blogs/rest-api-express-typescript-docker)


Learn how to dockerize React single page application. Create development image with auto-reload and lightweight & optimized production image with Nginx setup.

Dockerizing a React.js app

Learn how to setup Jest in Express and TypeScript server to test code. Add unit tests for the REST APIs controller and mock database to test repositories. Setup Github Actions to run tests.

Building REST API with Express, TypeScript - Part 4: Jest and unit testing

Learn how to connect PostgreSQL database from Express and TypeScript REST API server using TypeORM. Create TypeORM models and repositories.

Building REST API with Express, TypeScript - Part 3: PostgreSQL and TypeORM


In the [previous post](/blogs/rest-api-with-express-typescript), we build a REST API server with Express and TypeScript. In this post, we will dockerize the sever.

## Why Docker.

Docker helps organizations to ship and develop applications better and faster. It will be easy to set up the development environment on any new machine with docker as it abstracts out lots of complexity of setting up dependencies and environment. Docker also isolates the project from other projects in the same machine so the developer can run multiple projects without having any conflict with the required dependencies.

Docker makes it easy to configure and setup dependencies and environments for the application. As most of the companies have dedicated teams to do setup and manage infrastructure, Docker gives more power to developers to configure without depending on other teams to do the setup.

## Write Dockerfile.

To Dockerize the server, we need to create a `Dockerfile`. A Dockerfile is just a list of instructions to create a docker image. Read more about Dockerfile [here](https://docs.docker.com/engine/reference/builder/)

Each line in the Dockerfile is a command and create a new image layer of its own. Docker caches the images during the build, so every rebuild will only create the new layer which got changed from the last build. Here the order of commands is very significant as it helps to reduce the build time.

Let's start writing Dockerfile for the server. Here we are taking `node:12` as the base image for the server docker image. Explore [dockerhub](https://hub.docker.com/_/node) for more node image version. Here we are copying the `package.json` and doing `npm install` first, then copying the other files. Docker will cache the images of these two steps during the build and reuse them later as they change less frequently. Here we will be running the development server with the docker image, so we need to give `npm run dev` as the executing command.

`Dockerfile`

```dockerfile
FROM node:12

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 8000

CMD ["npm", "run", "dev"]
```

We need to add `.dockerignore` to tell docker build to ignore some files during the `COPY` Command.

`.dockerignore`

```ignore
node_modules
npm-debug.log
```

After creating the Dockerfile, we need to run the `docker build` to create a docker image from the Dockerfile. Here we are naming the docker image as `express-ts`

```bash
docker build -t express-ts .
```

We can verify the docker image by running the `docker images` command. Here we can see the name, size, and tag of the docker images.

```bash
docker images
REPOSITORY                        TAG                 IMAGE ID            CREATED             SIZE
express-ts                        latest              d0ce1e38958b        2 minutes ago       1.11GB
```

We can run the docker image with the `docker run` command. Here we can mapping the system port 8000 to docker container port 8000. We can verify if the server is running or not by visiting [http://localhost:8000/ping](http://localhost:8000/ping)

```bash
docker run -p 8000:8000 express-ts
```

## Add Docker Compose

The development server is running fine inside docker, but now we need to run the `docker build` command every time after making any changes to the source files to update the changes during development because the nodemon inside the docker container cannot watch the `src` folder on the local machine. We need to mount the local `src` folder to the docker container folder, so every time we make any change inside the `src` folder, nodemon restarts the development server inside the docker container.

We will add the `docker-compose.yml` file to the root of the project to mount the local `src` folder. Read more about docker-compose [here](https://docs.docker.com/compose/)

`docker-compose.yml`

```yaml
version: "3"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./src:/app/src
    ports:
      - "8000:8000"
```

We need to run the command `docker-compose up` to start the server. Now the server is running in development mode with auto-restart on code changes. We can verify the server is restarting on code changes by making any code change in the TypeScript files.

```bash
docker-compose up
```

The docker setup for the development server is completed. Let's rename the Dockerfile as `Dockerfile.dev` and update the docker-compose.yaml file. We will use the `Dockerfile` for the production image, which we are going to set up in the next section.

```bash
mv Dockerfile Dockerfile.dev
```

`docker-compose.yml`

```yaml
version: "3"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - ./src:/app/src
    ports:
      - "8000:8000"
```

## Add Production Dockerfile

Let's start building a docker image for the production server. We need to create a new Dockerfile and add the following commands. Here after copying the files, we need to build the JavaSript files and execute the `npm start` command.

```dockerfile
FROM node:12

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

RUN npm run build

EXPOSE 8000

CMD ["node", "start"]
```

After running the `docker build` command, we can see the docker image is created for the production server.

```bash
docker images
REPOSITORY                      TAG                 IMAGE ID            CREATED             SIZE
express-ts                      latest              d0ce1e38958b        2 minutes ago       1.11GB
```

Here the image size is `1.11GB`, which is not optimized. Let's optimize the docker image and reduce the size.

First, instead of taking `node:12` as the base image, we will be taking its alpine variant. Alpine Linux is very lightweight. Read more about alpine-docker [here](http://gliderlabs.viewdocs.io/docker-alpine/).

```dockerfile
FROM node:12-alpine
```

Let's build the docker image with the updated Dockerfile. Here we are tagging the docker image as `alpine` so we can compare the image size with the previous build.

```bash
docker build -t express-ts/alpine .
```

```bash
docker images
REPOSITORY                       TAG                 IMAGE ID            CREATED             SIZE
express-ts                       alpine              2b06fcba880e        46 seconds ago      280MB
express-ts                       latest              d0ce1e38958b        2 minutes ago       1.11GB
```

After running the `docker images` command we can see the difference in the sizes of docker images. The docker image is much leaner than the previous build.

There are still some issues with our docker image as development dependencies are there in production build and TypeScript code is there, which is not required while running the server in production. So let's optimize the docker image further with a multi-stage build.

Here we create two stages, one for building the server and the other for running the server. In the builder stage, we generate Javascript code from the Typescript files. Then in the server stage, we copy the generated files from the builder stage to the server stage. In the Server stage, we need only production dependencies, that's why we will pass the `--production` flag to the `npm install` command.

```dockerfile
FROM node:12-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM node:12-alpine AS server
WORKDIR /app
COPY package* ./
RUN npm install --production
COPY --from=builder ./app/public ./public
COPY --from=builder ./app/build ./build
EXPOSE 8000
CMD ["npm", "start"]
```

Let's build the docker image with the updated multi-staged Dockerfile. Here we are tagging the docker image as `ms` so we can compare the image sizes with the previous builds.

```bash
docker build -t express-ts/ms .
```

```bash
docker images

REPOSITORY                       TAG                 IMAGE ID            CREATED             SIZE
express-ts                       alpine              2b06fcba880e        46 seconds ago      280MB
express-ts                       latest              d0ce1e38958b        2 minutes ago       1.11GB
express-ts                       ms                  26b67bfe45b0        9 minutes ago       194MB
```

After running the `docker images` command we can see the difference in the sizes of docker images. The multi staged image is the leanest among all images.

We have dockerized the development and production version of the Express and TypeScript REST API server.

All the source code for this tutorial is available on [GitHub](https://github.com/rsbh/express-typescript).

### Next

- [Building REST API with Express, TypeScript - Part 3: PostgreSQL and Typeorm](/blogs/rest-api-express-postgres-typeorm)
- [Building REST API with Express, TypeScript - Part 4: Jest and unit testing](/blogs/rest-api-express-typescript-jest-testing)


Learn how to dockerize REST API server built with Express and TypeScript. Create a development image with auto restart on code changes and a lean production image with multi-staged build

Building REST API with Express, TypeScript - Part 2: Docker Setup


I’ve started working with JS in 2017, since then I am writing frontend and backend code with it. It is easy to write web-server with NodeJS and I never found any serious performance issue in using NodeJS. According to [Stack Overflow 2020 survey](https://insights.stackoverflow.com/survey/2020#technology-other-frameworks-libraries-and-tools), NodeJS is the most popular technology. I prefer using [Express](https://expressjs.com/) with [NodeJS](https://nodejs.org/). It is one of the most popular Node.js web application frameworks. There are multiple frameworks, and you can choose whichever you want according to the need.

After working with [TypeScript](https://www.typescriptlang.org/), it became my preferred language of choice between JS and TS. TypeScript is the superset of JavaScript, means all valid JS is valid TypeScript. So it is easy to learn Typescript if you already knew JavaScript. TypeScript is 2nd most loved language according to the [Stack Overflow 2020 survey](https://insights.stackoverflow.com/survey/2020#technology-most-loved-dreaded-and-wanted-languages-loved). TypeScript helps you to add static types to the Javascript code. It is very helpful in writing, maintaining, and debugging code.

## What you will build

You will build REST API server with Express and TypeScript. It will generate production JavaScript code on `build` command. It will auto restart server on any code change during development, and it will auto generate OpenAPI documentation with [Swagger](https://swagger.io/).

## Bootstrap project

Let's create a directory with your preferred application name and set up an empty node project inside it. You can choose to customize package.json or accepts all of the default options by passing `-y` flag to `init` command.

```bash
mkdir express-typescript
cd express-typescript
npm init -y
```

Install Typescript as development dependency

```bash
npm i -D typescript
```

Add `tsconfig.json` in the root of the project directory. Here we define `outDir` as `./build` to put generated JavaScript files. You can put your preferred directory name. You can customize the config file more as per your need. Check [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) for more details.

`tsconfig.json`

```json
{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./build",
    "strict": true,
    "esModuleInterop": true
  }
}
```

Install Express as dependency and type definitions of node and express as development dependencies.

```bash
npm i -S express
npm i -D @types/express @types/node
```

## Write server code

Let's add minimal code to make server up and running. Create a folder `src` inside the root folder. We will be going to put all the Typescript code inside it. It depends on personal choice. You can keep the code anywhere in the project.

This code will run the express server, listening to port 8000. It will add `/ping` route, which will reply JSON response on the GET call.

`src/index.ts`

```ts
import express, { Application } from "express";

const PORT = process.env.PORT || 8000;

const app: Application = express();

app.get("/ping", async (_req, res) => {
  res.send({
    message: "pong",
  });
});

app.listen(PORT, () => {
  console.log("Server is running on port", PORT);
});
```

Let's add the build command. it will transpile the TypeScript code into JavaScript and put the generated code in the output directory as mentioned in `tsconfig.json`.

`package.json`

```json
"scripts": {
  "build": "tsc",
}
```

Now let's build the JavaScript code with the build command.

```bash
npm run build
```

After running the above command we can see the JS code generated in the build folder. Now with node, we can run the server. We can visit [http://localhost:8000/ping](http://localhost:8000/ping) to see the JSON response.

```bash
node build/index.js

Server is running on port 8000
```

## Add development setup

The server is up and running. But still, development is difficult due to building and running the server manually after every code changes. It is better to automate this task. For this, we will use [ts-node](https://github.com/TypeStrong/ts-node) to run the typescript code directly, so then we don't have to run the typescript compiler during development. And to restart the ts-node on every code change, we will use [nodemon](https://nodemon.io/) which will watch the code and re-run the command on any changes.

Lets add ts-node nodemon as development dependencies in the project.

```bash
npm i -D ts-node nodemon
```

Now add the `dev` script to package.json, which will run the nodemon command. Add nodemon config to package.json. We can keep the config as a separate file. But I prefer to add it to package.json to keep the root of the project clean. Here we are configuring nodemon to watch all the `.ts` files inside the `src` folder and execute `ts-node src/index.ts` on any code change.

`package.json`

```json
  "scripts": {
    "build": "tsc",
    "dev": "nodemon",
  },

  "nodemonConfig": {
    "watch": [
      "src"
    ],
    "ext": "ts",
    "exec": "ts-node src/index.ts"
  }
```

After running the `dev` command, we can see the nodemon is running. And the server is up and running as well.

```bash
npm run dev

[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): src/**/*
[nodemon] watching extensions: ts
[nodemon] starting `ts-node src/index.ts`
Server is running on port 8000
```

## Add middlewares

Let's extend the server by adding some [middlewares](https://expressjs.com/en/guide/using-middleware.html). We are going to add three middleware to the server. `express.json` is built-in middleware to parse the request body, `express.static` is also built-in middleware used to serve the static files, and `morgan` is used to logs the requests. Let's install them as dependencies and their type definitions as development dependencies in the project.

```bash
npm i -S morgan
npm i -D @types/morgan
```

After installing the middleware, we can use them in the code. We will add them to the server with `app.use()` function. Here we make the `public` folder to serve the static files.

`src/index.ts`

```ts
import express, { Application } from "express";
import morgan from "morgan";

const PORT = process.env.PORT || 8000;

const app: Application = express();

app.use(express.json());
app.use(morgan("tiny"));
app.use(express.static("public"));
```

Now after running the server, open [http://localhost:8000/ping](http://localhost:8000/ping) in the browser. We can see the request gets logged in the terminal.

```bash
Server is running on port 8000
GET /ping 304 - - 2.224 ms
```

## Refactor

Till now the server is one single file. It is okay for small servers, but it is difficult to extend the server if it is one file. So we will create multiple files.

Let's create a controller for the ping request in `src/controllers/ping.ts` path. Here we add a class called `PingController` with method `getMessage`, we define the response interface with a property message as a string.

`src/controllers/ping.ts`

```ts
interface PingResponse {
  message: string;
}

export default class PingController {
  public async getMessage(): Promise<PingResponse> {
    return {
      message: "pong",
    };
  }
}
```

Now create a sub router in `src/routes/index.ts` file and move all the routing login there. In the server, we will add this sub router as a middleware.

`src/routes/index.ts`

```ts
import express from "express";
import PingController from "../controllers/ping";

const router = express.Router();

router.get("/ping", async (_req, res) => {
  const controller = new PingController();
  const response = await controller.getMessage();
  return res.send(response);
});

export default router;
```

`src/index.ts`

```ts
import express, { Application } from "express";
import morgan from "morgan";
import Router from "./routes";

const PORT = process.env.PORT || 8000;

const app: Application = express();

app.use(express.json());
app.use(morgan("tiny"));
app.use(express.static("public"));

app.use(Router);

app.listen(PORT, () => {
  console.log("Server is running on port", PORT);
});
```

## Swagger integration

Let's add OpenAPI documentation with the Swagger. We need to add `tsoa` to generates a JSON file with OpenAPI Specifications for all the APIs. We also need `swagger-ui-express` to host the Swagger JSON with Swagger UI.

```bash
npm i -S tsoa swagger-ui-express
npm i -D @types/swagger-ui-express concurrently
```

We need to add support for Decorators in the `tsconfig.json` file.

`tsconfig.json`

```json
{
  "compilerOptions": {
    ...
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

We need to create the config file for tsoa. Add `tsoa.json` at the root of the directory. Add `entryFile` and `outputDirectory` in the config. Here we are setting `public` as the output folder for the generated JSON file.

`tsoa.json`

```json
{
  "entryFile": "src/index.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "spec": {
    "outputDirectory": "public",
    "specVersion": 3
  }
}
```

We update the dev and build command to generate Swagger docs. We add `tsoa spec` to generate Swagger docs. We will be running the `swagger` command before build and dev command with `prebuild` and `predev` Respectively. We add `concurrently` to the dev command, which will run the nodemon and tsoa spec on parallel. The Swagger docs will get auto-updated on every code change during development.

`package.json`

```json
  "scripts": {
    "start": "node build/index.js",
    "predev": "npm run swagger",
    "prebuild": "npm run swagger",
    "build": "tsc",
    "dev": "concurrently \"nodemon\" \"nodemon -x tsoa spec\"",
    "swagger": "tsoa spec",
  },
```

Let's update the server file to serve the Swagger UI. We add `swagger-ui-express` to serve the Swagger UI for the hosted swagger JSON file.

`src/index.ts`

```ts
import express, { Application, Request, Response } from "express";
import morgan from "morgan";
import swaggerUi from "swagger-ui-express";

import Router from "./routes";

const PORT = process.env.PORT || 8000;

const app: Application = express();

app.use(express.json());
app.use(morgan("tiny"));
app.use(express.static("public"));

app.use(
  "/docs",
  swaggerUi.serve,
  swaggerUi.setup(undefined, {
    swaggerOptions: {
      url: "/swagger.json",
    },
  })
);

app.use(Router);
```

Now let's update the controller and add decorators to the class and methods to define the path and route for the API documentation. `tsoa` will pick the return type `PingResponse` as the response type for the `/ping` route.

`src/controllers/ping.ts`

```ts
import { Get, Route } from "tsoa";

interface PingResponse {
  message: string;
}

@Route("ping")
export default class PingController {
  @Get("/")
  public async getMessage(): Promise<PingResponse> {
    return {
      message: "pong",
    };
  }
}
```

After making all the changes and running the server, visit [http://localhost:8000/docs/](http://localhost:8000/docs/) to access the APIs documentation.

All the source code for this tutorial is available on [GitHub](https://github.com/rsbh/express-typescript).

### Additional Resources

- [Building a Node.js/TypeScript REST API, Part 1: Express.js](https://www.toptal.com/express-js/nodejs-typescript-rest-api-pt-1)

### Next

- [Building REST API with Express, TypeScript - Part 2: Docker Setup](/blogs/rest-api-express-typescript-docker)
- [Building REST API with Express, TypeScript - Part 3: PostgreSQL and Typeorm](/blogs/rest-api-express-postgres-typeorm)
- [Building REST API with Express, TypeScript - Part 4: Jest and unit testing](/blogs/rest-api-express-typescript-jest-testing)


How to build REST API server with Express & TypeScript, and auto-generate OpenAPI documentation with Swagger