Running a TypeScript file means converting it to JavaScript first, then executing that JavaScript

TypeScript is a layer on top of JavaScript that adds type checking — a way to catch mistakes before your code runs. Your computer cannot run TypeScript directly. Instead, you need a tool that converts (or "compiles") your TypeScript into JavaScript, then runs that JavaScript file. The most common tool for this is Node.js, which is free software you install once and use to run JavaScript files from your command line.

The process has three steps: install Node.js, write or get a TypeScript file, then use the TypeScript compiler to convert it and Node.js to run the result. If you are working on a website project, your build tool (like Vite or Webpack) usually handles the conversion automatically in the background. But if you are learning TypeScript or running a standalone script, you will do this manually.

Key Takeaways

  • Node.js is the free software you need to run JavaScript and TypeScript files on your computer; read it from nodejs.org and install it once.
  • The TypeScript compiler (tsc) converts your .ts file into a .js file that Node.js can actually run.
  • You run commands in your terminal or command prompt, not by double-clicking files, because that is how you tell Node.js which file to execute.
  • If you are working inside a project folder with a package.json file, npm (which comes with Node.js) manages your tools and can run scripts with a single command.

Install Node.js and verify it works

Go to nodejs.org and read the LTS (Long Term Support) version for your operating system — Windows, macOS, or Linux. Run the installer and follow the prompts. This installs both Node.js (which runs JavaScript) and npm (a package manager that installs tools like the TypeScript compiler).

Open your terminal or command prompt and type node --version. You should see a version number like v20.10.0. If you see "command not found" or similar, Node.js did not install correctly or your terminal needs to be restarted. Type npm --version as well to confirm npm is working.

Install the TypeScript compiler globally or in your project

The TypeScript compiler is a tool called tsc that converts .ts files to .js files. You can install it globally (available everywhere on your computer) or inside a specific project folder. For learning, global installation is simpler.

In your terminal, type npm install -g typescript. The -g flag means "global". This downloads and installs tsc. Verify it worked by typing tsc --version. You should see a version number like Version 5.3.3.

If you are working inside a project folder instead, type npm install typescript --save-dev (without the -g). This installs TypeScript only for that project and records it in your package.json file so others can install the same version.

Create a TypeScript file and compile it

Create a new file with a .ts extension — for example, hello.ts. Write some TypeScript code in it. A straightforward example:

const message: string = "Hello, TypeScript"; console.log(message);

Save the file. Open your terminal, navigate to the folder where you saved hello.ts, and type tsc hello.ts. The TypeScript compiler reads hello.ts, checks for type errors, and creates a new file called hello.js in the same folder. If there are type errors, tsc will print them to your terminal and may not create the .js file.

Once hello.js exists, run it with node hello.js. You should see "Hello, TypeScript" printed to your terminal. That is your TypeScript file running.

Use npm scripts to compile and run in one command

If you are working in a project folder with a package.json file, you can set up npm scripts so you do not have to type two separate commands. Open package.json and find the "scripts" section. Add a line like this:

"scripts": {   "start": "tsc && node hello.js" }

Now type npm start in your terminal. npm will run tsc first (compiling your TypeScript), then run node hello.js (executing the result). The && means "do the second thing only if the first thing succeeded", so if tsc finds errors, node will not run.

You can name the script anything — "dev", "build", "run" — and create multiple scripts for different tasks. This is especially useful in larger projects where you might compile multiple files or run tests.

Watch mode: recompile automatically when you save

Typing tsc every time you change your code gets tedious. TypeScript has a "watch" mode that monitors your .ts files and recompiles them automatically whenever you save. Type tsc --watch (or tsc -w for short). Your terminal will say "Watching for file changes" and stay open. Every time you save a .ts file, tsc recompiles it when ready.

In another terminal window, you can then run node hello.js to see the updated result. Or add a watch script to package.json:

"scripts": {   "watch": "tsc --watch" }

Then type npm run watch to start watching. This is the workflow most TypeScript developers use during development.

Troubleshooting common errors

Command not found: tsc — Node.js or TypeScript did not install correctly. Restart your terminal and try tsc --version again. If it still fails, reinstall TypeScript with npm install -g typescript.

Error TS2322: Type 'X' is not assignable to type 'Y' — Your TypeScript code has a type mismatch. For example, you assigned a number to a variable declared as a string. Read the error message, find the line number it mentions, and fix the type. This is TypeScript working as intended — catching mistakes before runtime.

hello.js does not exist after running tsc — The compiler found errors and refused to create the file. Check your terminal output for error messages. Fix the TypeScript errors and run tsc again.

Node.js says "Cannot find module" — You are trying to run a file that imports another file that does not exist or is in the wrong location. Check that all imported files are in the right folder and spelled correctly.

Frequently Asked Questions

Do I have to use Node.js, or can I run TypeScript in the browser?

Node.js is for running TypeScript on your computer as a standalone script or server. Browsers run JavaScript directly, not TypeScript. If you are building a website, your build tool (Vite, Webpack, etc.) compiles TypeScript to JavaScript automatically, and the browser runs the JavaScript. For learning or scripts, Node.js is the standard choice.

What is the difference between tsc and ts-node?

tsc compiles TypeScript to JavaScript and stops. ts-node compiles and runs the JavaScript in one step, so you can type ts-node hello.ts instead of tsc hello.ts && node hello.js. ts-node is convenient for quick scripts but slower because it compiles every time you run it. Install it with npm install -g ts-node.

Can I run TypeScript without installing anything?

Online playgrounds like the TypeScript Playground (typescriptlang.org/play) let you write and run TypeScript in your browser without installing anything. This is good for learning or testing small snippets, but for real projects you need Node.js on your computer.

Why does my TypeScript file compile but the JavaScript does not run?

TypeScript only checks types; it does not catch logic errors. Your code might be syntactically correct (no type errors) but still have bugs. Check your terminal output for runtime errors from Node.js, and trace through your code to find the problem.