@ewizardjs/builder-utils

TypeScript Node Starter

Pre-reqs

• Install Node.js
• Install VS Code

Getting started

• Install dependencies

cd <project_name>
npm install

• Build and run the project

npm start

Getting TypeScript

TypeScript itself is simple to add to any project with npm.

npm install -D typescript

If you're using VS Code then you're good to go! VS Code will detect and use the TypeScript version you have installed in your node_modules folder. For other editors, make sure you have the corresponding TypeScript plugin.

Project Structure

The most obvious difference in a TypeScript + Node project is the folder structure. In a TypeScript project, it's best to have separate source and distributable files. TypeScript (.ts) files live in your src folder and after compilation are output as JavaScript (.js) in the dist folder.

The full folder structure of this app is explained below:

Note! Make sure you have already built the app using npm run build

Name	Description
.vscode	Contains VS Code specific settings
dist	Contains the distributable (or output) from your TypeScript build. This is the code you ship
node_modules	Contains all your npm dependencies
src	Contains your source code that will be compiled to the dist dir
src/types	Holds .d.ts files not found on DefinitelyTyped. Covered more in this section
src/index.ts	Entry point to your express app
.copyStaticAssets.js	Build script that copies images, fonts, and JS libs to the dist folder
package.json	File that contains npm dependencies as well as build scripts
tsconfig.json	Config settings for compiling server code written in TypeScript
tslint.json	Config settings for TSLint code style checking

Building the project

It is rare for JavaScript projects not to have some kind of build pipeline these days, however Node projects typically have the least amount build configuration. Because of this I've tried to keep the build as simple as possible. If you're concerned about compile time, the main watch task takes ~2s to refresh.

Configuring TypeScript compilation

TypeScript uses the file tsconfig.json to adjust project compile options. Let's dissect this project's tsconfig.json, starting with the compilerOptions which details how your project is compiled.

    "compilerOptions": {
        "module": "commonjs",
        "target": "es6",
        "noImplicitAny": true,
        "moduleResolution": "node",
        "sourceMap": true,
        "outDir": "dist",
        "baseUrl": ".",
        "paths": {
            "*": [
                "node_modules/*",
                "src/types/*"
            ]
        }
    },

compilerOptions	Description
"module": "commonjs"	The output module type (in your .js files). Node uses commonjs, so that is what we use
"target": "es6"	The output language level. Node supports ES6, so we can target that here
"noImplicitAny": true	Enables a stricter setting which throws errors when something has a default any value
"moduleResolution": "node"	TypeScript attempts to mimic Node's module resolution strategy. Read more here
"sourceMap": true	We want source maps to be output along side our JavaScript. See the debugging section
"outDir": "dist"	Location to output .js files after compilation
"baseUrl": "."	Part of configuring module resolution. See path mapping section
paths: {...}	Part of configuring module resolution. See path mapping section

The rest of the file define the TypeScript project context. The project context is basically a set of options that determine which files are compiled when the compiler is invoked with a specific tsconfig.json. In this case, we use the following to define our project context:

    "include": [
        "src/**/*"
    ]

include takes an array of glob patterns of files to include in the compilation. This project is fairly simple and all of our .ts files are under the src folder. For more complex setups, you can include an exclude array of glob patterns that removes specific files from the set defined with include. There is also a files option which takes an array of individual file names which overrides both include and exclude.

Running the build

All the different build steps are orchestrated via npm scripts. Npm scripts basically allow us to call (and chain) terminal commands via npm. This is nice because most JavaScript tools have easy to use command line utilities allowing us to not need grunt or gulp to manage our builds. If you open package.json, you will see a scripts section with all the different scripts you can call. To call a script, simply run npm run <script-name> from the command line. You'll notice that npm scripts can call each other which makes it easy to compose complex builds out of simple individual build scripts. Below is a list of all the scripts this template has available:

