Setting up a TypeScript project

From an empty folder to a checked project

So far, TypeScript has run inside this page. To use it for your own work, you set up a project: a folder on your computer with the compiler installed and a file of settings. This lesson builds one for a small shop. Here is the only code it has, a cart that adds up two prices:

1type CartItem = { name: string; price: number };2 3const cart: CartItem[] = [4  { name: "Tea", price: 3 },5  { name: "Cake", price: 4 },6];7 8let total = 0;9for (const item of cart) {10  total += item.price;11}12console.log(`Total: ${total}`);

Line 1 says what a cart item is: a name that is text and a price that is a number. Lines 3 to 6 make a cart of tea and cake. Lines 8 to 11 add up the prices, and line 12 prints Total: 7. There are no errors. The rest of this lesson is about everything around this file: how to install the compiler, how to tell it what to do, and where to run it.

When the project is set up, the folder looks like this:

shop/
  package.json
  tsconfig.json
  src/
    cart.ts
  dist/
    cart.js

• package.json lists the packages the project uses, including typescript. (The npm & package.json lesson explains this file.)
• tsconfig.json holds the compiler's settings: how strict to be, which files to check, and where to write the JavaScript.
• src/cart.ts is the code you write. src is short for "source".
• dist/cart.js is the JavaScript the compiler writes. dist is short for "distribution": the files you hand to a browser or to Node.

Installing the compiler

You need Node.js, the program that runs JavaScript outside a browser. Installing it also installs npm, the tool that downloads packages. Open a terminal, the window where you type commands, and type these four lines:

mkdir shop
cd shop
npm init -y
npm install --save-dev typescript@5.9

• Line 1 makes a folder called shop, and line 2 moves into it.
• Line 3 makes a package.json. The -y answers "yes" to every question npm would ask.
• Line 4 downloads the typescript package into a folder called node_modules. The --save-dev option lists it as a dev dependency: something you need while you build, but the finished page doesn't. The @5.9 asks for version 5.9, the one this site checks its examples with, so what you see matches this lesson. Leave it out to get the newest version.

Here is the part of package.json the install added:

{
  "name": "shop",
  "version": "1.0.0",
  "devDependencies": {
    "typescript": "5.9"
  }
}

Lines 4 to 6 are the new part. "5.9" means "any 5.9 version". npm also adds a few fields that don't matter here, like a description and a license, which are left out above. Now check that the compiler is there:

npx tsc --version

Version 5.9.3

npx runs a command from the packages in this project. So npx tsc means "the tsc that belongs to this folder". It prints the version npm installed, here 5.9.3. A teammate who runs npm install on the same package.json gets a 5.9 version too, so everyone checks the code the same way.

You could install one copy for the whole computer with npm install -g typescript, and then type tsc on its own. Projects avoid it: that copy isn't written in package.json, and two projects might need different versions.

Most projects also give their commands short names, called scripts, in package.json. Inside a script you write tsc without npx, because npm already looks in the project's packages:

1{2  "name": "shop",3  "version": "1.0.0",4  "scripts": {5    "build": "tsc",6    "check": "tsc --noEmit"7  },8  "devDependencies": {9    "typescript": "5.9"10  }11}

Line 5 names tsc as the build script. Line 6 names tsc --noEmit as the check script. --noEmit means "check, but don't write any files". You run a script with npm run and its name:

npm run check
npm run build

The table below compares the ways to start the compiler. Read each row as: what you type, what runs, and when to use it.

tsconfig.json: the project's settings

tsc has dozens of options. Instead of typing them every time, you write them once in a file called tsconfig.json at the top of the project. TypeScript can write a starting file for you:

npx tsc --init

