Photo by Fotis Fotopoulos on Unsplash

Your First TypeScript Project Part 1

Hello, in this article I want to walk you through a basic project that helps identify the common steps to create a new TypeScript project. Now I know with my job I came into the role where there was already a TypeScript project built and configured the way that we needed so I didn’t have to worry too much about it. However when I first started using TypeScript I wish I would have known some of what we are about to cover here in this post. So get some coffee, I prefer Monster’s over coffee but whatever floats your boat will do, find a nice chair to sit in, place your laptop somewhere comfy because it’s time to build a TypeScript project from scratch. Let’s do this.

Simple Setup

I want to go over my setup which makes it a bit easier for you to follow along. If you are on Windows you should still be able to follow along just fine especially if you are using Git Bash with Windows Terminal. I will not cover how to set that up in this article but others have covered it and it takes about 5 minutes. I am on Linux so those of you on Linux or macOS should be able to follow along with the exact commands that I run in the terminal just fine. I am also using VS Code, but any text editor will do. We are going to go over what you need installed just in case this is your first time programming in any language and if so welcome. You’re going to love it here. :)

VS Code

Here is the download link for Visual Studio Code: https://code.visualstudio.com/. If you don’t already have a text editor of choice I recommend this one.

Node.js

For Nodejs I use a tool called Volta to install versions of Node to my machine. The tool allows you to manage your version of Node on a per project basis. For those coming from Python it kind of acts like a virtual environment to a certain extent. If you don’t want to use the tool that’s not a problem. You can visit this link here and you can download the LTS version. For installing Volta we can go here and follow the steps after clicking out the Get Started button. It is very simple and easy to install. I use it on both Linux and Windows depending on if I am on the go or not.

TypeScript

Here is where we install TypeScript. Personally I use npm to download TypeScript globally which you can do by opening up your terminal and typing in this command:

$ npm i -g typescript

Quick note this is the shorthand version to install packages using npm you might also see or have seen it used this way:

$ npm install --global typescript

Use the version you like as they both do the same thing. I prefer the shorthand as it’s less to type.

I install TypeScript globally so that I can make sure that if I need to run the TypeScript compiler(tsc) I can do so freely without the need to install TypeScript in each and everyone of my projects before hand. Now there are some developers that prefer to only install packages in the project they are working in and that is totally ok. Use whichever way makes sense for you. If you want to install it per project follow these steps:

$ cd Desktop
$ mkdir typescript-stuff
$ cd typescript-stuff
$ npm init -y
$ npm install typescript

The following commands will change you to your Desktop directory, create a new directory(folder) on your desktop called typescript-stuff and then change into that directory. From there you initialize your project folder with npm and install TypeScript only to that project. So that if you run

$ tsc -v
// you should get back
$ Version 4.3.5 // at the time of this writing

These are all the tools that we will use for this project. To recap that will be

1. A code editor(VS Code, Atom, Sublime Text, etc)
2. Nodejs
3. TypeScript(installed globally or only in your project)
4. Terminal(PowerShell, Git Bash, Terminal, iTerm ,etc)

A quick note for Windows users, you can use the Command Prompt(cmd) but I highly advise against it. If you want to use a built in terminal use PowerShell most of the commands that I type will work with PowerShell. If it doesn’t work then do a quick google search. for example: “Powershell command for ls”.

Project Setup

If you installed TypeScript via a project basis instead of globally then you are already set to go. Skip this section as you already created your project folder and initialized the project with npm. If you didn’t then follow the steps below:

$ cd Desktop && mkdir typescript-stuff && cd typescript-stuff
$ npm init -y

Now you are caught up and we can proceed to configuring TypeScript for our project. Let’s continue.

TypeScript Setup

The TypeScript compiler has a lot of options that we will need and trying to make sure that pass them all as flags when we run our tsc command in the terminal is going to get very tedious, very fast. So instead what we can do is setup a file similar to a makefile for C/C++ development. If you haven’t used C/C++ before and don’t know what a makefile is and you’re curious I recommend a quick google search. Now then moving on. The TypeScript configs will be stored in a file called tsconfig.json. We can create this file by hand and manually type in all of the flags and special cases that we want to use for our project which is great if you know what all of them are. If you don’t, well, thankfully there is a way to create one in seconds with the most used settings already in place. Let’s do that now. Run the below command in your terminal from within the project directory

tsc --init

