From caa90ba98e878aa277a404219c7ad45f524b0db9 Mon Sep 17 00:00:00 2001
From: Colin McDonnell <colinmcd94@gmail.com>
Date: Fri, 21 Apr 2023 11:35:42 -0700
Subject: Update TS docs for bun-types changes (#2590)

* Update TS docs for bun-types changes

* Update typescript, remove extends guidance

* Updates

* Tweaks

* Tweaks
---
 docs/runtime/typescript.md | 74 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 54 insertions(+), 20 deletions(-)

(limited to 'docs/runtime/typescript.md')

diff --git a/docs/runtime/typescript.md b/docs/runtime/typescript.md
index 6ac1d991a..d466bb016 100644
--- a/docs/runtime/typescript.md
+++ b/docs/runtime/typescript.md
@@ -1,64 +1,98 @@
-Bun can directly execute `.ts` and `.tsx` files with no extra configuration. If you import a `.ts` or `.tsx` file, Bun internally transpiles it into JavaScript then executes the file.
+Bun treats TypeScript as a first-class citizen.
+
+## Running `.ts` files
+
+Bun can directly execute `.ts` and `.tsx` files just like vanilla JavaScript, with no extra configuration. If you import a `.ts` or `.tsx` file (or an `npm` module that exports these files), Bun internally transpiles it into JavaScript then executes the file.
+
+**Note** — Similar to other build tools, Bun does not typecheck the files. Use [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) (the official TypeScript CLI) if you're looking to catch static type errors.
 
 {% callout %}
-**Note** — Similar to other build tools, Bun does not typecheck the files. Use [`tsc --noEmit`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) (the official TypeScript CLI) if you're looking to catch static type errors.
+
+**Is transpiling still necessary?** — Because Bun can directly execute TypeScript, you may not need to transpile your TypeScript to run in production. Bun internally transpiles every file it executes (both `.js` and `.ts`), so the additional overhead of directly executing your `.ts/.tsx` source files is negligible.
+
+That said, if you are using Bun as a development tool but still targeting Node.js or browsers in production, you'll still need to transpile.
+
 {% /callout %}
 
 ## Configuring `tsconfig.json`
 
-When using TypeScript and Bun together, it's important to properly configure your `tsconfig.json`.
+Bun supports a number of features that TypeScript doesn't support by default, such as extensioned imports, top-level await, and `exports` conditions. It also implements global APIs like the `Bun`. To enable these features, your `tsconfig.json` must be configured properly.
 
-First, install the TypeScript definitions for Bun's built-in APIs:
+{% callout %}
+If you initialized your project with `bun init`, everything is already configured properly.
+{% /callout %}
+
+To get started, install the `bun-types` package.
 
 ```sh
 $ bun add -d bun-types # dev dependency
 ```
 
-Then include `"bun-types"` in the `compilerOptions.types` in your `tsconfig.json`:
+If you're using a canary build of Bun, use the `canary` tag. The canary package is updated on every commit to the `main` branch.
+
+```sh
+$ bun add -d bun-types@canary
+```
+
+<!-- ### Quick setup
+
+{% callout %}
+
+**Note** — This approach requires TypeScript 5.0 or later!
+
+{% /callout %}
+
+Add the following to your `tsconfig.json`.
 
 ```json-diff
   {
-    "compilerOptions": {
-+     "types": ["bun-types"]
-    }
++   "extends": ["bun-types"]
+    // other options...
   }
 ```
 
-This is the most important step, as it allows you to use Bun's built in APIs without seeing TypeScript errors in your IDE.
+{% callout %}
+**Note** — The `"extends"` field in your `tsconfig.json` can accept an array of values. If you're already using `"extends"`, just add `"bun-types"` to the array.
+{% /callout %}
+
+That's it! You should be able to use Bun's full feature set without seeing any TypeScript compiler errors.
 
-Bun implements a range of [modern ECMAScript features](https://github.com/sudheerj/ECMAScript-features), like bigint literals, nullish coalescing, dynamic imports, `import.meta`, `globalThis`, ES modules, top-level await, and more. To use these features without seeing TypeScript errors in your IDE, set the following `compilerOptions`:
+### Manual setup -->
+
+### Recommended `compilerOptions`
+
+These are the recommended `compilerOptions` for a Bun project.
 
 ```jsonc
 {
   "compilerOptions": {
+    // add Bun type definitions
+    "types": ["bun-types"],
+
     // enable latest features
     "lib": ["esnext"],
     "module": "esnext",
     "target": "esnext",
 
-    // typescript 5.x+
+    // if TS 5.x+
     "moduleResolution": "bundler",
-    // typescript 4.x or earlier
+    "allowImportingTsExtensions": true,
+    "moduleDetection": "force",
+    // if TS 4.x or earlier
     "moduleResolution": "nodenext",
 
-    // support JSX, CommonJS
-    "jsx": "react-jsx", // support JSX (value doesn't matter)
+    "jsx": "react-jsx", // support JSX
     "allowJs": true, // allow importing `.js` from `.ts`
     "esModuleInterop": true, // allow default imports for CommonJS modules
 
     // best practices
     "strict": true,
     "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
-
-    // add Bun type definitions
-    "types": ["bun-types"]
+    "skipLibCheck": true
   }
 }
 ```
 
-If you use `bun init`, an appropriate `tsconfig.json` is automatically generated for you.
-
 ## Path mapping
 
 When resolving modules, Bun's runtime respects path mappings defined in [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths) in your `tsconfig.json`. No other runtime does this.
-- 
cgit v1.2.3