From a7e1269c6127e1adb42c443719734d1aae1698a1 Mon Sep 17 00:00:00 2001 From: shaischaudhry Date: Wed, 28 May 2025 09:27:24 +0500 Subject: [PATCH] docs: Add Quick Migration Guide for JavaScript developers - Create QUICK_MIGRATION_GUIDE.md with step-by-step migration instructions - Include common patterns, troubleshooting, and best practices - Add reference in README.md for easy discovery - Addresses common pain point for JS developers adopting TypeScript --- QUICK_MIGRATION_GUIDE.md | 234 +++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 2 files changed, 235 insertions(+), 1 deletion(-) create mode 100644 QUICK_MIGRATION_GUIDE.md diff --git a/QUICK_MIGRATION_GUIDE.md b/QUICK_MIGRATION_GUIDE.md new file mode 100644 index 0000000000000..9d688b80213ad --- /dev/null +++ b/QUICK_MIGRATION_GUIDE.md @@ -0,0 +1,234 @@ +# Quick Migration Guide: JavaScript to TypeScript + +This guide helps JavaScript developers quickly start using TypeScript in existing projects. Perfect for teams wanting to adopt TypeScript incrementally. + +## 🚀 Quick Start (5 minutes) + +### 1. Install TypeScript +```bash +# Install TypeScript globally +npm install -g typescript + +# Or install locally in your project +npm install -D typescript +``` + +### 2. Create TypeScript Configuration +```bash +# Generate tsconfig.json +npx tsc --init +``` + +### 3. Rename Your First File +```bash +# Rename any .js file to .ts +mv app.js app.ts +``` + +### 4. Compile and Run +```bash +# Compile TypeScript to JavaScript +npx tsc + +# Run the compiled JavaScript +node app.js +``` + +## 📝 Essential Type Annotations + +### Variables +```typescript +// Before (JavaScript) +let name = "John"; +let age = 30; +let isActive = true; + +// After (TypeScript) - types are inferred automatically! +let name = "John"; // string (inferred) +let age = 30; // number (inferred) +let isActive = true; // boolean (inferred) + +// Explicit typing (optional but helpful) +let name: string = "John"; +let age: number = 30; +let isActive: boolean = true; +``` + +### Functions +```typescript +// Before (JavaScript) +function greet(name) { + return "Hello, " + name; +} + +// After (TypeScript) +function greet(name: string): string { + return "Hello, " + name; +} + +// Arrow functions +const greet = (name: string): string => { + return "Hello, " + name; +}; +``` + +### Objects +```typescript +// Before (JavaScript) +const user = { + name: "John", + age: 30, + email: "john@example.com" +}; + +// After (TypeScript) - define the shape +interface User { + name: string; + age: number; + email: string; +} + +const user: User = { + name: "John", + age: 30, + email: "john@example.com" +}; +``` + +## 🔧 Common Migration Patterns + +### 1. Handling `any` Type +```typescript +// Start with 'any' for complex objects +let data: any = fetchDataFromAPI(); + +// Gradually add specific types +interface ApiResponse { + id: number; + name: string; + status: 'active' | 'inactive'; +} + +let data: ApiResponse = fetchDataFromAPI(); +``` + +### 2. Optional Properties +```typescript +interface User { + name: string; + age: number; + email?: string; // Optional property +} + +// Valid objects +const user1: User = { name: "John", age: 30 }; +const user2: User = { name: "Jane", age: 25, email: "jane@example.com" }; +``` + +### 3. Union Types +```typescript +// Handle multiple possible types +function processId(id: string | number) { + if (typeof id === "string") { + return id.toUpperCase(); + } + return id.toString(); +} +``` + +## ⚙️ Incremental Migration Strategy + +### Phase 1: Basic Setup +1. Install TypeScript +2. Create `tsconfig.json` +3. Rename one `.js` file to `.ts` +4. Fix any immediate errors + +### Phase 2: Add Type Annotations +1. Add types to function parameters +2. Define interfaces for objects +3. Use union types for flexible parameters + +### Phase 3: Strict Mode +1. Enable strict mode in `tsconfig.json` +2. Fix all type errors +3. Remove `any` types where possible + +## 🛠️ Essential tsconfig.json Settings + +```json +{ + "compilerOptions": { + "target": "ES2020", + "module": "commonjs", + "outDir": "./dist", + "rootDir": "./src", + "strict": false, // Start with false, enable later + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "allowJs": true, // Allow .js files during migration + "checkJs": false // Don't type-check .js files initially + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} +``` + +## 🚨 Common Migration Issues & Solutions + +### Issue: "Cannot find module" errors +```typescript +// Solution: Install type definitions +npm install -D @types/node +npm install -D @types/express // for Express.js +npm install -D @types/lodash // for Lodash +``` + +### Issue: "Property does not exist" errors +```typescript +// Problem: Accessing properties that might not exist +const user = getUser(); +console.log(user.name); // Error if user might be undefined + +// Solution: Use optional chaining +console.log(user?.name); + +// Or type guards +if (user && user.name) { + console.log(user.name); +} +``` + +### Issue: "Type 'any' is not assignable" errors +```typescript +// Problem: Mixing typed and untyped code +let data: string = fetchData(); // fetchData returns 'any' + +// Solution: Type assertion (use carefully) +let data: string = fetchData() as string; + +// Better solution: Type the function +function fetchData(): string { + return "some data"; +} +``` + +## 📚 Next Steps + +1. **Read the Official Handbook**: [TypeScript Handbook](https://www.typescriptlang.org/docs/) +2. **Try the Playground**: [TypeScript Playground](https://www.typescriptlang.org/play/) +3. **Join the Community**: [TypeScript Discord](https://discord.gg/typescript) +4. **Follow Best Practices**: [TypeScript Do's and Don'ts](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html) + +## 💡 Pro Tips + +- **Start Small**: Migrate one file at a time +- **Use Type Inference**: Let TypeScript infer types when possible +- **Gradual Typing**: Use `any` initially, then add specific types +- **IDE Support**: Use VS Code for excellent TypeScript support +- **Community Types**: Check [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) for library types + +--- + +*This guide covers the most common migration scenarios. For advanced topics, refer to the [official TypeScript documentation](https://www.typescriptlang.org/docs/).* \ No newline at end of file diff --git a/README.md b/README.md index b6505f7362b63..28c66f2f2b7a0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ - # TypeScript [![CI](https://github.com/microsoft/TypeScript/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/TypeScript/actions/workflows/ci.yml) @@ -41,6 +40,7 @@ with any additional questions or comments. ## Documentation +* [Quick Migration Guide](QUICK_MIGRATION_GUIDE.md) - **New to TypeScript?** Start here to migrate from JavaScript * [TypeScript in 5 minutes](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) * [Programming handbook](https://www.typescriptlang.org/docs/handbook/intro.html) * [Homepage](https://www.typescriptlang.org/)