Quickstart

Get started with TypeScript in 5 minutes

This guide walks you through creating, compiling, and running your first TypeScript project.

Prerequisites

• Node.js 14.17 or higher installed
• TypeScript installed (see Installation)

Create Your First TypeScript File

1. Create a project directory

   mkdir my-typescript-app
   cd my-typescript-app
   
2. Initialize npm

   npm init -y
   

   This creates a package.json file for your project.

3. Install TypeScript

   npm install -D typescript
   
4. Create a TypeScript file

   Create a file called index.ts with the following content:

   index.ts

   function greet(name: string): string {
     return `Hello, ${name}!`;
   }
   
   const user = "TypeScript";
   console.log(greet(user));
   
   // This will cause a type error if uncommented:
   // console.log(greet(42));
   

   The : string syntax adds type annotations. TypeScript will check that you only pass strings to the greet function.

Initialize TypeScript Configuration

Create a tsconfig.json file to configure the TypeScript compiler:

npx tsc --init

This generates a tsconfig.json file with default settings and helpful comments. For this quickstart, create a minimal configuration:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Configuration options explained

• target: ECMAScript version for the output JavaScript (ES2020, ES2015, etc.)
• module: Module system to use (NodeNext, CommonJS, ES2015, etc.)
• outDir: Output directory for compiled JavaScript files
• rootDir: Root directory of TypeScript source files
• strict: Enable all strict type-checking options
• esModuleInterop: Enables better CommonJS/ES module interoperability
• skipLibCheck: Skip type checking of declaration files

Move your index.ts file into a src/ directory to match the configuration:

mkdir src
mv index.ts src/

Compile TypeScript

Compile your TypeScript code to JavaScript:

npx tsc

TypeScript will compile src/index.ts and output JavaScript to dist/index.js.

If compilation succeeds with no output, your code compiled successfully! TypeScript only shows messages for errors and warnings.

View the compiled output

Check the generated JavaScript:

cat dist/index.js

You’ll see something like:

dist/index.js

function greet(name) {
    return `Hello, ${name}!`;
}
const user = "TypeScript";
console.log(greet(user));

Notice how the type annotations have been removed - they’re only used during compilation for type checking.

Run Your Code

Execute the compiled JavaScript:

node dist/index.js

Output:

Hello, TypeScript!

Watch Mode

During development, use watch mode to automatically recompile when files change:

npx tsc --watch

You’ll see output like:

[12:00:00 AM] Starting compilation in watch mode...

[12:00:01 AM] Found 0 errors. Watching for file changes.

Now TypeScript will automatically recompile whenever you save changes to your .ts files.

Press Ctrl+C to stop watch mode.

Type Checking in Action

Let’s see TypeScript’s type checking in action. Add this code to src/index.ts:

src/index.ts

function add(a: number, b: number): number {
  return a + b;
}

console.log(add(5, 10));        // Works fine
console.log(add("5", "10"));    // Type error!

Compile again:

npx tsc

You’ll see a type error:

src/index.ts:8:17 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

8 console.log(add("5", "10"));
                  ~~~

Found 1 error in src/index.ts:8

This is TypeScript preventing a potential runtime bug at compile time!

Common Compiler Options

Useful tsc command-line options:

Check types without emitting

npx tsc --noEmit

npx tsc src/index.ts

npx tsc --version

npx tsc --help

npx tsc --showConfig

Using with ts-node

For running TypeScript directly without compiling first, install ts-node:

npm install -D ts-node

Run TypeScript files directly:

npx ts-node src/index.ts

Output:

Hello, TypeScript!

ts-node is great for development but not recommended for production. Always compile to JavaScript for production deployments.

Project Structure

Your project should now look like this:

my-typescript-app/
├── node_modules/
├── dist/
│   └── index.js
├── src/
│   └── index.ts
├── package.json
├── package-lock.json
└── tsconfig.json

Add Build Scripts

Update package.json to add convenient build scripts:

package.json

{
  "name": "my-typescript-app",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch",
    "start": "node dist/index.js",
    "dev": "ts-node src/index.ts"
  },
  "devDependencies": {
    "typescript": "^6.0.0",
    "ts-node": "^10.9.0"
  }
}

Now you can use:

Build

npm run build

npm run watch

npm start

npm run dev

Next Steps

tsconfig.json

Deep dive into compiler configuration options

Compiler

Learn about the TypeScript compiler

Module Resolution

Understand module resolution and imports

CLI Reference

Complete command-line interface documentation

Additional Resources

• TypeScript Handbook
• TypeScript Playground
• TypeScript GitHub
• Community Discord