dev/notes
⌕

Spot a mistake? Highlight any text in a post and click Report — it goes straight to the author.

← all posts
intermediate · TypeScript · August 17, 2026 · updated October 27, 2026 · 3 min read

How to Set Up a TypeScript Project from Scratch

Create a TypeScript project from scratch: tsconfig.json, strict mode, and build scripts. A hands-on setup guide for Node.js and TypeScript.

Why strict mode from day one

TypeScript’s value is catching mistakes before runtime, but only if strict is on. Turning it on later means fixing a wall of errors at once. Enable it now, when there is no legacy code to migrate.

Step 1: Initialize the project

mkdir my-ts-project && cd my-ts-project
npm init -y
npm install -D typescript tsx @types/node
  • typescript: the compiler.
  • tsx: runs .ts files directly during development.
  • @types/node: types for Node’s standard library.

Step 2: Create tsconfig.json

npx tsc --init

Replace the generated file with a focused config:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

noUncheckedIndexedAccess makes array/object access return T | undefined, forcing you to handle missing keys explicitly.

Step 3: Write your first module

src/index.ts:

interface Greeting {
  name: string;
  punctuation?: string;
}

export function greet(input: Greeting): string {
  const mark = input.punctuation ?? "!";
  return `Hello, ${input.name}${mark}`;
}

console.log(greet({ name: "devnotes" }));

Step 4: Path aliases for clean imports

Deep relative imports (../../../../lib/db) get unreadable fast. Add a paths map to tsconfig.json and import from an alias:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Then import from the alias in source:

import { db } from "@/lib/db";

TypeScript resolves the alias during typechecking and in the editor, and tsx resolves it during development. That is where the alias story ends for the default toolchain. tsc does not rewrite aliases in the JavaScript it emits. The file in dist/ still contains @/lib/db, and plain Node does not read tsconfig.json, so node dist/index.js fails with a module-not-found error for the alias. This bug only appears after a build. Development with tsx works, which is why it is easy to miss until the built app runs.

Fix it at build time. Install tsc-alias and run it after tsc:

npm install -D tsc-alias

tsc-alias reads the paths mapping and rewrites the emitted imports to relative paths in dist/, so @/lib/db becomes a relative import Node can resolve with no runtime dependency and no loader. If you do not want a post-build step, skip the alias and use relative imports in code that ships.

Step 5: Add build and dev scripts

In package.json:

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc && tsc-alias",
    "start": "node dist/index.js"
  }
}

npm run dev hot-reloads during development; npm run build typechecks, emits plain JavaScript to dist/, and rewrites the aliases there; npm run start runs the built output.

Step 6: Editor integration

The whole point of a strict tsconfig.json is catching errors before you run anything, and that happens in the editor. Open the project in VS Code (it ships TypeScript support built in) and you get live red squiggles, hover types, and go-to-definition, all driven by this same config. If errors do not show, run TypeScript: Select TypeScript Version and pick the workspace version, so the editor uses your installed compiler in place of its bundled one.

Step 7: Wire typechecking into CI

Make type errors fail the build:

npm run build

tsc with strict is your first line of defense. Treat any error as a bug, not a suggestion. A passing build does not prove the built app runs, so run the built output once as a smoke test after the build:

node dist/index.js

Troubleshooting

  • Cannot find module with ESM: with "module": "NodeNext", local imports need explicit .js extensions (import { greet } from "./index.js").
  • Cannot find package '@/...' after a build: tsc left the alias in dist/ untouched. Run tsc-alias after tsc, as in Step 5, and check that dist/ contains relative imports, not @/ imports.
  • Object is possibly undefined: that is strict/noUncheckedIndexedAccess doing its job; narrow with a guard or optional chaining.
  • Output directory is messy: confirm rootDir/outDir are set so tsc mirrors your src/ layout.

Summary

You have a strict, modern TypeScript project with a dev loop (tsx watch) and a production build (tsc plus tsc-alias) that actually runs under plain Node. The compiler is now guarding every commit.

For the editor side of this setup, see How to Set Up VS Code for Web Development; to make CI fail on type errors automatically, GitHub Actions for CI/CD wires npm run build into every push.

Related posts

Comments

One comment per thread every 30 minutes · edits are unlimited.