{
  // Visit https://aka.ms/tsconfig to read more about this file
  "compilerOptions": {
    // File Layout
    // "rootDir": "./src",
    // "outDir": "./dist",

    // Environment Settings
    // See also https://aka.ms/tsconfig/module
    "module": "nodenext",
    "target": "esnext",
    "types": [],
    // For nodejs:
    // "lib": ["esnext"],
    // "types": ["node"],
    // and npm install -D @types/node

    // Other Outputs
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // Stricter Typechecking Options
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // Style Options
    // "noImplicitReturns": true,
    // "noImplicitOverride": true,
    // "noUnusedLocals": true,
    // "noUnusedParameters": true,
    // "noFallthroughCasesInSwitch": true,
    // "noPropertyAccessFromIndexSignature": true,

    // Recommended Options
    "strict": true,
    "jsx": "react-jsx",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

A line starting with // is a comment: a note, or a setting that is switched off. Plain JSON doesn't allow comments, but tsconfig.json does. Every setting sits inside "compilerOptions", which starts on line 3. Line 36, "strict": true, is the most important one, and the next section is about it. The rest are choices for later lessons, and you can delete what you don't understand yet.

The shop project uses a much smaller file:

{
  "compilerOptions": {
    "target": "es2022",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

• Line 3, target, picks the edition of JavaScript tsc writes. es2022 is the 2022 edition, which every current browser and Node runs, so the output keeps const and let.
• Line 4 turns on strict checks.
• Line 5, rootDir, says the code lives in src. Line 6, outDir, says to write JavaScript into dist. So src/cart.ts becomes dist/cart.js.
• Line 8, include, lists the files that belong to the project: everything in src. It sits outside compilerOptions, because it says which files, not how to compile them.

The table below sums up the five settings. Read each row as: the setting, what it says, and its value in the shop.

tsc reads tsconfig.json only when you give it no file names. Try it: run the commands below in any order and watch the terminal and the list of files.

1{2  "compilerOptions": {3    "target": "es2022",4    "strict": true,5    "rootDir": "src",6    "outDir": "dist"7  },8  "include": ["src"]9}

$

Press npx tsc and dist/cart.js appears, with const and a first line of "use strict", which turns on JavaScript's strict mode. Then node dist/cart.js prints Total: 7; before the build, Node can't find the file. npx tsc --noEmit checks and writes nothing. And npx tsc src/cart.ts writes src/cart.js with var: with a file name, TypeScript 5.9 ignores tsconfig.json and uses its own defaults.

That last one surprises people, because nothing warns you. TypeScript 6.0 and later refuse instead, with error TS5112: "tsconfig.json is present but will not be loaded if files are specified on commandline". In any version, the fix is the same: run npx tsc with no file names.

Turning on strict checks

"strict": true is one switch for a whole group of stricter checks. Two of them matter right away. A parameter with no type, like price below, quietly gets the type any, which means "don't check this"; strict reports that as an error. And a value that might be undefined must be checked before you use it. Flip the switch and watch the errors:

1{2  "compilerOptions": {3    "strict": true4  }5}

1function lineTotal(price, quantity: number) {2//                 ^?3  return price * quantity;4}5 6const cart = [7  { name: "Tea", price: 3 },8  { name: "Cake", price: 4 },9];10const cake = cart.find((item) => item.name === "Cake");11console.log(lineTotal(cake.price, 2));

With strict on, TypeScript marks two lines. Line 1 gets Parameter 'price' implicitly has an 'any' type: "implicitly" means TypeScript chose any because you didn't write a type. Line 11 gets 'cake' is possibly 'undefined', because find gives back undefined when no item matches (Searching arrays covers find). With strict off, both errors disappear, but nothing changed in the code. The query on line 2 shows price is still any either way. Strict didn't make the code safer or riskier; it decided whether TypeScript tells you.

Turn strict on at the start of every new project. Turning it on later means fixing every error it finds at once. One more reason to write it: in TypeScript 5.9, strict is off unless tsconfig.json turns it on, and TypeScript 6.0 and later turn it on by default. Writing "strict": true makes the project behave the same in every version. A later lesson, Strict mode options, goes through every check strict turns on.

Running TypeScript in Node

There are two ways to run cart.ts in Node. The first is the one you've already used: build, then run the JavaScript.

npx tsc
node dist/cart.js

Line 1 checks the project and writes dist/cart.js. Line 2 runs that file and prints Total: 7.

The second is newer. Node 22.18 and later, and Node 23.6 and later, run a .ts file directly. (Node 22.6 to 22.17 need the option --experimental-strip-types.)

node src/cart.ts

Node does this with type stripping: it replaces every type with spaces and runs what's left. That's quick, but it skips two things. Node never checks the types, and it never reads tsconfig.json. Here is what that means for a cart with a mistake on line 5:

1type CartItem = { name: string; price: number };2 3const cart: CartItem[] = [4  { name: "Tea", price: 3 },5  { name: "Cake", price: "4" },6];7 8let total = 0;9for (const item of cart) {10  total += item.price;11}12console.log(`Total: ${total}`);

Total: 34

Run with Node prints Total: 34, with no warning. Check with tsc finds the bug. The message is in two parts: the first says what's wrong on line 5, and the indented part shows line 1, where price: number was written. Check, then run joins both commands with &&, so the code only runs when the check passes. The last button fixes line 5, and both commands succeed.

Because Node only removes types, it can't run TypeScript features that turn into new JavaScript code. The best-known one is an enum: a named list of values, like sizes, that the Enums lesson covers later. TypeScript has an option that reports these features before Node fails on them:

1enum Size {2  Small,3  Large,4}5console.log(Size.Large);

Lines 1 to 4 make an enum called Size, and line 5 prints Size.Large. This example turns on erasableSyntaxOnly, and TypeScript marks line 1 on purpose: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. "Erasable" means "can be removed without leaving anything behind". An enum can't: tsc turns it into JavaScript code, and that code prints 1. Node stops at line 1 instead:

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode

If you run .ts files with Node, add "erasableSyntaxOnly": true to tsconfig.json, and your editor will point these out as you type. If you need the full language in Node, or an older Node, a package called tsx runs TypeScript files:

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

Line 1 installs tsx as a dev dependency, and line 2 runs src/cart.ts with it. Like Node, it removes the types without checking them, so keep npx tsc --noEmit for checking.

Editors and the Playground

You don't need to run tsc to see errors while you write. Editors like VS Code have TypeScript built in. They ask it about every file you open, underline errors as you type, list them in the Problems panel, and show a type when you point at a name:

1const cart = [2  { name: "Tea", price: 3, quantity: 2 },3  { name: "Cake", price: 4, quantity: 1 },4];5const itemCount = cart.length;6//    ^?7console.log(itemCount);

Lines 1 to 4 make a cart with two items. Line 5 counts them. The query on line 6 shows what your editor shows when you point at itemCount: const itemCount: number. Line 7 prints 2. Point at cart on this page to see the type of the whole list.

Two details decide whether the editor and tsc agree:

• Both read the same tsconfig.json. Turn on strict, and the editor shows the new errors too.
• They can use different TypeScript versions. VS Code comes with its own copy. To use the project's, open a .ts file and run the command TypeScript: Select TypeScript Version, then choose Use Workspace Version.

One difference matters: the editor checks the files you have open. npx tsc --noEmit checks every file in the project, including ones nobody has opened today. That's why projects run it before every build.

When you only want to try an idea, you don't need a project at all. The TypeScript Playground on the TypeScript website runs the compiler in your browser. You type code on the left, and it lists the errors, shows the JavaScript it writes, and runs it. Its TS Config menu changes the settings, its version menu picks the TypeScript version, and Share gives you a link to send someone.

The checked examples on this site work the same way, and each one has its own settings. This one turns strict off, so it has no errors:

1function lineTotal(price, quantity) {2  return price * quantity;3}4console.log(lineTotal(3, 2));

Line 1 declares lineTotal with two parameters and no types. Line 4 calls it and prints 6. Press Pop out: the code opens in the site's editor with a tsconfig.json next to it, holding the example's settings:

{
  "compilerOptions": {
    "strict": false
  }
}

Change false to true on line 3 and go back to the code. Line 1 now has two errors, one for price and one for quantity, the same message you saw in the strict playground.

A checkout page project with Vite

Real frontend projects rarely start from an empty folder. A tool like Vite builds the starting files for you (the Bundlers & build tools lesson covers Vite). Its vanilla-ts template is a page written in TypeScript with no framework:

npm create vite@latest checkout -- --template vanilla-ts
cd checkout
npm install
npm run dev

Line 1 makes a folder called checkout from the template. The -- passes --template vanilla-ts on to Vite's setup tool. Line 3 installs the packages, TypeScript among them. Line 4 starts a local server and prints an address like http://localhost:5173 to open in your browser. The template comes with its own tsconfig.json. Here are the lines that matter now:

1{2  "compilerOptions": {3    "target": "es2023",4    "lib": ["ES2023", "DOM"],5    "moduleResolution": "bundler",6    "noEmit": true7  },8  "include": ["src"]9}

• Line 4, lib, lists the built-in things TypeScript knows about. "DOM" adds the browser's: document, buttons, inputs, and so on.
• Line 5, moduleResolution, tells TypeScript that a bundler like Vite will find the files your import lines name.
• Line 6, noEmit, means tsc never writes JavaScript in this project. Vite removes the types itself, file by file, so the page loads fast. tsc is there only to check.

Without "DOM" in lib, a checkout page's code can't even find the page:

1const quantityInput = document.createElement("input");2quantityInput.value = "2";3 4const quantity = Number(quantityInput.value);5console.log(`Cake x${quantity}: $${quantity * 4}`);

Line 1 makes an <input> box, and line 2 puts "2" in it. Line 4 turns the text into a number. Line 5 prints Cake x2: $8. This example sets lib to ["es2023"] alone, and TypeScript marks lines 1 and 5 on purpose: Cannot find name 'document', and then the same for console. Both come from the browser, and "DOM" is how TypeScript learns about them. The message even says what to do: Try changing the 'lib' compiler option to include 'dom'.

Because Vite doesn't check types, the template's scripts run both tools:

1{2  "scripts": {3    "dev": "vite",4    "build": "tsc && vite build",5    "preview": "vite preview"6  }7}

Line 3, npm run dev, starts Vite alone, for quick changes while you work; your editor shows the errors. Line 4, npm run build, runs tsc first. With noEmit in tsconfig.json, that's a check. If it finds an error, && stops the build, so a type error never reaches your users. Line 5 serves the built page so you can look at it. The table below lists which tools check types and which only remove them.

Common mix-ups

• "I should install TypeScript once for the whole computer." No. Install it in each project with npm install --save-dev typescript, so package.json records the version and everyone uses the same one.
• "npx tsc src/cart.ts uses my tsconfig.json." No. With a file name, TypeScript 5.9 skips tsconfig.json, and 6.0 and later stop with an error. Run npx tsc with no file names.
• "node cart.ts checks my types." No. Node removes the types and runs the code. Check with npx tsc --noEmit, or both at once with npx tsc --noEmit && node src/cart.ts.
• "--noEmit means tsc does nothing." No. It still checks every file and reports every error. It only skips writing JavaScript.
• "Strict is always on." No. In TypeScript 5.9 it's off unless tsconfig.json turns it on. Write "strict": true yourself so every version behaves the same.
• "No red underlines in my editor means the project has no errors." No. The editor checks the files you have open. npx tsc --noEmit checks them all.

Practice exercises

Some exercises are about files and commands, and some are TypeScript code. For the code ones, press Edit & run on the starter: the errors update as you type. Try a guess first, then use the hints.

{
  "name": "shop",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "check": "tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "5.9"
  }
}

npm run check

{
  "compilerOptions": {
    "target": "es2022",
    "strict": true,
    "rootDir": "src",
    "outDir": "public/js"
  },
  "include": ["src"]
}

public/js/cart.js

1function discounted(price, percent: number) {2  return price - (price * percent) / 100;3}4console.log(discounted(20, 10));

1function discounted(price: number, percent: number) {2  return price - (price * percent) / 100;3}4console.log(discounted(20, 10));

1const itemCount: number = "2";2console.log(itemCount * 3);3console.log(itemCount + 1);

1const itemCount: number = 2;2console.log(itemCount * 3);3console.log(itemCount + 1);

{
  "scripts": {
    "start": ""
  }
}

{
  "scripts": {
    "start": "tsc --noEmit && node src/cart.ts"
  }
}

npx tsc src/cart.ts

npx tsc

Check your understanding

For each question, ask which tool is doing the work, and whether it reads tsconfig.json, checks types, or only removes them. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Install TypeScript in each project with npm install --save-dev typescript, and run it with npx tsc or an npm script.
• tsconfig.json holds the settings. npx tsc with no file names reads it; with a file name, it doesn't.
• target, strict, rootDir, outDir, and include are enough to start a project.
• Turn on strict from the start. It reports values with no type and values that might be undefined.
• node file.ts removes types and runs the code without checking. Pair it with npx tsc --noEmit.
• Your editor checks open files as you type; tsc --noEmit checks every file. The Playground is for trying ideas with no setup.

Coming next: Your first typed program. You'll turn a plain JavaScript cart into TypeScript, read the compiler's errors, and fix them.