This is going to auto generate a file for us with basic configuration for TypeScript ready to go. If we look inside we will see that there are a bunch of different options that are commented out. We can uncomment ones that we need on a per project basis. But for the most part the most used ones are all there and ready to go. Alright now we are going to test this out. Let’s create a new file and call it cubes.ts. Inside of the file type:

function cubes(array: number[]) {
  const result = array.map(x => x * x * x);
  return result;
}

Next we will save the file and run tsc cubes.ts and we should now see a cubes.js file automatically created for us in our project. If you receive an error make sure that you have TypeScript installed either globally or in the project and try running the command again.

If we open the file we will see

function cubes(array) {
  var result = array.map(function (x) { return x * x * x; });
  return result;
}

This means that the compiler is working and that we are good to go. The transpilation process is working as you can see the type annotation was removed and now it looks like normal JavaScript which is what we want.

Let’s run another command like this:

tsc --target es6 cubes.ts

This is going to override the tsconfig.json file we have. The reason for this is flags passed in to the terminal command take higher preference over the config file. Now we should see that the cubes.js looks like this now:

function cubes(array) {
  const result = array.map(x => x * x * x);
  return result
}

Which looks just like our cubes.ts file but it’s missing the type annotation. We just compiled our TypeScript code, transpiled it, and spit it out as a different version of JavaScript that the browser knows and can actually use. We are able to use the latest and greatest features of the JavaScript language inside of Typescript and then compile it, transpile it and target any version of JavaScript we might need for whatever browser we need to support. Including Internet Explorer. Pretty neat right? Before we move on I suggest playing around with the target flag. Maybe do tsc --target es4 cubes.ts and see what the output of the .js file is.

The Real Project

Now that we have a little bit of the basics down we can start our project. We are going to create a small terminal application that by doing so will help you get familiar with TypeScript and also, for those that don’t use the terminal much, help you get familiar with using the terminal more. I am going to split this up into multiple articles so that the posts aren’t extremely long. So without further ado let’s get started.

Project Setup

We are going to be creating a todo application that will run in the command line/terminal. As mentioned before it will be a good exercise to bring all of the concepts together to better understand TypeScript as well as learn the command line/terminal. Let’s create the new project now in your terminal run these commands:

$ cd .. //only if you are still in the previous project
// Other wise we can open up our terminal and navigate to where we 
// want to store our projects, mine is the Desktop
$ cd Desktop
$ mkdir todo-app-ts
$ cd todo-app-ts
$ npm init -y // or you can use yarn init -y if you have yarn

The first command is only for those of you that still have your terminal open and inside of the previous projects directory. If not, and you had to open a new terminal then you will navigate to the Desktop and create a new directory to store the project in. We are going to use npm to initialize our project so we can start installing packages.

Create the TSC Config File

The compiler configuration we used previously could also work however I want to show you how you can manually create the file and add the options yourself so that you don’t have to rely on the tsc --init command every time. Especially if you only need a few options as is the case with this project.

Create a new file called tsconfig.json and inside add the options below:

{
  "compilerOptions": {
    "target": "es2020",
    "outDir": "./dist",
    "rootDir": "./src",
    "module": "commonjs"
  }
}

These settings will tell the compiler that we want to use the latest version of JavaScript. Our JavaScript files will be stored in a separate folder called dist so we can keep the TypeScript files separated so as to not get confused. We wont’ be editing the files in the ./dist folder directly as they will constantly be overwritten when we compile our TypeScript files. We are also telling the compiler to look for our .ts files in ./src folder. Last but not least we are using the commonjs way of handling our modules.

Adding Some TypeScript Code

As we saw previously in this post, TypeScript files have a .ts file extension. We are going to setup the structure of our app and write our first couple lines of code now.

• Create a folder called src
• Inside of src create a file called index.ts

Now inside of index.ts we will write the following code:

console.clear();
console.log("Jonathan's Awesome Todo List");

The code above will clear the console and then print out, in my case, Jonathan’s Awesome Todo List which will be the name of my todo app. Feel free to write whatever message here you want. It will be the name of your app.

Compilation and Execution

Now we can compile the code and then run it by doing the following:

$ tsc
$ node dist/index.js
// => Jonathan's Awesome Todo List

Conclusion

That’s it for this post. I don’t want it to get too long. In the next post we will flesh out some more of our Todo App. Some of the things to look forward to are:

• Creating the collection for the Todo Items
• Checking basic data model features
• providing access to items
• deleting completed tasks
• providing counts for items

See you in the next post.