Chapter 1.2☕ 15 min read

Setup & Your First TS File

No kitchen, no biryani. No compiler, no TypeScript.

01Setup Kitchen Before Cooking

Imagine you want to cook a grand Hyderabadi biryani. You have the recipe, you have the ingredients, but — you have no kitchen, no stove, no utensils. That's exactly what writing TypeScript without a proper setup feels like. You can write .ts files all day long, but without the right tools installed and configured, nothing is going to run.

TypeScript is not something browsers or Node.js understand natively. They only speak JavaScript. So we need a compiler — a translator — that converts our TypeScript code into plain JavaScript. This compiler is called tsc, which stands for TypeScript Compiler. It reads your .ts files, strips out all the type annotations, and produces clean .js files that any JavaScript runtime can execute.

But tsc alone only compiles; it doesn't run your code. To actually execute TypeScript files directly during development, we use a tool called ts-node. Think of tsc as the stove that transforms raw ingredients into a cooked dish, and ts-node as the serving plate that lets you taste the dish immediately without waiting for the full plating process.

In this chapter, we'll install both tools, create our first .ts file, configure the project with tsconfig.json, and understand the common pitfalls that trip up every single beginner. By the end, your TypeScript kitchen will be fully operational and ready for serious cooking.

02Installing tsc and ts-node

Let's install the tools step by step. First, make sure you have Node.js installed on your machine — it's the foundation everything else builds upon. Open your terminal and run:

npm install -g typescript

This installs the TypeScript compiler (tsc) globally on your machine so you can use it from any directory. Verify the installation worked by running:

tsc --version

You should see something like Version 5.4.5 printed in your terminal. Next, install ts-node so we can run .ts files directly without manually compiling first every single time:

npm install -g ts-node

Now let's create a project folder and initialize it as a TypeScript project:

mkdir my-ts-project
cd my-ts-project
tsc --init

The tsc --init command creates a tsconfig.json file in your project root. This is the configuration file that tells the compiler exactly how to behave — what JavaScript version to target, how strict the type checking should be, where to find source files, and where to put the compiled output. Think of it as the recipe card for your kitchen: what temperature to set, what ingredients to use, what cooking style to follow.

Now create your very first TypeScript file called index.ts:

let message: string = "Hello from TypeScript!";
console.log(message);

Run it with:

ts-node index.ts

If you see Hello from TypeScript! printed on your screen, congratulations — your kitchen is alive! The ts-node tool internally compiles your TS code to JS and runs it with Node.js, all in a single step. During development, this is your best friend and saves enormous amounts of time. For production builds, you'll use tsc to compile and then run the output with plain node.

03tsconfig.json — The Constitution

When you ran tsc --init, it generated a tsconfig.json file with dozens of commented-out options. It can look overwhelming at first, but let's understand the most important ones. This file is the constitution of your TypeScript project — every single rule about how your code gets compiled lives here, and every team member follows the same rules because they share this file.

The most critical option is target. It tells the compiler which version of JavaScript to produce as output. For example:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

target: If you set it to "ES5", the compiler will produce old-school JavaScript that works even in Internet Explorer — lots of polyfills and verbose output. If you set it to "ES2022", it produces modern JavaScript with all the latest syntax features like optional chaining, nullish coalescing, and top-level await. Choose based on where your code will run — Node.js projects can comfortably use newer targets, while browser projects might need older ones for broader compatibility.

module: Defines the module system for the output. "commonjs" is for Node.js environments (using require() and module.exports), while "ESNext" or "ES2020" is for modern bundlers and browsers (using import and export).

strict: When set to true, it enables all strict type-checking options at once — noImplicitAny, strictNullChecks, strictFunctionTypes, and more. Always turn this on from the start. It's like wearing a seatbelt — feels uncomfortable at first, but saves you from catastrophic disasters down the road.

outDir: Specifies where the compiled JavaScript files should be placed. Keeping your source .ts files separate from the output .js files is crucial for project organization.

rootDir: Specifies where your TypeScript source files live. The compiler looks inside this directory to find all the code it needs to compile.

When you run tsc (without any filename), it reads tsconfig.json and compiles everything inside rootDir, outputting the results into outDir. This is the standard production workflow that every professional TypeScript project follows.

04The Trap — Running node index.ts

Here's the number one mistake every TypeScript beginner makes, without exception: they try to run a TypeScript file directly with Node.js.

node index.ts

This fails spectacularly with a syntax error. Why? Because Node.js does not understand TypeScript syntax like let x: number = 5. The : number part is a TypeScript-specific annotation, and Node.js chokes on it immediately — it's like someone trying to eat biryani with chopsticks. Wrong tool for the job, plain and simple.

The correct approach is one of two paths, depending on your situation:

Development path: Use ts-node index.ts — it compiles and runs in one step, perfect for quick iteration.
Production path: First compile with tsc, then run the JavaScript output with node dist/index.js.

Another extremely common trap: running tsc index.ts and then trying node index.ts instead of node index.js. The tsc compiler creates a .js file next to your .ts file (or in your outDir), but you keep trying to feed the original .ts file to Node. Always run the compiled output, not the source file.

A third sneaky trap: editing your .ts files but accidentally running the old stale .js output and then wondering why your changes aren't showing up. This happens more often than you'd think, especially when both files sit in the same directory. Always recompile after making changes, or use ts-node during development to avoid this confusion entirely.

The mental model is dead simple: .ts → (tsc) → .js → (node) → output. Never skip a step in production.

05Setup Cheatsheet

Here's your quick-reference cheatsheet for setting up a TypeScript project from absolute scratch. Bookmark this, screenshot it, tattoo it on your arm — you'll need it:

# Install TypeScript compiler globally
npm install -g typescript

# Install ts-node for direct execution during development
npm install -g ts-node

# Create a new project folder
mkdir my-project && cd my-project

# Generate tsconfig.json with default settings
tsc --init

# Create your first TypeScript file
echo 'let msg: string = "Hello TS!"; console.log(msg);' > index.ts

# Run directly in development (compile + execute in one step)
ts-node index.ts

# Compile all TS files to JavaScript (production build)
tsc

# Run the compiled JavaScript output (production)
node dist/index.js

Key tsconfig.json options to remember forever:

"target" — JavaScript version to output (ES5, ES2020, ES2022, etc.)
"module" — Module system (commonjs for Node, ESNext for browsers)
"strict" — Always set to true. No exceptions. No excuses.
"outDir" — Where compiled JS files get placed (e.g., "./dist")
"rootDir" — Where your TS source files live (e.g., "./src")

The golden rule, engraved in stone: .ts files go into the compiler, .js files come out, and only .js files run in Node.js or browsers. Never try to feed .ts directly to Node — it will not work. Use ts-node for development speed, and tsc plus node for production builds. That's the entire setup story in a nutshell.

Key Takeaways

TypeScript needs a compiler (tsc) to convert .ts files into .js files that Node.js and browsers can run.
ts-node lets you run .ts files directly during development — it compiles and executes in one step.
tsconfig.json is the project constitution — target, module, strict, outDir, and rootDir are the key options.
Never run `node index.ts` — Node.js cannot parse TypeScript syntax. Always compile first, then run the .js output.
The golden pipeline: .ts → (tsc) → .js → (node) → output. ts-node is the shortcut for development.

Previous1.1 — What is TypeScript & Why It Exists 📋 All Chapters Next Chapter1.3 — Primitive Types →