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:
mkdir -p ~/ts-demo
cd ~/ts-demo
npm init -y
npm pkg set type=moduleStep 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:
npm install --save-dev typescript@7 @types/node@26
npx tsc --versionnpx 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:
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"]
}
JSONWhat the settings mean:
targetis the JavaScript version to write.es2023is well within what Node.js 26 supports.moduleandmoduleResolutionset tonodenextmake the compiler follow Node's own rules for modules, which it reads from"type": "module"inpackage.json.rootDirandoutDirsay that sources live insrc/and output goes todist/.strictturns on the family of strict checks, including that a value cannot benullunless you say so. Always start a new project with it on.noUncheckedIndexedAccessmakesarray[0]possiblyundefined, which it can be.verbatimModuleSyntaxrequires you to mark imports that only carry types with the wordtype, so the compiler knows exactly what to remove.skipLibCheckskips checking the.d.tsfiles innode_modules, which saves time and avoids errors that are not yours.typeslists the global type packages to load, here only Node's. TypeScript 7 changed the defaults forrootDirandtypes, 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:
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})`;
}
TSinterface 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:
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));
TSThe 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:
npx tsc
ls dist
node dist/index.js AdaCheck 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:
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:
head -n 6 src/index.ts > src/index.tmp
mv src/index.tmp src/index.ts
npx tsc --noEmitThe 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:
npm pkg set scripts.build="tsc" scripts.typecheck="tsc --noEmit" scripts.start="node dist/index.js"
npm run build
npm start -- Gracenpm 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:
cat > scratch.ts <<'TS'
const n: number = "not a number";
console.log("ran anyway");
TS
node scratch.tsThe 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:
cd ~
rm -rf ~/ts-demoNext steps
- Package a compiled Node.js app in an image: write a Dockerfile for a Node.js app.
- Build a web app with types: build your first Next.js 16 app with the App Router, which sets up TypeScript for you.
- The TypeScript handbook at typescriptlang.org/docs covers generics, unions, narrowing and the rest of the type system.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials