Set Up TypeScript on macOS: Node.js, npm, tsc and a first project

What you need before starting

TypeScript is source code that a compiler checks and normally turns into JavaScript. For this terminal-based example, Node.js runs the resulting JavaScript and npm installs the TypeScript compiler as a project dependency. Node.js and npm are tools for this workflow; they are not part of the TypeScript language.

First install a currently supported Node.js LTS release for your operating system using the linked Codectionary guide and the official Node.js download page. The installation normally includes npm. Open a new terminal after installing, then check that both commands report versions. The exact version changes over time; a project may also state a required Node range in package.json.

Install Node.js on macOS

Follow the macOS Node.js guide for the current supported LTS release and a suitable installation method for your Mac. Quit and reopen Terminal after installing. Verify that Node and npm are both available before making the project.

Terminal: check the prerequisites

node --version
npm --version

Install Node.js on macOS

Create a local project

Run these commands in a folder where you can create files. mkdir creates a new directory, and cd enters it. npm init -y writes a starter package.json without asking interactive questions. Review its name and other defaults later; it is the manifest for this project, not a TypeScript source file.

npm install --save-dev typescript adds the compiler to devDependencies in package.json and updates package-lock.json. A local dependency lets the project record its compiler version. npx tsc --version checks the local compiler that the following commands will use. You do not need to install TypeScript globally.

Create the project and install TypeScript locally

mkdir typescript-start
cd typescript-start
npm init -y
npm install --save-dev typescript
npx tsc --version

Create your first .ts file

Create a folder named src inside typescript-start. In a text editor, save the code below as src/hello.ts. The : string annotations tell TypeScript that greet receives and returns text. The call passes "TypeScript", and console.log writes the returned greeting when the resulting JavaScript runs.

Use the exact .ts extension, not hello.ts.txt. Keep the terminal inside typescript-start: the next commands look for package.json, tsconfig.json and src/hello.ts there.

Create the source folder

mkdir src

Save as src/hello.ts

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

console.log(greet("TypeScript"));

Initialise and review tsconfig.json

npx tsc --init creates a tsconfig.json in the current project. The generated defaults can change with the installed TypeScript version, so open the file and replace its contents with the small configuration below for this exercise. This is a Node command-line example; a browser or modern module-based application may need different module settings.

include chooses TypeScript files under src. rootDir and outDir keep the source in src and emitted JavaScript in dist. target selects the JavaScript language level; module: CommonJS fits the default npm package created by npm init -y, which has no "type": "module" field. strict enables stronger checks. noEmitOnError stops a failed compilation from writing new output, though it does not remove files emitted by an earlier successful build.

Create the configuration file

npx tsc --init

Replace the generated contents of tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "noEmitOnError": true
  },
  "include": ["src/**/*.ts"]
}

Check, compile and run

Run the noEmit command first. It reads the project from tsconfig.json, reports type errors and writes no JavaScript. If it succeeds, run the compiler without noEmit to create dist/hello.js. Then Node executes that JavaScript and prints Hello, TypeScript! in your terminal. TypeScript annotations are absent from the emitted file.

Try replacing greet("TypeScript") with greet(42), then run the noEmit command again. The checker should report a type mismatch; restore the string before compiling. Do not pass src/hello.ts as a separate command-line argument here: this example uses --project so the configuration and its include pattern are applied.

Check types without writing files

npx tsc --project tsconfig.json --noEmit

Compile and execute the JavaScript output

npx tsc --project tsconfig.json
node dist/hello.js

Common macOS setup problems

If the shell says command not found, reopen Terminal and inspect command -v node; a version manager may need to be initialised for your shell. If npm encounters a permissions error, work inside a folder you own and avoid using sudo for this project-local install.

If Node cannot find dist/hello.js, confirm your current directory with pwd, check the saved src/hello.ts filename, and read any compiler diagnostics. The --noEmit check does not create dist/hello.js.

Terminal: locate Node and the current project

command -v node
pwd

Where to go next

You now have a repeatable local workflow: edit src/hello.ts, check types, compile, then run dist/hello.js. A real application may add npm scripts and more source files, but the same distinction between checking and execution remains. npm and package.json are explained in the JavaScript project guide.

Syntax

npm install --save-dev typescript
npx tsc --project tsconfig.json
node dist/hello.js

Examples

A first TypeScript program

Save this as src/hello.ts; check and compile it, then run dist/hello.js with Node.js in Terminal.

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

console.log(greet("TypeScript"));

The function parameter and return type annotations ask the compiler to check that greet receives and returns a string. They do not remain in the emitted JavaScript.
The call greet("TypeScript") passes text, so it satisfies the declared parameter type. The template literal combines Hello, the supplied name and an exclamation mark.
console.log prints Hello, TypeScript! when Node runs dist/hello.js. The compiler checks the source first; Node executes the JavaScript that it emits.
Change the call to greet(42) and run the noEmit check to see a diagnostic. Restore the string before compiling and running the example.

Best practices

Use a supported Node.js LTS release and install TypeScript locally in each project.
Review the generated tsconfig.json before relying on its version-dependent defaults.
Run a noEmit type check separately when you need diagnostics without generated files.
Run and test the emitted JavaScript in the environment for which you built it.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook