TypeScript

Getting Started with TypeScript (Hello World, Mac)

In this article, I'm going to show you how to install the tools to create and run a Hello World app using TypeScript.

Getting Started with TypeScript (Hello World, Mac)
Image generated using leonardo.a

In this article, I'm going to show you how to install the tools to create and run a Hello World app using TypeScript.

💡
These instructions were written and tested on a Mac.

Step 1. Install Node.js and npm

  • Open the Terminal application on your Mac

You can find it in the Applications > Utilities folder.

  • Check if you have Node.js and npm installed by typing the following commands in the Terminal:
node -v
npm -v
  • If Node.js and npm are not installed, you can download and install them from the Node.js website (https://nodejs.org/). Download the LTS version, which is recommended for most users.

Step 2. Create a project folder

In a terminal window, run the following commands:

mkdir -p ~/projects/typescript/typescript-101
cd ~/projects/typescript/typescript-101

Step 3. Initialize the project

Run this command to initialize a new project:

npm init -y

The -y flag instructs the init command to use the defaults for creating the package.json file. I'll show you how to modify it later.

Step 4. Install TypeScript as a dependency

You can either install TypeScript globally or as a project dependency.

It is recommended that you install it as a project dependency, like this:

npm install typescript --save-dev

This command installs TypeScript and adds it to the "devDependencies" section of your package.json file.

Step 5. Create a source folder

You can't run TypeScript directly using NodeJS. You have to "transpile" it to JavaScript.  The way that works is that you put your source TypeScript (*.ts) files in one folder, and define a second target distribution folder for the transpiler-generated JavaScript (*.js) files.

  • Create a new folder for your source by running this command:
mkdir src

You don't have to create the target folder, because the build command will do that for you.  I'll show you in the next step how to define the location.

Step 6. Configure TypeScript

The TypeScript transpiler (tsc) will look for a file called tsconfig.json in the root of your projects folder.

To create a simple config file that references your source and distribution files, do the following:

  • Make a new tsconfig.json file:
touch tsconfig.json
  • Edit the file, paste in the contents from this listing, and save the file:
{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts", "tests/**/*"],
  "exclude": ["node_modules"]
}

The important things to note are:

  • the rootDir path must match the location of your source folder (./src)
  • the outDir path defines the target folder for the build command to create
  • the output of the build command will be written to the outDir

Step 7. Create a source file

Create a new source file with a *.ts extension in the source src folder.

  • Run this command:
touch src/app.ts
  • Edit src/app.ts, paste in the contents from this listing, and save the file.
console.log("Hello, World!");

Step 8. Create a build command

To build the app you need to add a script command to call tsc.

  • Edit package.json
  • Add the build script to the scripts block, like this:
  "scripts": {
    "build": "tsc",
    "test": "echo \"Error: no test specified\" && exit 1"
  },

When the build command runs, it will transpile your code to ./dist/app.js.  So change the main line in package.json to this:

"main": "./dist/app.js",
  • Save the package.json file

Step 9. Run the build

You can now run the build with this command:

npm run build

Check the contents of the dist folder:

ls -ls dist

You should see a new file called app.js

You can view the contents of the file with this command:

cat dist/app.js

The contents are identical because there was nothing special about the source file to change.  In the next step, I will show you how to make a file that does need to change.

Step 10. Make the example TypeScript specific

We can modify the source file to require more than just copying the file and changing the extension.

  • Edit src/app.ts, replace the contents with the following, and change it:
let message: string = "Hello, World!";
console.log(message);
  • Run the build again:
npm run build
  • Examine the new distribution file.
cat dist/app.js

Note that the new version has been converted to JavaScript like this:

let message = "Hello, World!";
console.log(message);

Step 11. Add a start script

You should add a script to run the distributed file.

  • First run the file manually, like this:
node dist/app.js
  • Now edit package.json and create a start script for it in the scripts block, like this:
"scripts": {
  "build": "tsc",
  "start": "node dist/app.js",
  • Save the file, and run this start command like this:
npm start
💡
npm start is one of a few special scripts that don't require insertion of the run command

One problem is that you may make changes and forget to run the build command before running the npm start command.  

There is a trick that you can use to run the build command before the start command.   If you have a script called foo, and you create a second script called prefoo, the pre* script will always run before the other command that it is named after.

For example:

  • Edit package.json
  • Add this prestart script command and save the file:
"scripts": {
  "build": "tsc",
  "prestart": "npm run build",
  "start": "node dist/app.js",
  • Run the start command again:
npm start

If you look at the output you will see that it ran the build script command first, and then ran the start script command.

Example output

 npm start                                

> typescript-101@1.0.0 prestart
> npm run build


> typescript-101@1.0.0 build
> tsc


> typescript-101@1.0.0 start
> node dist/app.js

Hello, World!

Step 12. Add a clean command

The files in the dist folder don't need to be saved or checked in.  You can delete them at any time and recreate them using the build command.  It's good to do that from time to time to remove any outdated files.

You can create a clean command by doing the following:

  • Edit package.json
  • Add a clean script command like this:
  "scripts": {
    "build": "tsc",
    "prestart": "npm run build",
    "start": "node dist/app.js",
    "clean": "rm -rf dist",

You can run the clean command like this:

npm run clean

You will now see that the dist folder is gone:

ls -ls

Run the start command again to see that the dist folder is automatically recreated.

npm start

Step 13. Add the dist folder to .gitignore

Since you don't need to keep the dist files, you can add them to .gitignore with a line like this:

# Ignore built files
dist/**/*

To use that do the following:

  • Create a .gitignore file:
touch .gitignore

That file contains a line to ignore the dist folder.

Example

You can find an example repo for this project here:

An alternate way to generate tsconfig.json

To keep things simple I showed you how to hand-craft a tsconfig.json file. But you can also generate one with the tsc package using the init flag (tsc --init).

The problem is that since you installed tsc only as a local dependency you can't just call it from the command line and pass it arguments – unless you call it as a script command.  But you will then have to go in and edit the values (outDir, etc) and save the file again.

If you would like to try it that way, do the following:

  • Move the existing tsconfig.json to a backup file:
mv tsconfig.json back-tsconfig.json

Since the build script simply calls tsc ("build": "tsc",) you can use the special double dash flag to pass in the init flag to tsc, like this:

npm run build -- --init

This will generate a new tsconfig.json file.

  • Uncomment and/or edit the values to match the original and save the file
  • Here are the original values for reference:
{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts", "tests/**/*"],
  "exclude": ["node_modules"]
}
  • After updating the values and saving the file, run the clean and start scripts again to verify that everything still works with the alternate config:
npm run clean
npm start

init script

Since you will probably only do this once per package, it made no sense to create a separate init script for it.  But you could if you want to.  It would look like this:

"init": "tsc --init",

Then you would run it like this:

npm run init

Conclusion

In this article, you learned how to:

  • Setup a project to transpile TypeScript into JavaScript
  • Add scripts to manage the build process
  • Create a .gitignore file to filter out build files

References

Read next