Why TypeScript, and Your First Project

You already know some JavaScript, or you are learning it. This series, "TypeScript From Zero to Confident", adds types to it one small step at a time. This first lesson does not teach many type rules yet. It sets up a working project, explains every line of a small config file, and shows you how to read the first error messages, so that the next lessons have a place to run.

If you want interview practice later, read Full-Stack Q&A, Lesson 3 for the common TypeScript questions and Frontend Depth, Lesson 4 for the advanced ones. This series builds the base under both.

Words used in this lesson

• A type is a label for what kind of value something is, such as string (text) or number.
• A type checker is a tool that reads your code and reports places where a value is used in a way its type does not allow. It does not run the code.
• A compiler turns code from one form into another. tsc is the TypeScript compiler. It checks types and can write out JavaScript.
• Transpiling means turning TypeScript into JavaScript. Here that mostly means deleting the types.
• Type erasure (or "type stripping") means the types are removed from the code and do not exist when the program runs.
• A runtime is the place where code runs, such as Node.js or the browser.
• tsconfig.json is the settings file that tells tsc which files to read and how strict to be.
• Strict mode (the strict option) is a group of checks that catch more mistakes. It is not the same as JavaScript's "use strict".

What TypeScript is, and what it is not

TypeScript is a superset of JavaScript. That means every valid JavaScript program is also a valid TypeScript program, and TypeScript adds more syntax on top: mainly the : type notes.

function greet(name: string): string {  return "Hello, " + name;}console.log(greet("Ada"));

The first : string says "the parameter is text"; the second says "the function returns text". I saved this as src/hello.ts and ran it:

$ node src/hello.tsHello, Ada

TypeScript is:

• A way to write down what shape your data has, so the editor and the compiler can warn you before you run anything.

TypeScript is not:

• A different language at runtime. The browser and Node never see types.
• A guard against bad data coming from outside. A JSON response from a server can say anything. The type checker cannot know. (Lesson 6 covers checking data at runtime.)
• A promise that nothing can go wrong. It finds one group of mistakes (wrong shapes, missing values, typos). Logic bugs stay.

Types are erased

Let us see this with our own eyes. First a file with types, src/erase.ts:

type Id = string | number;interface User { id: Id; name: string }const u: User = { id: 1, name: "Ada" };console.log(u);

I asked tsc to write the JavaScript (--noEmit false --rootDir src --outDir dist; more on these flags below) and printed the result, dist/erase.js:

const u = { id: 1, name: "Ada" };console.log(u);export {};

The type line and the interface line are gone. The : User note is gone. (The export {} line is how tsc marks the file as a module. It does nothing here.) That is erasure. The consequence is the most important idea in this lesson: a type can only protect you while tsc is checking. At runtime there is no User.

Here is a program where the types lie, src/rt.ts:

const data = JSON.parse('{"id": "abc"}') as { id: number };console.log(typeof data.id, data.id.toFixed(2));

tsc reported no errors. as { id: number } is a type assertion: you tell the checker "trust me, this is that shape". The checker believed it. Then I ran it:

$ node src/rt.tsTypeError: data.id.toFixed is not a function

The value was the text "abc", and text has no toFixed. The type said number and the data said string, and at runtime the data wins. Keep this in mind whenever you reach for as.

Setting up: three ways to run TypeScript

You need Node.js 22 or newer. Check with node -v. I used v22.22.0.

Make a folder and start a project:

mkdir hello-ts && cd hello-tsnpm init -ynpm install --save-dev typescript @types/node

typescript gives you the tsc command. @types/node gives TypeScript the type information for Node's own functions, such as process and fs (without it, TypeScript does not know what process is; there is an example below). Then open package.json and add "type": "module" so that .ts files may use import and export. Mine looked like this:

{ "name": "hello-ts", "private": true, "type": "module" }

(plus the devDependencies that npm added.) There are three tools to know. They do different jobs, and people mix them up.

1. tsc: the checker

npx tsc

With the tsconfig in the next section, a clean project prints nothing and exits with code 0. I made a wrong version of hello.ts that calls greet(42), and tsc printed:

src/bad.ts(5,19): error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

