TypeScript brings safety and scalability to JavaScript. But with great power comes great responsibility. Here are some hard-won lessons.

---

🧼 1. Prefer type over interface

// ✅ Better
type User = {
  id: number;
  name: string;
};

// ❌ Avoid when not extending
interface User {
  id: number;
  name: string;
}

Use type for union, intersection, and readability.

---

📁 2. Modularize Types

Avoid a types.ts god file. Instead:

• Co-locate types with domain logic
• Export them from index if needed

// user/types.ts
export type User = { id: number; name: string };

// user/index.ts
export * from "./types";

---

🧪 3. Use Narrow Types

Instead of generic types:

// ❌
function log(level: string) {}

// ✅
type LogLevel = "info" | "warn" | "error";
function log(level: LogLevel) {}

---

📌 4. Enforce strict mode

Enable in tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true
  }
}

This avoids silent type issues.

---

📚 5. Document Complex Types

/**
 * Represents a GitHub API user payload
 */
type GitHubUser = {
  login: string;
  id: number;
  avatar_url: string;
};

---

🧠 Final Thoughts

TypeScript doesn’t just catch bugs — it also documents intent.

---

🔗 Recommended Tools

• ESLint with @typescript-eslint
• TypeDoc
• ts-prune (find unused types)