TypeScript 2 🔷 Setting Up the Development Environment - KandZ

Before writing any TypeScript, you need a working environment — Node.js, npm, the TypeScript compiler, and a code editor that understands the language. This is a one-time investment, but it’s the foundation everything else builds on. Get it right and every subsequent step is smooth; get it wrong and you’ll spend hours chasing phantom errors that have nothing to do with your code.

Key point: TypeScript’s environment has three layers — Node.js (the runtime that runs the tooling), the TypeScript compiler (which turns .ts into .js), and your editor (which surfaces errors as you type). All three need to be set up correctly. The compiler is what actually checks your types; the editor is just a convenient window into the same checks.

What you need

Four pieces, working together:

Node.js — the JavaScript runtime that runs the compiler, the package manager, and eventually your emitted JavaScript
npm — Node’s package manager; it installs TypeScript and every project dependency
TypeScript — the compiler itself, installed either globally or locally
An editor — VS Code is the standard choice, but any editor with TypeScript support works

You’ll also want a terminal — VS Code’s built-in terminal, iTerm, Windows Terminal, or whatever shell you prefer. The commands below work in bash, zsh, PowerShell, and cmd with minor path differences.

The chain is:

Node.js  →  npm  →  typescript (tsc)  →  your project

Each layer depends on the one above. Node brings npm. npm installs TypeScript. TypeScript compiles your code.

Why Node first: Node is the foundation for everything. Even if your TypeScript runs in the browser, the tooling runs on Node. The compiler, the build tools, the test runner — all Node programs. Install it first, and the rest follows.

Step 1 — Install Node.js

Download the LTS (Long-Term Support) version from https://nodejs.org/. LTS is the recommended track — stable, supported for years, and matched to what the ecosystem expects.

What gets installed:

node — the runtime
npm — the package manager

Verify:

node --version
npm --version

Both should print version numbers. If you see command not found, the installer’s PATH additions didn’t take — restart your terminal, or log out and back in.

Current minimum: TypeScript 5.x works on Node 14 and later. For new projects, use the current LTS — usually Node 20 or 22.

Version managers: If you work on multiple projects that need different Node versions, install a version manager.

macOS/Linux: nvm — curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
Windows: nvm-windows — a separate project with a similar interface

With nvm, you can switch versions per project:

nvm install 20
nvm use 20

Why LTS and not Current: The “Current” version has the newest features but is more likely to break tooling. LTS versions are tested against the entire ecosystem — the compiler, package managers, frameworks. For development work, LTS is almost always the right choice.

Step 2 — Decide: global or local TypeScript

TypeScript can be installed globally (available everywhere on your machine) or locally (per-project, in node_modules).

Global install:

npm install -g typescript

Use tsc from any directory:

tsc --version

Local install (recommended for projects):

npm install --save-dev typescript

Then run through npx or npm scripts:

npx tsc --version

Which to choose:

Approach	Best for
Global	Learning, quick scripts, one-off compilations
Local	Every real project — pinned versions, reproducible builds

Why local is preferred: Different projects may need different TypeScript versions. A project on TS 4.9 may not compile correctly with TS 5.4. Installing locally pins the version in package.json, so every developer and every CI run gets the same compiler. Global installs are convenient for learning but cause version drift in real projects.

Do both if you like: Install globally for one-off experiments, and install locally in every project for reproducible builds. They don’t conflict — inside a project, npx tsc uses the local version; outside, tsc uses the global one.

Why the shift to local matters: Before npm made this trivial, every language had a “system compiler” problem — one version for all projects, breaking when projects needed different versions. Node’s solution — per-project node_modules — solves it. The same pattern applies to TypeScript, ESLint, and every other tool.

Step 3 — Verify the compiler

If installed globally:

tsc --version

If installed locally:

npx tsc --version

Both print something like:

Version 5.4.5

If you see a version, the compiler is ready. If you see command not found or npx: command not found, the install didn’t complete — reinstall and check the PATH.

Check what the compiler can do:

tsc --help

Prints a list of flags. The most useful ones:

Flag	Purpose
`--init`	Create a `tsconfig.json`
`--watch`	Recompile on file change
`--noEmit`	Type-check only
`--project`	Use a specific `tsconfig.json`
`--version`	Show version
`--help`	Show help

Why verify: The compiler is the entire tool. If tsc --version works, you’re 90% set up. Everything after this is configuration and workflow.

Step 4 — Set up an editor

VS Code is the default recommendation. Install it, then check that it’s using the right TypeScript version.

Check the version VS Code uses:

Open any .ts file
Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
Run TypeScript: Select TypeScript Version
Choose Use Workspace Version to use the project’s local TypeScript

