Setting Up TypeScript

Difficulty: Beginner

Getting started with TypeScript requires installing the TypeScript compiler and understanding how to configure it. The compiler (`tsc`) is distributed as an npm package and can be installed globally or as a project dependency. For most projects, installing it locally as a dev dependency is recommended so that every developer on the team uses the same version.

The TypeScript compiler is invoked with the `tsc` command. You can compile a single file with `tsc myFile.ts`, which produces a `myFile.js` output. For larger projects, you create a `tsconfig.json` configuration file that tells the compiler which files to include, what JavaScript version to target, how strict the type checking should be, and where to output compiled files. Running `tsc --init` generates a default tsconfig with commented explanations for every option.

The `tsconfig.json` file has several important sections. The `compilerOptions` object controls the compilation behavior: `target` sets the output JavaScript version, `module` sets the module system (CommonJS, ESModules), `strict` enables all strict type-checking options, and `outDir` specifies where compiled JS files are written. The `include` and `exclude` arrays control which files the compiler processes.

In modern development, you often don't invoke `tsc` directly. Build tools like Vite, webpack, esbuild, and swc handle TypeScript compilation as part of a larger build pipeline. These tools typically use their own TypeScript parsers for speed and rely on `tsc` only for type checking (via `tsc --noEmit`). This separation of concerns - fast builds with a separate type-checking step - has become the standard pattern in large TypeScript projects.

Code examples

Installing TypeScript and compiling

// Terminal commands (not runnable here)
// npm install -D typescript
// npx tsc --init          # Creates tsconfig.json
// npx tsc                 # Compiles entire project
// npx tsc --watch         # Recompiles on file changes

// A simple TypeScript file: hello.ts
const message: string = "TypeScript is set up!";
console.log(message);

After installing TypeScript as a dev dependency, you use npx tsc to compile. The --watch flag is useful during development as it recompiles automatically when files change.

Basic tsconfig.json structure

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

// With this config, src/index.ts compiles to dist/index.js
const version: number = 5;
console.log(`TypeScript version target: ES2020, strict: ${version >= 4}`);

The tsconfig.json controls compilation behavior. 'strict: true' enables all strict checks and is recommended for new projects. 'outDir' and 'rootDir' control the directory structure of compiled output.

Strict mode benefits

// With strict: true, TypeScript enforces:
// - strictNullChecks: null and undefined are distinct types
// - noImplicitAny: must annotate types that can't be inferred
// - strictFunctionTypes: checks function parameter types correctly

function getLength(value: string | null): number {
  // With strictNullChecks, you must handle null
  if (value === null) {
    return 0;
  }
  return value.length;
}

console.log(getLength("hello"));
console.log(getLength(null));

Strict mode catches potential null/undefined errors and requires explicit type handling. Always enable strict mode in new projects - it prevents entire categories of bugs.

Key points

• Always use `strict: true` in new projects - it enables the most useful type checks including strictNullChecks and noImplicitAny.
• The `tsc --noEmit` flag checks types without producing output files - useful when another tool handles the actual compilation.
• Use `npx tsc --init` to generate a tsconfig.json with all options documented as comments.

Concepts covered

tsc compiler, tsconfig.json, Installation, Compilation