Skip to main content

Setup

Let's get TypeScript running on your machine. By the end of this page you'll have a working project that compiles and runs.

Installing TypeScript​

TypeScript is an npm package. You can install it globally, but I recommend installing it per project so every project pins its own version (a TypeScript upgrade can introduce new errors, and you don't want one project's upgrade breaking another):

mkdir ts-playground
cd ts-playground
npm init -y
npm install --save-dev typescript

Verify it works:

npx tsc --version
# Version 5.x.x

tsc is the TypeScript compiler. npx runs the version installed in your project's node_modules.

Your First TypeScript File​

Create hello.ts:

function greet(name: string): string {
  return `Hello, ${name}!`;
}

const message = greet("Rizwan");
console.log(message);

Compile it:

npx tsc hello.ts

This produces hello.js next to it — plain JavaScript with the types stripped out:

function greet(name) {
  return "Hello, ".concat(name, "!");
}
var message = greet("Rizwan");
console.log(message);

Run it with Node:

node hello.js
# Hello, Rizwan!

Notice the output uses var and .concat() — by default tsc targets a very old JavaScript version. We fix that with a config file.

tsconfig.json​

Running tsc with individual files is fine for experiments, but real projects use a tsconfig.json that tells the compiler what to compile and how. Generate one:

npx tsc --init

That generates a file with dozens of commented-out options. Here's the config I actually start projects with:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true
  },
  "include": ["src"]
}

The options that matter​

  • target — which JavaScript version the output uses. ES2022 is safe for modern Node and browsers, and keeps your output readable (real const, template literals, async/await instead of transpiled workarounds).
  • module / moduleResolution — how imports are compiled and resolved. NodeNext matches how modern Node.js actually resolves modules.
  • rootDir / outDir — source lives in src/, compiled output goes to dist/. Keeps generated JS out of your source tree (add dist to .gitignore).
  • strict — turns on all strict type checks. Always enable this. Learning TypeScript without strict mode teaches you a weaker language; we'll break down the individual flags in the last doc of this section.
  • esModuleInterop — makes imports from CommonJS packages (most of npm) work the way you expect.
  • skipLibCheck — skips type-checking of .d.ts files inside node_modules. Big speed win, and third-party type errors aren't yours to fix anyway.
  • sourceMap — generates .js.map files so stack traces and debuggers point at your .ts source instead of the compiled output.

With the config in place, move your file to src/hello.ts and compile the whole project with just:

npx tsc
node dist/hello.js

No file arguments needed — tsc reads tsconfig.json and compiles everything under src.

Faster Development with tsx​

Compiling and then running gets old fast during development. Tools like tsx (my current pick) and ts-node run TypeScript directly in one step:

npm install --save-dev tsx

npx tsx src/hello.ts
# Hello, Rizwan!

Even better, watch mode re-runs on every save:

npx tsx watch src/hello.ts

I wire these into package.json scripts in every project:

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

The workflow becomes: npm run dev while developing, npm run build and npm start for production.

tsx runs your code even with type errors

tsx strips types and executes — it does not type-check. Your editor shows the red squiggles, and tsc is the final gate before shipping. A common CI setup runs tsc --noEmit (type-check only, no output files) on every push.

No install experiments

Want to try a snippet without setting anything up? The TypeScript Playground runs entirely in the browser and shows you the compiled JavaScript side by side. I use it constantly to test type behavior.

Recap​

  • npm install --save-dev typescript per project, run the compiler with npx tsc
  • tsconfig.json controls everything — start from the config above, keep strict: true
  • Source in src/, compiled output in dist/
  • Use tsx for a fast dev loop, tsc to type-check and build

Next up: the type system itself — annotations, inference, and the core types you'll use every day.

Last updated on