VS Code ships with a bundled TypeScript version. For consistency, use the workspace version — the one installed in your project’s node_modules. That way, the editor and tsc agree on what’s an error.

Recommended extensions:

Extension	Purpose
ESLint	Lint TypeScript files
Prettier	Format code
Error Lens	Show errors inline
Path Intellisense	Autocomplete imports
TypeScript Vue Plugin	Vue + TS (if applicable)

None are strictly required. VS Code’s built-in TypeScript support is already excellent — the extensions just add convenience.

Other editors:

WebStorm — first-class TypeScript support out of the box
Neovim / Vim — via nvim-lspconfig and typescript-language-server
Sublime Text — via the LSP package

Any editor with the TypeScript Language Server installed will give you autocomplete, go-to-definition, and inline errors.

Why the workspace version: The bundled version is whatever shipped with VS Code. Your project may need a different version. Selecting the workspace version aligns the editor with your build — no more “the editor says it’s fine but tsc fails” surprises.

Step 5 — Create your first project

A TypeScript project needs a package.json and a tsconfig.json. The first tracks dependencies and scripts; the second configures the compiler.

Initialize npm:

mkdir my-project
cd my-project
npm init -y

The -y accepts all defaults. You’ll get a package.json with placeholder fields.

Install TypeScript locally:

npm install --save-dev typescript

Initialize the compiler configuration:

npx tsc --init

This creates a tsconfig.json with comments explaining every option. By default, it enables strict: true (good) and targets a modern JavaScript version.

A minimal tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Option	Purpose
`target`	JS version to emit
`module`	Module system for output
`moduleResolution`	How imports are resolved
`strict`	Enable all strict checks
`esModuleInterop`	Smooth interop with CJS
`skipLibCheck`	Skip `.d.ts` checking (faster)
`outDir`	Where compiled JS goes
`rootDir`	Where source lives

Add scripts to package.json:

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch",
    "typecheck": "tsc --noEmit"
  }
}

Write a file:

mkdir src
cat > src/index.ts << 'EOF'
function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet('Alice'));
EOF

Compile:

npm run build

Run the output:

node dist/index.js

You should see Hello, Alice!. The project is set up.

Why rootDir and outDir: By default, tsc emits .js files next to their .ts sources. For a clean project, keep sources in src/ and build output in dist/. That makes it clear what’s code and what’s generated — and keeps dist/ easily gitignored.

Step 6 — Gitignore and project files

A TypeScript project should ignore build output and dependencies in Git.

.gitignore:

node_modules/
dist/
*.tsbuildinfo
.DS_Store

Commit these:

package.json
package-lock.json
tsconfig.json
All .ts source files

Ignore these:

node_modules/ — regenerated from package.json
dist/ — regenerated by tsc
*.tsbuildinfo — incremental build cache

Never edit node_modules. Install dependencies with npm and let the compiler find them.

Why the lockfile matters: package-lock.json pins exact versions of every dependency, including transitive ones. Without it, two developers installing at different times can end up with different compilers. Commit it.

Step 7 — Running TypeScript without pre-compiling

Sometimes you want to run a .ts file directly — no build step, no dist/. Several tools make this possible.

tsx — the modern standard:

npm install --save-dev tsx
npx tsx src/index.ts

tsx uses esbuild to strip types fast and runs the result. It’s what ts-node used to be, but faster and with fewer configuration problems.

ts-node — the older standard:

npm install --save-dev ts-node
npx ts-node src/index.ts

ts-node compiles and runs in one step. Slower than tsx, more configuration-sensitive, but widely used.

Node’s native TypeScript support (experimental):

Recent Node versions can run .ts files directly:

node --experimental-strip-types src/index.ts

This strips types without transforming them — no enums, no namespace, no decorators. Useful for scripts, not for full projects yet.

Which to use:

Tool	Speed	Use case
`tsc` + `node`	Slower	Production builds
`tsx`	Fast	Development, scripts
`ts-node`	Medium	Legacy projects
Node native	Fast	Simple scripts, no fancy syntax

For most projects, tsx is the right choice for running during development, and tsc is the right choice for the production build. They can coexist.

Why not just use tsc for everything: tsc is a compiler, not a runner. Running tsc && node on every edit is slow. tsx skips the full compile and just strips types — much faster for the dev loop. The final build still goes through tsc.

Step 8 — Recommended project layout

A small, well-organized TypeScript project looks like this:

my-project/
├── node_modules/
├── src/
│   ├── index.ts
│   └── utils.ts
├── dist/
├── package.json
├── package-lock.json
├── tsconfig.json
├── .gitignore
└── README.md

