diff options
| -rw-r--r-- | docs/runtime/typescript.md | 74 |
1 files changed, 54 insertions, 20 deletions
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. |