Npm Script	Description
start	Runs full build before starting all watch tasks. Can be invoked with npm start
build	Full build. Runs ALL build tasks
build-ts	Compiles all source .ts files to .js files in the dist folder
watch-ts	Same as build-ts but continuously watches .ts files and re-compiles when needed
tslint	Runs TSLint on project files
copy-static-assets	Calls script that copies JS libs, fonts, and images to dist directory

Type Definition (.d.ts) Files

TypeScript uses .d.ts files to provide types for JavaScript libraries that were not written in TypeScript. This is great because once you have a .d.ts file, TypeScript can type check that library and provide you better help in your editor. The TypeScript community actively shares all of the most up-to-date .d.ts files for popular libraries on a GitHub repository called DefinitelyTyped. Making sure that your .d.ts files are setup correctly is super important because once they're in place, you get an incredible amount high quality of type checking (and thus bug catching, IntelliSense, and other editor tools) for free.

Note! Because we're using "noImplicitAny": true, we are required to have a .d.ts file for every library we use. While you could set noImplicitAny to false to silence errors about missing .d.ts files, it is a best practice to have a .d.ts file for every library. (Even the .d.ts file is basically empty!)

Installing .d.ts files from DefinitelyTyped

For the most part, you'll find .d.ts files for the libraries you are using on DefinitelyTyped. These .d.ts files can be easily installed into your project by using the npm scope @types. For example, if we want the .d.ts file for jQuery, we can do so with npm install --save-dev @types/jquery.

Note! Be sure to add --save-dev (or -D) to your npm install. .d.ts files are project dependencies, but only used at compile time and thus should be dev dependencies.

In this template, all the .d.ts files have already been added to devDependencies in package.json, so you will get everything you need after running your first npm install. Once .d.ts files have been installed using npm, you should see them in your node_modules/@types folder. The compiler will always look in this folder for .d.ts files when resolving JavaScript libraries.

What if a library isn't on DefinitelyTyped?

If you try to install a .d.ts file from @types and it isn't found, or you check DefinitelyTyped and cannot find a specific library, you will want to create your own .d.ts file. In the src folder of this project, you'll find the types folder which holds the .d.ts files that aren't on DefinitelyTyped (or weren't as of the time of this writing).

Setting up TypeScript to look for .d.ts files in another folder

The compiler knows to look in node_modules/@types by default, but to help the compiler find our own .d.ts files we have to configure path mapping in our tsconfig.json. Path mapping can get pretty confusing, but the basic idea is that the TypeScript compiler will look in specific places, in a specific order when resolving modules, and we have the ability to tell the compiler exactly how to do it. In the tsconfig.json for this project you'll see the following:

"baseUrl": ".",
"paths": {
    "*": [
        "src/types/*"
    ]
}