As the project grows, src/ gets subfolders — components/, services/, utils/, types/. The build output in dist/ mirrors src/‘s structure.

What each file does:

File	Role
`package.json`	Dependencies and scripts
`package-lock.json`	Exact versions
`tsconfig.json`	Compiler configuration
`.gitignore`	What not to commit
`src/`	Source `.ts` files
`dist/`	Compiled `.js` output
`node_modules/`	Installed packages

Why this layout: It separates source from build output, keeps dependencies out of version control, and matches what virtually every TypeScript project looks like. Learning the shape once means you can navigate any project.

Global vs local — a concrete comparison

Global install:

npm install -g typescript
tsc --version   # 5.4.5

Problems: every project uses the same version. If one project was written for 4.9, it may not compile cleanly with 5.4.

Local install:

cd my-project
npm install --save-dev typescript
npx tsc --version   # uses this project's version

Advantages: each project pins its own version. Upgrading one project doesn’t break another.

Both together:

tsc (global) for quick scripts you run outside any project
npx tsc (local) for real projects

The global compiler never sees a project with a local one — npx prefers the local version automatically.

Why this matters: Version drift is the most common cause of “it works on my machine.” Pinning per-project eliminates it. When the whole team installs from the same package-lock.json, they get identical compilers.

A full example

Setting up a project from zero.

# ============================================
# PART 1: CREATE THE DIRECTORY
# ============================================

mkdir ts-demo
cd ts-demo

# ============================================
# PART 2: INITIALIZE NPM
# ============================================

npm init -y
# Wrote to package.json

# ============================================
# PART 3: INSTALL TYPESCRIPT
# ============================================

npm install --save-dev typescript
# added 1 package

# ============================================
# PART 4: CREATE TSCONFIG
# ============================================

npx tsc --init
# Created tsconfig.json

# ============================================
# PART 5: ADD SCRIPTS
# ============================================

# Edit package.json to add:
#   "build": "tsc"
#   "watch": "tsc --watch"
#   "typecheck": "tsc --noEmit"

# ============================================
# PART 6: WRITE A PROGRAM
# ============================================

mkdir src
cat > src/index.ts << 'EOF'
interface User {
  id: number;
  name: string;
}

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

const alice: User = { id: 1, name: 'Alice' };
console.log(greet(alice));
EOF

# ============================================
# PART 7: BUILD
# ============================================

npm run build
# dist/index.js created

# ============================================
# PART 8: RUN
# ============================================

node dist/index.js
# Hello, Alice (id 1)!

# ============================================
# PART 9: WATCH MODE
# ============================================

npm run watch
# Watching for file changes.

# Edit src/index.ts in another terminal
# → dist/index.js updates automatically

# ============================================
# PART 10: TYPE-CHECK ONLY
# ============================================

npm run typecheck
# (no output — no errors)

# ============================================
# PART 11: RUN DIRECTLY WITH TSX
# ============================================

npm install --save-dev tsx
npx tsx src/index.ts
# Hello, Alice (id 1)!

# ============================================
# PART 12: ADD .gitignore
# ============================================

cat > .gitignore << 'EOF'
node_modules/
dist/
*.tsbuildinfo
EOF

Quick Reference

Required Tools

Tool	Purpose	Install
Node.js	Runtime for tooling	nodejs.org (LTS)
npm	Package manager	Ships with Node
TypeScript	Compiler	`npm i -D typescript`
VS Code	Editor	code.visualstudio.com

Install Commands

Command	Purpose
`npm install -g typescript`	Global install
`npm install --save-dev typescript`	Local install
`npm install --save-dev tsx`	Fast runner
`npm install --save-dev ts-node`	Older runner

Compiler Commands

Command	Purpose
`tsc --version`	Show version
`tsc --init`	Create `tsconfig.json`
`tsc`	Compile per config
`tsc file.ts`	Compile a single file
`tsc --watch`	Watch and rebuild
`tsc --noEmit`	Type-check only
`tsc --help`	Show help

Running Without Compiling

Tool	Command
`tsx`	`npx tsx src/index.ts`
`ts-node`	`npx ts-node src/index.ts`
Node native	`node --experimental-strip-types src/index.ts`

Global vs Local

Aspect	Global	Local
Install	`npm i -g typescript`	`npm i -D typescript`
Command	`tsc`	`npx tsc`
Version	One for all projects	Per project
Reproducible	❌	✅
Recommended	For learning	For projects

Project Layout

Path	Contents
`src/`	`.ts` sources
`dist/`	Compiled `.js`
`node_modules/`	Dependencies
`package.json`	Deps + scripts
`package-lock.json`	Exact versions
`tsconfig.json`	Compiler config
`.gitignore`	Ignored files

