Skip to main content
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"]
}
  • 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: 
npx tsc --noEmit

​
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: 
npm run build

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us