From a286fbb43d7cfb16a34bf8153d909bccafbf219a Mon Sep 17 00:00:00 2001
From: Orta Therox <orta.therox@gmail.com>
Date: Tue, 23 Jun 2020 10:44:39 -0400
Subject: [PATCH] Adds a doc for babel + tsc in a project

---
 .../en/tutorials/Babel with TypeScript.md     | 48 +++++++++++++++++++
 .../src/lib/handbookNavigation.ts             | 10 ++--
 2 files changed, 52 insertions(+), 6 deletions(-)
 create mode 100644 packages/handbook-v1/en/tutorials/Babel with TypeScript.md

diff --git a/packages/handbook-v1/en/tutorials/Babel with TypeScript.md b/packages/handbook-v1/en/tutorials/Babel with TypeScript.md
new file mode 100644
index 000000000000..a9a21d321c94
--- /dev/null
+++ b/packages/handbook-v1/en/tutorials/Babel with TypeScript.md	
@@ -0,0 +1,48 @@
+---
+title: Using Babel with TypeScript
+layout: docs
+permalink: /docs/handbook/tutorials/babel-with-typescript.html
+oneline: How to create a hybrid Babel + TypeScript project
+---
+
+# Babel vs `tsc` for TypeScript
+
+When making a modern JavaScript project, you might ask yourself what the right way to convert files from TypeScript to JavaScript.
+
+A lot of the time the answer is _"it depends"_, or _"someone may have decided for you"_ depending on the project. If you are building your project with an existing framework like [tsdx](https://www.npmjs.com/package/tsdx), [Angular](https://angular.io/), [NestJS](https://nestjs.com/) or any framework mentioned in the [Getting Started](/docs/home) then this decision is handled for you.
+
+However, a useful heuristic could be:
+
+- Is your build output mostly the same as your source input files? Use `tsc`
+- Do you need a build pipeline with multiple potential outputs? Use `babel` for transpiling and `tsc` for type checking
+
+## Babel for transpiling, `tsc` for types
+
+This is a common pattern for projects with existing build infrastructure which may have been ported from a JavaScript codebase to TypeScript.
+
+This technique is a hybrid approach, using Babel's [preset-typescript](https://babeljs.io/docs/en/babel-preset-typescript) to generate your JS files, and then using TypeScript to do type checking and `.d.ts` file generation.
+
+By using babel's support for TypeScript, you get the ability to work with existing build pipelines and are more likely to have a faster JS emit time because Babel does not type check your code.
+
+#### Type Checking and d.ts file generation
+
+The downside to using babel is that you don't get type checking during the transition from TS to JS. This can mean that type errors which you miss in your editor could sneak through into production code.
+
+In addition to that, Babel cannot create `.d.ts` files for your TypeScript which can make it harder to work with your project if it is a library.
+
+To fix these issues, you would probably want to set up a command to type check your project using TSC. This likely means duplicating some of your babel config into a corresponding [`tsconfig.json`](/tconfig) and ensuring these flags are enabled:
+
+```json
+"compilerOptions": {
+  // Ensure that .d.ts files are created by tsc, but not .js files
+  "declaration": true,
+  "emitDeclarationOnly": true,
+  // Ensure that Babel can safely transpile files in the TypeScript project
+  "isolatedModules": true
+}
+```
+
+For more information on these flags:
+
+- [`isolatedModules`](/tsconfig#isolatedModules)
+- [`declaration`](/tsconfig#declaration), [`emitDeclarationOnly`](/tsconfig#emitDeclarationOnly)
diff --git a/packages/typescriptlang-org/src/lib/handbookNavigation.ts b/packages/typescriptlang-org/src/lib/handbookNavigation.ts
index c574103886bf..f282ffc2a678 100644
--- a/packages/typescriptlang-org/src/lib/handbookNavigation.ts
+++ b/packages/typescriptlang-org/src/lib/handbookNavigation.ts
@@ -12,8 +12,7 @@ export interface NavItem {
 export const handbookNavigation: NavItem[] = [
   {
     title: "Get Started",
-    summary:
-      "Quick introductions based on your background or preference.",
+    summary: "Quick introductions based on your background or preference.",
     id: "get-started",
     directory: "handbook",
     index: "typescript-from-scratch",
@@ -39,8 +38,7 @@ export const handbookNavigation: NavItem[] = [
   },
   {
     title: "Handbook",
-    summary:
-      "A good first read for your daily TS work.",
+    summary: "A good first read for your daily TS work.",
     id: "handbook",
     directory: "handbook",
     chronological: true,
@@ -93,13 +91,13 @@ export const handbookNavigation: NavItem[] = [
     id: "tutorials",
     directory: "handbook",
     index: "typescript-in-5-minutes",
-    summary:
-      "Using TypeScript in several environments.",
+    summary: "Using TypeScript in several environments.",
     items: [
       { id: "asp-net-core", title: "ASP.NET Core" },
       { id: "gulp", title: "Gulp" },
       { id: "migrating-from-javascript", title: "Migrating from JavaScript" },
       { id: "react-&-webpack", title: "React & Webpack" },
+      { id: "babel-with-typescript", title: "Using Babel with TypeScript" },
     ],
   },
   {