# How to Install and Run TypeScript Locally Using the TypeScript NPM Package

> Learn to install and run TypeScript locally using the npm package. Use npx tsc or a tsconfig json file for compilation and project settings.

- Repository: [Microsoft/TypeScript](https://github.com/microsoft/typescript)
- Tags: getting-started
- Published: 2026-02-14

---

**Install the `typescript` package locally with `npm install --save-dev typescript`, then compile files by running `npx tsc` or configure a [`tsconfig.json`](https://github.com/microsoft/TypeScript/blob/main/tsconfig.json) for project-wide settings.**

The TypeScript compiler is distributed as the `typescript` package on npm, providing the `tsc` command-line tool and all compiler APIs that power the language service. When you install and run TypeScript locally using the typescript npm package, you leverage the exact source code that drives the official TypeScript language service and Visual Studio Code integration. This guide demonstrates installation methods, compiler architecture, and practical usage based on the microsoft/TypeScript repository.

## Installation Methods for the TypeScript NPM Package

You can install TypeScript globally, locally per project, or run it on-demand without installation. Each method ultimately loads the same compiler logic from the `typescript` package, but local installation ensures version consistency across teams and CI pipelines.

### Local Project Installation (Recommended)

Install TypeScript as a development dependency to lock the compiler version to your project. This is the standard approach for reproducible builds.

```bash
npm install --save-dev typescript

```

After installation, the `tsc` binary is available in `./node_modules/.bin/tsc`, accessible via `npx tsc`.

### Global Installation

Install TypeScript globally to make `tsc` available on your system PATH for all projects. This is useful for quick prototyping or one-off scripts.

```bash
npm install -g typescript

```

### One-off Execution with npx

Run TypeScript without modifying [`package.json`](https://github.com/microsoft/TypeScript/blob/main/package.json) by using `npx`, which fetches the package on-the-fly.

```bash
npx tsc --init

```

## How the TypeScript Compiler Works

When you execute `tsc`, the binary shim at `bin/tsc` loads the compiled [`lib/tsc.js`](https://github.com/microsoft/TypeScript/blob/main/lib/tsc.js) and invokes the command-line interface. According to the microsoft/TypeScript source code, the compiler follows a pipeline architecture:

### Command Line Parsing

The entry point at [`src/compiler/tsc.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/tsc.ts) calls the **command-line parser** in [`src/compiler/commandLineParser.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/commandLineParser.ts). This module parses CLI flags and [`tsconfig.json`](https://github.com/microsoft/TypeScript/blob/main/tsconfig.json) to build a `ParsedCommandLine` configuration object.

### Program Construction and Type Checking

The `ParsedCommandLine` feeds into [`src/compiler/program.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/program.ts), which constructs a **Program** object containing source files and the type-checker. The **type checker** implementation in [`src/compiler/checker.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/checker.ts) resolves symbols, performs type inference, and reports diagnostics.

### The Emit Pipeline

Once validation completes, the **emit pipeline** in [`src/compiler/emit.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/emit.ts) transforms the Abstract Syntax Tree (AST) into JavaScript, declaration files ([`.d.ts`](https://github.com/microsoft/TypeScript/blob/main/.d.ts)), and source maps. The [`package.json`](https://github.com/microsoft/TypeScript/blob/main/package.json) in the repository declares the `tsc` and `tsserver` binaries that expose this functionality.

## Step-by-Step: Compiling TypeScript Locally

Follow these steps to compile TypeScript files after installing the package locally.

### Initialize Configuration

Generate a [`tsconfig.json`](https://github.com/microsoft/TypeScript/blob/main/tsconfig.json) file to define compiler options and project scope:

```bash
npx tsc --init

```

This creates a configuration file similar to:

```json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

```

### Write and Compile Source Files

Create a TypeScript file at [`src/index.ts`](https://github.com/microsoft/TypeScript/blob/main/src/index.ts):

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

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

```

Compile the project using the locally installed compiler:

```bash
npx tsc

```

This reads [`tsconfig.json`](https://github.com/microsoft/TypeScript/blob/main/tsconfig.json) and emits [`./dist/index.js`](https://github.com/microsoft/TypeScript/blob/main/./dist/index.js). Execute the output with Node.js:

```bash
node ./dist/index.js

```

**Output:**

```

Hello, World!

```

## Using the Compiler API Programmatically

For advanced use cases, import the **Compiler API** directly from the `typescript` package. This API lives in the same source tree as the CLI, specifically within [`src/services/typescriptServices.ts`](https://github.com/microsoft/TypeScript/blob/main/src/services/typescriptServices.ts) and the compiler modules.

```typescript
import * as ts from "typescript";

const source = "let x: number = 42;";
const result = ts.transpileModule(source, {
  compilerOptions: { module: ts.ModuleKind.CommonJS }
});

console.log(result.outputText);
// → "var x = 42;\n"

```

The `transpileModule` function provides a lightweight way to convert TypeScript to JavaScript without the full program construction overhead.

## Summary

- **Install locally** using `npm install --save-dev typescript` to ensure consistent compiler versions across development environments.
- The **binary shim** at `bin/tsc` loads [`lib/tsc.js`](https://github.com/microsoft/TypeScript/blob/main/lib/tsc.js) and invokes the parser in [`src/compiler/commandLineParser.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/commandLineParser.ts).
- The compiler pipeline involves **program construction** ([`src/compiler/program.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/program.ts)), **type checking** ([`src/compiler/checker.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/checker.ts)), and **emit** ([`src/compiler/emit.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/emit.ts)).
- Use **`npx tsc`** to run the locally installed compiler without referencing the full path to `node_modules`.
- Access the **Compiler API** via `import * as ts from "typescript"` for programmatic transpilation and custom tooling.

## Frequently Asked Questions

### What is the difference between `npm install typescript` and `npm install -g typescript`?

Installing with `--save-dev` (or `--save`) adds TypeScript to your project's `devDependencies`, ensuring all team members use the same version specified in [`package.json`](https://github.com/microsoft/TypeScript/blob/main/package.json). The global flag `-g` installs TypeScript system-wide, making `tsc` available on your PATH regardless of the current directory, but it can lead to version mismatches between projects.

### How does `npx tsc` know which version of TypeScript to use?

`npx` first looks for the `tsc` binary in the local `./node_modules/.bin` directory. If found, it executes that version; otherwise, it downloads the latest `typescript` package from the npm registry. This ensures you always use the project-specific version when running commands within a project directory.

### Can I use TypeScript without a [`tsconfig.json`](https://github.com/microsoft/TypeScript/blob/main/tsconfig.json) file?

Yes. You can compile individual files by passing them directly to the compiler: `npx tsc src/index.ts`. However, using a [`tsconfig.json`](https://github.com/microsoft/TypeScript/blob/main/tsconfig.json) file is recommended for projects because it centralizes compiler options, defines inclusion/exclusion patterns, and ensures consistent behavior across the command line, IDEs, and CI pipelines.

### Where is the `tsc` command defined in the TypeScript source code?

The `tsc` command entry point is implemented in [`src/compiler/tsc.ts`](https://github.com/microsoft/TypeScript/blob/main/src/compiler/tsc.ts), which orchestrates the command-line parser, program creation, and emit pipeline. The executable shim that Node.js calls when you run `tsc` is located at `bin/tsc` in the repository, which loads the compiled [`lib/tsc.js`](https://github.com/microsoft/TypeScript/blob/main/lib/tsc.js) file distributed with the npm package.