npm Scripts

Script	Command
`build`	`tsc`
`watch`	`tsc --watch`
`typecheck`	`tsc --noEmit`
`dev`	`tsx src/index.ts`

tsconfig Essentials

Option	Recommended
`target`	`ES2022`
`module`	`ESNext` or `NodeNext`
`moduleResolution`	`Bundler` or `NodeNext`
`strict`	`true`
`esModuleInterop`	`true`
`skipLibCheck`	`true`
`outDir`	`dist`
`rootDir`	`src`

Best Practices

✅ Do This:

# Install Node LTS
# Use nvm for multi-project work
nvm use 20                                          # ✅

# Install TypeScript locally in every project
npm install --save-dev typescript                   # ✅

# Use npx to run the local compiler
npx tsc --version                                   # ✅

# Commit tsconfig.json and package-lock.json
git add tsconfig.json package-lock.json             # ✅

# Keep source in src/, output in dist/
# Both in tsconfig and .gitignore                    # ✅

# Enable strict mode
"strict": true                                      # ✅

# Use tsx for the dev loop
npm install --save-dev tsx                          # ✅

# Type-check in CI
npx tsc --noEmit                                    # ✅

# Select the workspace TypeScript in VS Code
# Command Palette → TypeScript: Select Version       # ✅

❌ Don’t Do This:

# Don't rely on global TypeScript in real projects
tsc                                                 # ⚠️  version drift

# Don't commit node_modules or dist
git add node_modules dist                           # ❌

# Don't edit node_modules by hand
nano node_modules/typescript/...                    # ❌

# Don't skip the lockfile
# Remove package-lock.json                          # ❌

# Don't run tsc on every edit in dev
tsc && node dist/index.js                           # ⚠️  slow — use tsx

# Don't disable strict mode permanently
"strict": false                                     # ⚠️  temporary at best

# Don't mix global and local configs
# Global tsc using project tsconfig                  # ⚠️  use npx

# Don't install Node "Current" for stable work
# Download the LTS version                           # ✅

Common Pitfalls

Pitfall	Problem	Solution
`tsc: command not found`	Not installed or not on PATH	Reinstall, check PATH
Global vs local mismatch	Different versions	Use `npx tsc` in projects
Editor uses bundled version	Editor disagrees with build	Select workspace version
No `tsconfig.json`	No project settings	Run `tsc --init`
`tsc` emits next to source	Messy project	Set `outDir` and `rootDir`
Forgetting `--save-dev`	TS in production deps	Always use `--save-dev`
Running `.ts` with `node`	Syntax error	Use `tsx` or compile first
Missing lockfile	Version drift	Commit `package-lock.json`
`node_modules` committed	Huge repo	Add to `.gitignore`

Real-World Examples

1. Check Node

node --version

2. Check npm

npm --version

3. Install TypeScript globally

npm install -g typescript

4. Install TypeScript locally

npm install --save-dev typescript

5. Check the compiler

npx tsc --version

6. Initialize a project

npm init -y
npx tsc --init

7. Create a source file

mkdir src
echo 'console.log("hi")' > src/index.ts

8. Compile

npx tsc

9. Run the output

node dist/index.js

10. Watch mode

npx tsc --watch

11. Type-check without emitting

npx tsc --noEmit

12. Run directly with tsx

npx tsx src/index.ts

13. Run directly with ts-node

npx ts-node src/index.ts

14. Add a build script

"scripts": {
  "build": "tsc",
  "watch": "tsc --watch",
  "typecheck": "tsc --noEmit"
}

15. Ignore build artifacts

node_modules/
dist/
*.tsbuildinfo

16. Select workspace TypeScript in VS Code

Command Palette → TypeScript: Select TypeScript Version → Use Workspace Version

17. Version manager

nvm install 20
nvm use 20

18. Check which tsc you’re using

which tsc    # or `where tsc` on Windows

19. Check project TypeScript version

npx tsc --version

20. Create an empty tsconfig

npx tsc --init --rootDir src --outDir dist

Visual: The Toolchain

┌──────────────────────────────────────────────┐
│  Node.js                                     │
│       │                                      │
│       ▼                                      │
│  npm                                         │
│       │                                      │
│       ▼                                      │
│  typescript (tsc)                            │
│       │                                      │
│       ▼                                      │
│  Your project                                │
│                                              │
│  Each layer depends on the one above         │
│                                              │
└──────────────────────────────────────────────┘

Visual: Global vs Local