This tells the TypeScript compiler that in addition to looking in node_modules/@types for every import (*) also look in our own .d.ts file location <baseUrl> + src/types/*. So when we write something like:

import * as lusca from "lusca";

First the compiler will look for a d.ts file in node_modules/@types and then when it doesn't find one look in src/types and find our file lusca.d.ts.

Using dts-gen

Unless you are familiar with .d.ts files, I strongly recommend trying to use the tool dts-gen first. The README does a great job explaining how to use the tool, and for most cases, you'll get an excellent scaffold of a .d.ts file to start with.

Writing a .d.ts file

If generating a .d.ts using dts-gen isn't working, you should tell me about it first, but then you can create your own .d.ts file.

If you just want to silence the compiler for the time being, create a file called <some-library>.d.ts in your types folder and then add this line of code:

declare module "<some-library>";

If you want to invest some time into making a great .d.ts file that will give you great type checking and IntelliSense, the TypeScript website has great docs on authoring .d.ts files.

Summary of .d.ts management

In general if you stick to the following steps you should have minimal .d.ts issues;

1. After installing any npm package as a dependency or dev dependency, immediately try to install the .d.ts file via @types.
2. If the library has a .d.ts file on DefinitelyTyped, the install will succeed and you are done. If the install fails because the package doesn't exist, continue to step 3.
3. Make sure you project is configured for supplying your own d.ts files
4. Try to generate a .d.ts file with dts-gen. If it succeeds, you are done. If not, continue to step 5.
5. Create a file called <some-library>.d.ts in your types folder.
6. Add the following code:

declare module "<some-library>";

7. At this point everything should compile with no errors and you can either improve the types in the .d.ts file by following this guide on authoring .d.ts files or continue with no types.

Debugging

Debugging TypeScript is exactly like debugging JavaScript with one caveat, you need source maps.

Source maps

Source maps allow you to drop break points in your TypeScript source code and have that break point be hit by the JavaScript that is being executed at runtime.

Note! - Source maps aren't specific to TypeScript. Anytime JavaScript is transformed (transpiled, compiled, optimized, minified, etc) you need source maps so that the code that is executed at runtime can be mapped back to the source that generated it.

The best part of source maps is when configured correctly, you don't even know they exist! So let's take a look at how we do that in this project.

Configuring source maps

First you need to make sure your tsconfig.json has source map generation enabled:

"compilerOptions" {
    "sourceMaps": true
} 

With this option enabled, next to every .js file that the TypeScript compiler outputs there will be a .map.js file as well. This .map.js file provides the information necessary to map back to the source .ts file while debugging.

Note! - It is also possible to generate "inline" source maps using "inlineSourceMap": true. This is more common when writing client side code because some bundlers need inline source maps to preserve the mapping through the bundle. Because we are writing Node.js code, we don't have to worry about this.

Using the debugger in VS Code

Debugging is one of the places where VS Code really shines over other editors. Node.js debugging in VS Code is easy to setup and even easier to use. This project comes pre-configured with everything you need to get started.

When you hit F5 in VS Code, it looks for a top level .vscode folder with a launch.json file. In this file, you can tell VS Code exactly what you want to do:

{
    "type": "node",
    "request": "launch",
    "name": "Debug",
    "program": "${workspaceRoot}/dist/index.js",
    "smartStep": true,
    "outFiles": [
        "../dist/**/*.js"
    ],
    "protocol": "inspector"
}

This is mostly identical to the "Node.js: Launch Program" template with a couple minor changes:

launch.json Options	Description
"program": "${workspaceRoot}/dist/index.js",	Modified to point to our entry point in dist
"smartStep": true,	Won't step into code that doesn't have a source map
"outFiles": [...]	Specify where output files are dropped. Use with source maps
"protocol": inspector,	Use the new Node debug protocol because we're on the latest node

With this file in place, you can hit F5 to serve the project with the debugger already attached. Now just set your breakpoints and go!

Warning! Make sure you don't have the project already running from another command line. VS Code will try to launch on the same port and error out. Likewise be sure to stop the debugger before returning to your normal npm start process.

Using attach debug configuration

VS Code debuggers also support attaching to an already running program. The Attach configuration has already configured, everything you need to do is change Debug Configuration to Attach and hit F5.

Tips! Instead of running npm start, using npm run debug and Attach Configuration that make you don't need to stop running project to debug.

TSLint

TSLint is a code linter which mainly helps catch minor code quality and style issues. TSLint is very similar to ESLint or JSLint but is built with TypeScript in mind.

TSLint rules

Like most linters, TSLint has a wide set of configurable rules as well as support for custom rule sets. All rules are configured through tslint.json. In this project, we are using a fairly basic set of rules with no additional custom rules.

Running TSLint

Like the rest of our build steps, we use npm scripts to invoke TSLint. To run TSLint you can call the main build script or just the TSLint task.

npm run build   // runs full build including TSLint
npm run tslint  // runs only TSLint

## `devDependencies`

| Package                         | Description                                                           |
| ------------------------------- | --------------------------------------------------------------------- |
| tslint                          | Linter (similar to ESLint) for TypeScript files                       |
| typescript                      | JavaScript compiler/type checker that boosts JavaScript productivity  |

To install or update these dependencies you can use `npm install` or `npm update`.