Typescript ExpressJS API with webpack

When creating any API in node, I like to have a common scaffolding and delve directly into the code. Of course, every six months, a new framework comes, the stack changes and we need a new scaffolding.

In this tutorial, we will create a simple ExpressJS API with Typescript. Tests will be supported with Jest and Mocha/Chai.

If you use heroku and coveralls, you can even plug it to the app.

TL;DR
Check out https://github.com/anthillsolutions/api-skel for the whole package.

Scaffolding in a NodeJS environment

Initialisation

For the purpose of the tutorial, we will create an API with only one route:
GET / and it will output the following:

{“message”:”Welcome to API sekeleton.”,”version”:”1.0.0"}

Let’s init the repository:

$ mkdir tutorial
$ cd tutorial
$ npm init

You will be prompted with some additional information to fill.

Scaffolding creation

Our project structure is as follow (there might better structures out there):

|-> /tutorial
|---> /server
|-----> /controllers
|---> /tests
$ mkdir -p server/controllers tests

Install the necessary packages.

yarn add -D webpack typescript tslint ts-node ts-loader

Now we need the webpack configuration:

The configuration is quite simple. Don’t forget to add target: 'node' enabling webpack to work for node environment.
externals: nodeModules is here suppressing a warning explained on the James Long’s blog.

We also need to configure Typescript:

Note: in compilerOptions/paths/* types paths are added. So, if you need custom types, you can add them in ./server/types.

Code creation

Now that the scaffolding is ready, we can concentrate on our API.
We need those packages:

$ yarn add dotenv express body-parser
$ yarn add -D @types/body-parser @types/express @types/dotenv
  • dotenv is pretty handy for handling environment variables;
  • express is our main package for handling http requets;
  • body-parser is needed for json content.

We create the controller for the first route:

And the server:

Run

$ yarn && ./node_modules/webpack/bin/webpack.js
$ node ./dist/server.js

If everything is set properly, you will see:

App is running at http://localhost:3000 in development mode
Press CTRL-C to stop

Hooza! We have a minimalist API in ExpressJS written in Typescript.

Note: If you are not thrilled with ./node_modules/webpack/bin/webpack.js you can install globally webpack.

$ npm install -g webpack

We can set up package.json for this:

"scripts": {
"build": "webpack --config webpack.config.js",
"start": "npm run build && node ./dist/server.js"
}

Tests — preparation

Any good program should have its tests. We will use Jest from facebook. It alleviates a lot of pain.

Some preparation first:

$ yarn add -D jest @types/jest ts-jest

Note: we can add jest globally.

$ npm install -g jest

We will use also supertest, mocha and chai:

$ yarn add -D supertest @types/supertest mocha chai @types/chai

Jest needs a bit of configuration, so we need to add in package.json the following:

These options will cover any code written in Typescript in our project.

Tests — writing

Hopefully, our code base is small. We will write one simple test.

Supertest will launch the server in a test mode and will perform any call written in the test suite. In this instance, we check when we call GET / that there is the property message.

$ jest

Coverage

Let’s add coverage to the process. Jest is shipped with coverage options. We just need to update package.json.

100% test coverage, yeah!!!

Coveralls

Let’s show to world that we are thorough with our code and send the result to coveralls. For this, we need node-coverall and have a dedicated script.

yarn add -D coveralls

Next thing we need, is to add in our environment COVERALLS_REPO_TOKEN with the provided token.

Conclusion

The API is small and useless, but the scaffolding is useful for any project buildup.

We have now a working set up for Typescript ExpressJS APIs! We only have to add the content of the API!