Modules & tooling.
From .ts file to shipped app.

// ─── What each option does ─────────────────

// strict: true
// Turns on 8 sub-flags at once: strictNullChecks,
// noImplicitAny, strictFunctionTypes, etc. Catches
// null/undefined bugs, implicit any, and more.
// ALWAYS enable this from day one.

// target: "ES2022"
// JavaScript version to compile down to. ES2022
// supports top-level await, class fields, .at().
// Modern enough for 2026 browsers. Use ES2020 if
// you must support older browsers.

// lib: ["ES2022", "DOM", "DOM.Iterable"]
// Which built-in types exist. DOM adds document,
// window, fetch. Add other libs for other envs.

// module: "ESNext"
// Output module syntax. ESNext keeps import/export.
// "CommonJS" would convert to require(). Use ESNext
// for modern bundlers.

// moduleResolution: "bundler"
// How to resolve imports. "bundler" (new in TS 5)
// matches how Vite, webpack, esbuild work. Use it
// for any modern bundler. "node" is for Node.js.

// esModuleInterop: true
// Lets you import CJS modules as if they were ESM.
// import express from 'express' works without this
// only if the library ships compatible types. Set it.

// resolveJsonModule: true
// Lets you import JSON files with proper types.
// import data from './data.json' works.

// isolatedModules: true
// Each file must be independently compilable.
// Required by esbuild, Vite, and Babel. Set it.

// noEmit: true
// Don't output .js files — just type check.
// Set when a bundler (Vite) handles the build.
// Set to false if you use plain tsc for output.

// skipLibCheck: true
// Skip type checking of .d.ts files in node_modules.
// Speeds up builds significantly. Some disagree with
// it, but for most projects the trade is worth it.

// paths: { "@/*": ["src/*"] }
// Path aliases. "@/" → "src/". Requires the same
// config in your bundler.

// With module: "ESNext" — output keeps import/export.
// This is what modern bundlers expect.

import { useState } from 'react';
import express from 'express';
// Type-only import erased entirely

export function greet(name) {
return Hello,${name}`;
}

export const VERSION = '1.0.0';

export default function app() { return 'app'; }

import * as React from 'react';

// ─────────────────────────────────────────────
// If module: "CommonJS" were set instead, the
// output would be:
//
// const { useState } = require('react');
// const express = require('express');
// exports.greet = function(name) {...};
// exports.VERSION = '1.0.0';
//
// Both work. ESM is the modern standard.

// Vite config MUST mirror the tsconfig paths.
// TS config makes the type checker happy.
// Vite config makes the actual bundling work.
// Both are required — one without the other breaks.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
plugins: [react()],
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
'@components': path.resolve(__dirname, './src/components'),
'@utils': path.resolve(__dirname, './src/utils'),
'@types': path.resolve(__dirname, './src/types')
}
}
});

// ─────────────────────────────────────────────
// Webpack, Rollup, esbuild, Next.js — same idea,
// different config syntax. Every bundler supports
// aliases, but each has its own way of declaring them.
// If you use Next.js, tsconfig paths work out of the box
// (no bundler config needed). Vite requires both.

// ─── Using a library with .d.ts types ─────────

import { initialize, query, Config } from 'my-lib';

// Full autocomplete + type checking — from the .d.ts file
initialize({
apiKey: 'abc123',
endpoint: 'https://api.example.com'
});

const result = await query('SELECT * FROM users');
// result: unknown[] (from the .d.ts return type)

// ─── How @types/* works ───────────────────────
// When you install:
// npm install lodash
// npm install --save-dev @types/lodash
//
// TypeScript looks in:
// node_modules/@types/lodash/index.d.ts
//
// It finds types automatically — no import needed.
// You just get them when you import lodash.

// ─── Do I need @types? ────────────────────────
// If the library ships its own .d.ts (most modern libs do):
// → no @types needed. Installing both causes conflicts.
//
// If the library is plain JavaScript (older libs):
// → install @types/libname. If it exists, great. If not,
// you might need to write your own .d.ts or use any.
//
// Popular @types packages:
// @types/node, @types/react, @types/express,
// @types/lodash, @types/jest, @types/lodash.debounce

{
"name": "my-app",
"scripts": {
"dev": "vite",
"build": "tsc --noEmit && vite build",
"preview": "vite preview"
},
"devDependencies": {
"typescript": "^5.6.0",
"vite": "^5.4.0",
"@vitejs/plugin-react": "^4.3.0"
}
}

// ─── The build script is the key ─────────────
// "tsc --noEmit && vite build"
//
// 1. tsc --noEmit — type check every file.
// Fails the build if any type error exists.
// 2. vite build — bundles TS → optimized JS.
// Uses esbuild, doesn't check types.
//
// This pattern: type check FIRST, then build.
// If types fail, you never ship a broken build.
// If types pass, Vite produces optimized output.
//
// CI runs npm run build — full safety, fast dev.

// ─── Typical Vite + TS project structure ────

my-app/
├── node_modules/
├── public/ // static assets
├── src/
│ ├── components/ // .tsx files
│ ├── hooks/ // use*.ts files
│ ├── types/ // shared types
│ ├── utils/ // helpers
│ ├── App.tsx // root component
│ ├── main.tsx // entry point
│ └── vite-env.d.ts // Vite type refs
├── index.html // single HTML entry
├── package.json
├── tsconfig.json // base config
├── tsconfig.node.json // config for vite.config.ts
└── vite.config.ts // Vite config (with aliases)

// ─── Two tsconfig files — why? ──────────────
// tsconfig.json → for src/ (browser code)
// tsconfig.node.json → for vite.config.ts (Node code)
//
// The two files have different targets and libs:
// src/ needs DOM; vite.config.ts needs Node.
// Vite scaffolds both automatically.

// ─── vite-env.d.ts — what's in it ───────────
// /// 
//
// This one line tells TS about Vite's env vars,
// asset imports (import logo from './logo.svg'),
// and other Vite-specific features.