Table of Contents
- Introduction
- Prerequisites
- Installing TypeScript Globally
- Setting Up a New TypeScript Project
- Understanding
tsconfig.json - Writing Your First TypeScript Program
- Compiling TypeScript to JavaScript
- Running the JavaScript Output
- Using TypeScript Locally in a Project (Best Practice)
- Setting Up TypeScript with Node.js
- Common Issues and Troubleshooting
- Conclusion
Introduction
Once you understand the advantages of using TypeScript over JavaScript, the next step is setting up a working TypeScript environment.
In this article, we will cover how to install TypeScript, configure your first project, understand key setup files, and compile and run your TypeScript code. Whether you are setting up a simple practice project or laying the foundation for a large-scale application, this guide will walk you through everything you need to get started the right way.
Prerequisites
Before you start installing TypeScript, make sure you have the following tools installed on your machine:
- Node.js (version 12 or later recommended)
Node.js comes bundled with npm (Node Package Manager), which you’ll use to install TypeScript.
To check if Node.js and npm are installed, run:
node -v
npm -v
If not installed, you can download Node.js from the official website.
Installing TypeScript Globally
The most straightforward way to install TypeScript is by using npm to install it globally. A global installation allows you to access the TypeScript compiler (tsc) from anywhere on your system.
To install TypeScript globally:
npm install -g typescript
Once installed, verify that TypeScript is installed correctly:
tsc -v
You should see a version number like 5.2.3, confirming that the installation was successful.
Setting Up a New TypeScript Project
Now, let’s create a simple TypeScript project from scratch.
- Create a new folder for your project:
mkdir typescript-first-project
cd typescript-first-project
- Initialize a Node.js project (optional but recommended):
npm init -y
This creates a basic package.json file, which helps manage dependencies later.
- Initialize a TypeScript configuration file:
tsc --init
This generates a tsconfig.json file, which controls how the TypeScript compiler behaves.
At this point, your folder structure should look like this:
/typescript-first-project
|-- package.json
|-- tsconfig.json
Understanding tsconfig.json
The tsconfig.json file is the heart of any TypeScript project. It defines the compiler options, files to include or exclude, and the overall behavior of the project.
Here’s a sample snippet from a freshly created tsconfig.json:
{
"compilerOptions": {
"target": "es5",
"module": "commonjs",
"strict": true,
"outDir": "./dist",
"rootDir": "./src",
"esModuleInterop": true
}
}
Key fields to note:
- target: The JavaScript version output (e.g.,
es5,es6,esnext). - module: Module system (e.g.,
commonjs,es6). - strict: Enables all strict type-checking options.
- outDir: Directory where compiled JavaScript files will be placed.
- rootDir: Directory containing the source TypeScript files.
You can customize these settings depending on the needs of your project.
Writing Your First TypeScript Program
Let’s create our first simple TypeScript file.
- Create a new folder called
src:
mkdir src
- Inside the
srcfolder, create a file namedindex.ts:
touch src/index.ts
- Open
index.tsand add the following code:
function greet(name: string): void {
console.log(`Hello, ${name}!`);
}
greet('World');
Here:
- We defined a function
greetthat takes astringtype argument. voidmeans the function does not return any value.
Compiling TypeScript to JavaScript
To convert your TypeScript code into JavaScript, run the TypeScript compiler:
tsc
This command reads the tsconfig.json file and compiles all .ts files found in the src folder into .js files in the dist folder.
After compilation, your folder structure should look like:
/typescript-first-project
|-- /src
| |-- index.ts
|-- /dist
| |-- index.js
|-- package.json
|-- tsconfig.json
Running the JavaScript Output
Now that you have compiled JavaScript, you can run the output using Node.js:
node dist/index.js
You should see the following output:
Hello, World!
Congratulations! You just created, compiled, and ran your first TypeScript program.
Using TypeScript Locally in a Project (Best Practice)
Instead of installing TypeScript globally, it’s often better to install it locally to each project. This ensures consistency across different machines and team members.
To install TypeScript as a development dependency:
npm install --save-dev typescript
You can then use npx to run the local version:
npx tsc
This approach is highly recommended for professional projects.
Setting Up TypeScript with Node.js
If you are using TypeScript with Node.js, you might also want to install type definitions for Node:
npm install --save-dev @types/node
This package provides type information for Node.js core modules like fs, path, and http, allowing you to use them in your TypeScript files without issues.
You may also want to modify your tsconfig.json to include "moduleResolution": "node" for smoother development.
Common Issues and Troubleshooting
Here are a few common problems you might face:
tsc: command not found: Ensure TypeScript is installed globally, or usenpx tsc.- Output files not generated: Check that your
tsconfig.jsonspecifies the correctrootDirandoutDir. - Node.js can’t find module: Ensure you run the compiled
.jsfiles, not.tsfiles. - Permission errors on Linux/macOS: You may need to prefix commands with
sudoif permission issues arise during installation.
Conclusion
Setting up TypeScript is a straightforward process once you understand the tools and workflow. By installing TypeScript, initializing a tsconfig.json file, writing your first TypeScript program, and compiling it to JavaScript, you have taken the crucial first steps into the world of statically typed JavaScript development.
Proper project setup lays the foundation for scalable, maintainable, and error-free applications. Whether you are building a small tool or a massive enterprise-grade application, investing a little time upfront in setting up TypeScript correctly will save you countless hours down the line.
