Skip to main content

Programming languages · Beginner · 15 min

How to Set Up a TypeScript 7 Project from Scratch

By Padding · Updated 15 Nov 2026
TypeScript 7.0 · Node.js 26

You will create a Node.js 26 project, install TypeScript 7, write a tsconfig.json you understand, compile two files to JavaScript, watch the compiler catch a type error, and add npm scripts for building, checking and running.

On this page

TypeScript is JavaScript with types. You describe the shape of your data, and a compiler checks the whole program for mistakes before it runs: a misspelled property, a number passed where text belongs, a value that might be missing. It then removes the types and writes plain JavaScript that Node.js runs. This tutorial assumes Node.js 26 from the Node.js install tutorial.

TypeScript 7 is a native port of the compiler, which its release announcement calls ten times faster (Announcing TypeScript 7.0). The command is still tsc, and the configuration file is still tsconfig.json. In this tutorial you set up a small project from nothing, so that you know what each file is for. The steps use only tsc and node, and no framework or build tool.

Step 1 · Create the project

Make a folder and an npm project in it. npm init -y writes a package.json with defaults. Then set "type": "module", which makes Node.js treat .js files as ES modules, the import and export syntax:

Bash
mkdir -p ~/ts-demo
cd ~/ts-demo
npm init -y
npm pkg set type=module

Step 2 · Install TypeScript

Install the compiler and the type definitions for Node.js as development dependencies. Development dependencies are tools for working on the project, not code that runs in production. The second package describes Node's own functions, such as process, so that the compiler knows them:

Bash
npm install --save-dev typescript@7 @types/node@26
npx tsc --version

npx runs a program installed in this project's node_modules/.bin. Installing the compiler per project, and not globally, means each project uses the version it was written for.

Check it worked

npx tsc --version prints Version 7.0. followed by a patch number. package.json now has a devDependencies section listing both packages with a ^ in front of the version. The caret allows later minor and patch versions on npm install, and the exact versions are recorded in package-lock.json.

Step 3 · Write tsconfig.json

The compiler reads its settings from tsconfig.json. npx tsc --init creates a starter file. This tutorial writes a short one instead, so every line is a decision you can explain:

Bash
cat > tsconfig.json <<'JSON'
{
  "compilerOptions": {
    "target": "es2023",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "types": ["node"]
  },
  "include": ["src"]
}
JSON

What the settings mean:

  • target is the JavaScript version to write. es2023 is well within what Node.js 26 supports.
  • module and moduleResolution set to nodenext make the compiler follow Node's own rules for modules, which it reads from "type": "module" in package.json.
  • rootDir and outDir say that sources live in src/ and output goes to dist/.
  • strict turns on the family of strict checks, including that a value cannot be null unless you say so. Always start a new project with it on.
  • noUncheckedIndexedAccess makes array[0] possibly undefined, which it can be.
  • verbatimModuleSyntax requires you to mark imports that only carry types with the word type, so the compiler knows exactly what to remove.
  • skipLibCheck skips checking the .d.ts files in node_modules, which saves time and avoids errors that are not yours.
  • types lists the global type packages to load, here only Node's. TypeScript 7 changed the defaults for rootDir and types, according to its announcement, so this file sets both on purpose.

Step 4 · Write some TypeScript

Create two files in src/. The first declares a type and a function that uses it:

Bash
mkdir -p src
cat > src/greet.ts <<'TS'
export interface User {
  name: string;
  age?: number;
}

export function greet(user: User): string {
  const age = user.age === undefined ? "age unknown" : `${user.age} years old`;
  return `Hello, ${user.name} (${age})`;
}
TS

interface User describes an object with a required name that is text and an optional age that is a number. The ? marks it as optional. The second file imports the first and prints a greeting:

Bash
cat > src/index.ts <<'TS'
import { greet, type User } from "./greet.js";

const name = process.argv[2] ?? "world";
const user: User = { name, age: 36 };

console.log(greet(user));
TS

The import path ends in .js, not .ts. That is correct and surprises everyone once. TypeScript does not rewrite import paths, and the compiled file will be greet.js, so you write the name that will exist when the program runs. The compiler maps it back to greet.ts when it checks types.

Step 5 · Compile and run

Run the compiler. With no arguments it reads tsconfig.json:

Bash
npx tsc
ls dist
node dist/index.js Ada

Check it worked

tsc prints nothing when it succeeds. ls dist shows greet.js, greet.js.map, index.js and index.js.map. The .map files let debuggers show the original TypeScript. The run prints Hello, Ada (36 years old). Open dist/greet.js to see that it is the same code with the types removed.

Troubleshooting

An error such as Cannot find module './greet.js' after a successful build usually means the include or rootDir setting excludes the file. Cannot find name 'process' means the compiler does not know Node's types, so check that @types/node is installed and that "types": ["node"] is in tsconfig.json.

Step 6 · Let the compiler catch a mistake

This is the reason to use TypeScript. Add a call with the wrong type of value, and check the program without writing any output:

Bash
cat >> src/index.ts <<'TS'

console.log(greet({ name: 42 }));
TS
npx tsc --noEmit || echo "tsc exited with status $?"

--noEmit runs the checks and writes no files.

Check it worked

The compiler prints an error in this form, with your own file, line and column: src/index.ts(8,21): error TS2322: Type 'number' is not assignable to type 'string'., and the shell prints tsc exited with status 1. The numbers are the line and column. The error appears before the program runs, and a failing exit status is what makes a build or a CI job stop. Now remove the bad line:

Bash
head -n 6 src/index.ts > src/index.tmp
mv src/index.tmp src/index.ts
npx tsc --noEmit

The last command now succeeds, with no output.

Step 7 · Add npm scripts

Scripts give the commands names, so you and your teammates, and any CI system, run the same ones:

Bash
npm pkg set scripts.build="tsc" scripts.typecheck="tsc --noEmit" scripts.start="node dist/index.js"
npm run build
npm start -- Grace

npm pkg set edits package.json for you. The two dashes in npm start -- Grace mean that everything after them goes to your program and not to npm.

Check it worked

The build runs tsc, and npm start -- Grace prints Hello, Grace (36 years old), above or below a few lines of npm's own output.

Add a .gitignore file with node_modules and dist before you commit, because both are rebuilt from package.json and the source. Commit package-lock.json.

Step 8 · Know the shortcut, and its limit

Recent Node.js releases can run a TypeScript file directly. They strip the types and run what is left, with no build step:

Bash
cat > scratch.ts <<'TS'
const n: number = "not a number";
console.log("ran anyway");
TS
node scratch.ts

The output is ran anyway, even though the file has a type error, because Node.js removes types and never checks them. That is useful for scripts and quick experiments. It does not replace tsc, so keep running npm run typecheck in your project and in CI.

Remove the demo when you are done:

Bash
cd ~
rm -rf ~/ts-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.