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

Install the typescript package locally with npm install --save-dev typescript, then compile files by running npx tsc or configure a 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.

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.

npm install -g typescript

One-off Execution with npx

Run TypeScript without modifying package.json by using npx, which fetches the package on-the-fly.

npx tsc --init

How the TypeScript Compiler Works

When you execute tsc, the binary shim at bin/tsc loads the compiled 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 calls the command-line parser in src/compiler/commandLineParser.ts. This module parses CLI flags and tsconfig.json to build a ParsedCommandLine configuration object.

Program Construction and Type Checking

The ParsedCommandLine feeds into 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 resolves symbols, performs type inference, and reports diagnostics.

The Emit Pipeline

Once validation completes, the emit pipeline in src/compiler/emit.ts transforms the Abstract Syntax Tree (AST) into JavaScript, declaration files (.d.ts), and source maps. The 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 file to define compiler options and project scope:

npx tsc --init

This creates a configuration file similar to:

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

Write and Compile Source Files

Create a TypeScript file at src/index.ts:

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

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

Compile the project using the locally installed compiler:

npx tsc

This reads tsconfig.json and emits ./dist/index.js. Execute the output with Node.js:

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 and the compiler modules.

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 and invokes the parser in src/compiler/commandLineParser.ts.
• The compiler pipeline involves program construction (src/compiler/program.ts), type checking (src/compiler/checker.ts), and emit (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. 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 file?

Yes. You can compile individual files by passing them directly to the compiler: npx tsc src/index.ts. However, using a 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, 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 file distributed with the npm package.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}