┌──────────────────────────────────────────────┐
│  Global TypeScript                           │
│                                              │
│  /usr/local/lib/node_modules/typescript     │
│                                              │
│  Command: tsc                                │
│  One version for all projects                │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Local TypeScript                            │
│                                              │
│  ./node_modules/typescript                   │
│                                              │
│  Command: npx tsc                            │
│  Per-project version                         │
│  Pinned in package.json                      │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Inside a project:                           │
│                                              │
│  npx tsc  → uses LOCAL version               │
│  tsc      → uses GLOBAL version              │
│                                              │
│  Prefer npx in projects                      │
│                                              │
└──────────────────────────────────────────────┘

Visual: Compile Pipeline

┌──────────────────────────────────────────────┐
│  src/index.ts                                │
│                                              │
│  interface User { ... }                      │
│  function greet(u: User): string { ... }     │
│                                              │
└──────────────────────────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────┐
│  tsc                                         │
│                                              │
│  • Type-check                                │
│  • Transform syntax                          │
│  • Erase types                               │
│  • Emit to dist/                             │
│                                              │
└──────────────────────────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────┐
│  dist/index.js                               │
│                                              │
│  function greet(u) { ... }                   │
│                                              │
│  (plain JavaScript)                          │
│                                              │
└──────────────────────────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────┐
│  node dist/index.js                          │
│                                              │
│  → Runs in the JS runtime                    │
│                                              │
└──────────────────────────────────────────────┘

Visual: Dev vs Build Loop

┌──────────────────────────────────────────────┐
│  Development loop (tsx)                      │
│                                              │
│  Edit .ts file                               │
│       │                                      │
│       ▼                                      │
│  tsx strips types, runs immediately          │
│                                              │
│  Fast, no dist/ output                       │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Build loop (tsc)                            │
│                                              │
│  Edit .ts file                               │
│       │                                      │
│       ▼                                      │
│  tsc full type-check + emit                  │
│                                              │
│  Slower, produces dist/ for deployment       │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  CI (tsc --noEmit)                           │
│                                              │
│  Type-check only, no output                  │
│                                              │
│  Fast, catches errors before merge           │
│                                              │
└──────────────────────────────────────────────┘

Visual: Project Structure

my-project/
├── node_modules/          ← installed deps (ignored)
├── src/                   ← your .ts sources
│   ├── index.ts
│   └── utils.ts
├── dist/                  ← compiled .js (ignored)
│   ├── index.js
│   └── utils.js
├── package.json           ← deps + scripts
├── package-lock.json      ← exact versions
├── tsconfig.json          ← compiler config
├── .gitignore             ← ignored paths
└── README.md

Visual: Editor-Build Alignment

┌──────────────────────────────────────────────┐
│  VS Code bundled TS                          │
│                                              │
│  Ships with VS Code                          │
│  May not match project                       │
│  → "editor says OK, tsc fails"               │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Workspace TS                                │
│                                              │
│  From node_modules/typescript                │
│  Matches what the build uses                 │
│  → editor and tsc agree                      │
│                                              │
│  Select via:                                 │
│  Command Palette → TS: Select Version        │
│                                              │
└──────────────────────────────────────────────┘

Summary

Concept	Meaning
Node.js	Runtime for tooling and the compiler
npm	Package manager — installs TypeScript
TypeScript compiler	`tsc` — checks and emits JavaScript
Local install	Per-project, pinned in `package.json`
Global install	System-wide, for quick scripts
`tsconfig.json`	Compiler configuration
`package.json`	Dependencies and scripts
`package-lock.json`	Exact dependency versions
`tsx`	Fast runner for dev
`ts-node`	Older runner
VS Code workspace TS	Match editor and build versions

Key takeaways:

Node.js LTS is the foundation — install it first
npm ships with Node — no separate install
Install TypeScript locally in every project (--save-dev)
Use npx tsc inside projects to run the local compiler
tsconfig.json configures the compiler — strict: true is the recommended baseline
Keep source in src/ and build output in dist/ — both in tsconfig and .gitignore
Commit package.json, package-lock.json, and tsconfig.json; ignore node_modules/ and dist/
Use tsx for fast dev runs, tsc for production builds, tsc --noEmit for CI type-checks
Set VS Code to use the workspace TypeScript version so the editor and build agree
Version managers (nvm) help with multi-project work
Verify the setup with node --version, npm --version, npx tsc --version

Remember: The environment is a one-time investment. Install Node LTS, add TypeScript locally to each project, configure tsconfig.json, ignore the generated folders, and make the editor match the build. After that, everything is TypeScript — write .ts, run with tsx for dev, compile with tsc for production. The toolchain gets out of your way, and you focus on the code.

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!