and exited with code 1. (npx runs a program that is installed in your project's node_modules.)

2. tsx: run it now

npm install --save-dev tsxnpx tsx src/hello.ts

tsx strips the types and runs the file. It also understands more TypeScript than Node does. It does not check types. I ran the bad greet(42) program with tsx:

$ npx tsx src/bad.tsHello, 42

No error. So tsx and tsc go together: tsx to run, tsc to check.

3. Node's built-in type stripping

Since Node v22.18.0 you can run a .ts file directly and no flag is needed (the Node docs list "type stripping is enabled by default" for that version, and I confirmed it on v22.22.0):

$ node src/hello.tsHello, Ada

Node deletes the types (it replaces them with spaces) and runs what is left. It does not type check, and it does not read tsconfig.json. The same bad program printed Hello, 42 under plain node.

Because Node only deletes, it cannot run TypeScript that needs to be rewritten into JavaScript. I tested an enum:

enum Color { Red, Green }console.log(Color.Green);

$ node src/enum.tsSyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode

npx tsx ran the same file and printed 1. A class parameter property (constructor(public name: string) {}, covered in Lesson 2) fails in the same way: TypeScript parameter property is not supported in strip-only mode. The Node docs name these as features that need transformation: enums, namespace with runtime code, parameter properties and import aliases. With node --experimental-transform-types they work, and Node prints an ExperimentalWarning. Decorators are not supported at all.

Two more rules from the Node docs, which I also hit:

• In an import, write the real file name with the .ts extension: import { x } from "./types.ts".
• Import types with the type keyword (details below). Otherwise Node tries to import something that does not exist at runtime.

A minimal tsconfig.json, line by line

tsc --init creates a starting file. In 7.0.2 it wrote module: nodenext, target: esnext, types: [], strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, verbatimModuleSyntax, isolatedModules, skipLibCheck and more, with comments. I wrote a smaller one by hand for this series:

{  "compilerOptions": {    "target": "es2022",    "module": "nodenext",    "strict": true,    "noUncheckedIndexedAccess": true,    "skipLibCheck": true,    "isolatedModules": true,    "verbatimModuleSyntax": true,    "erasableSyntaxOnly": true,    "allowImportingTsExtensions": true,    "noEmit": true,    "types": ["node"]  },  "include": ["src"]}

I used exactly this file for every example. Line by line:

• "target": "es2022". Which version of JavaScript the output may use. tsc also uses it to decide which built-in features (like Array.prototype.at) exist. Choose a version your runtime supports. Node 22 supports es2022 and newer.
• "module": "nodenext". How import and export work. nodenext follows Node's real rules: ES modules or CommonJS, decided by package.json "type" and by the file extension; relative imports need a file extension. It also sets moduleResolution (how TypeScript finds the file behind an import) to nodenext. I confirmed that with tsc --showConfig. If you use a bundler such as Vite, you would choose "module": "preserve" and "moduleResolution": "bundler" instead (Lesson 5).
• "strict": true. Turns on a family of checks. The most important ones: strictNullChecks (null and undefined are separate types, not allowed everywhere) and noImplicitAny (you may not leave a type out and get any by accident). Always use it for new code.
• "noUncheckedIndexedAccess": true. Not part of strict. When you read array[0] or object[key], the result type gets | undefined added, because the item might not be there. It is a little annoying and catches real bugs. I show an example below.
• "skipLibCheck": true. Do not type check the .d.ts files (type-only files) inside node_modules. Other people's libraries sometimes disagree with each other, and you cannot fix them. The default is false; I confirmed that in tsc --help --all. Skipping the check makes builds faster and removes noise. The cost is that a mistake in a library's own types is not reported.
• "isolatedModules": true. Makes TypeScript warn about code that a tool which processes one file at a time cannot handle. Tools such as tsx, esbuild, Babel and Node's stripping never see your other files, so they cannot know if User is a type or a value. This flag reports code that depends on that knowledge.
• "verbatimModuleSyntax": true. A strict rule: what you write in import and export is what is kept in the output. Imports that are only types must say type. This is easy for tools to follow, and it matches Node's stripping. Example below.
• "erasableSyntaxOnly": true. TypeScript refuses syntax that Node's stripping cannot run (enums, parameter properties, runtime namespaces). The flag is in the Node docs' recommended settings. It makes tsc tell you about the problem before Node does.
• "allowImportingTsExtensions": true. Lets you write from "./types.ts". TypeScript only allows this when it is not writing JavaScript, which is why noEmit is next.
• "noEmit": true. tsc only checks and does not write .js files. Another tool (Node, tsx, a bundler) runs the code.
• "types": ["node"]. Which global type packages to load. With ["node"], names like process are known. If you leave it out in 7.0.2, the list is empty. I tried "types": [] and a file that uses process:

src/proc.ts(1,13): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

• "include": ["src"]. Only look at files in src.

To write JavaScript files instead of only checking, remove noEmit and allowImportingTsExtensions and add "rootDir": "src" and "outDir": "dist". Without rootDir, 7.0.2 stops with error TS5011: The common source directory of 'tsconfig.json' is './src'. The 'rootDir' setting must be explicitly set ....

One more thing: if you run tsc src/main.ts while a tsconfig.json exists, it stops with error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error. Run npx tsc with no file names to use your config.

verbatimModuleSyntax in action

I made src/types.ts:

export interface User { id: number; name: string }export function makeUser(name: string): User { return { id: 1, name }; }

and a src/main.ts that imports both names the normal JavaScript way:

import { makeUser, User } from "./types.ts";

src/main.ts(1,20): error TS1484: 'User' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.

At runtime, Node has no User to import:

SyntaxError: The requested module './types.ts' does not provide an export named 'User'

The fix is to mark type-only names with type:

import { makeUser, type User } from "./types.ts";const u: User = makeUser("Ada");console.log(u.name);

This compiled cleanly, and node src/main.ts printed Ada.

If you forget the extension (from "./types"), tsc says:

src/main2.ts(1,26): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './types.js'?

(The .js hint is right if you build to JavaScript first. With the setup used here, write .ts.)

Re-exporting a type needs export type too. For export { User } from "./types.ts"; I got error TS1205: Re-exporting a type when 'verbatimModuleSyntax' is enabled requires using 'export type'. And the earlier enum Color file gives error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. under this config.

Reading your first compiler errors

An error from tsc has the same parts every time:

src/e1.ts:2:18 - error TS2339: Property 'nmae' does not exist on type '{ name: string; age: number; }'.2 console.log(user.nmae);                   ~~~~

(That is the --pretty format; I removed the colours. With --pretty false you get the one-line version src/e1.ts(2,18): error TS2339: ....)

• src/e1.ts:2:18: file, line 2, column 18. The ~~~~ marks the exact word.
• TS2339: the error code. It is stable. Search for the code plus a few words, and you will find explanations.
• The message after it says what is wrong. Read it as "I expected X but found Y".

Some messages have extra indented lines under them. Read the last indented line first, because it usually holds the real reason. Here are the errors I got most often, from small files. Each file uses the tsconfig above.

A typo in a property name.

const user = { name: "Ada", age: 36 };console.log(user.nmae);

src/e1.ts(2,18): error TS2339: Property 'nmae' does not exist on type '{ name: string; age: number; }'.

The message shows the type TypeScript worked out for user. You never wrote it: TypeScript inferred it (Lesson 1).

A parameter without a type.

function double(n) {  return n * 2;}

src/e2.ts(1,17): error TS7006: Parameter 'n' implicitly has an 'any' type.

any means "turn the checker off for this value". noImplicitAny (part of strict) refuses to let you get it by accident. Fix: function double(n: number).

A value that might be missing.

function find(names: string[], q: string) {  return names.find((n) => n === q);}const hit = find(["Ada", "Bo"], "Ada");console.log(hit.toUpperCase());

src/e4.ts(5,13): error TS18048: 'hit' is possibly 'undefined'.

Array.find returns undefined when nothing matches. strictNullChecks makes TypeScript remember that. Fix: check first, if (hit) { ... }. (Lesson 1 teaches this, called narrowing.)

An indexed read.

function firstWord(text: string): string {  const words = text.split(" ");  return words[0];}

src/e3.ts(3,3): error TS2322: Type 'string | undefined' is not assignable to type 'string'.  Type 'undefined' is not assignable to type 'string'.

This one comes from noUncheckedIndexedAccess. I removed that line from the config and ran again: the error disappeared. An empty array has no words[0], so the check is correct about the risk.

Often one early mistake causes several later errors, and tsc reports all of them in one run. Fix the first one on the list, run again, and repeat.

What strict bought us

I ran the same files with "strict": false. The typo error (TS2339) stayed, because it does not depend on strict. The any parameter (TS7006), the possibly 'undefined' error (TS18048) and the string | undefined error (TS2322) all disappeared, because those checks live in strict. The program is not safer; the checker just stopped looking. That is why the setting stays on.

Try it

1. Create a project as shown above. Write src/hello.ts with a function add(a: number, b: number): number. Run it with node, with tsx, and check it with tsc.
2. Call add("1", 2). Run tsc, then run the file with node. What happens in each case?
3. Add enum Dir { Up, Down } to a file. What does tsc say with erasableSyntaxOnly? What does node say? Then change it to const Dir = { Up: 0, Down: 1 } as const; (Lesson 2 explains this).
4. Move an interface to another file and import it without the word type. Read both the tsc error and the Node error.

Answers.

1. All three work. tsc prints nothing and exits with 0.
2. tsc reports error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. node runs the file anyway and "1" + 2 gives the text "12". Types are erased, so Node never sees the problem.
3. tsc: TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. Node: ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX ... TypeScript enum is not supported in strip-only mode. The object with as const is plain JavaScript plus a type note, so both accept it.
4. tsc: TS1484. Node: The requested module './types.ts' does not provide an export named 'Name'.

Interview questions

Key takeaways

• TypeScript = JavaScript + a checker. The types are erased; they do not exist at runtime.
• tsc checks. tsx and node file.ts run. Only tsc finds type errors.
• Node 22 strips types by default (v22.18.0 and later). It cannot run enums, parameter properties or runtime namespaces, and it ignores tsconfig.json.
• A good start config: strict, noUncheckedIndexedAccess, skipLibCheck, isolatedModules, verbatimModuleSyntax, erasableSyntaxOnly, noEmit and types: ["node"].
• Read an error as: file, line, column, code, message. Read the last indented line first.
• Do not trust as, any or @ts-ignore to make errors go away.

What's next

Lesson 1: Basic Types, Inference and Narrowing. Now that you can run tsc and read its messages, we learn the basic types, why you can often leave them out, and how TypeScript follows your if checks to know what a value is.