1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
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 %}
**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`
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.
{% 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
```
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
{
+ "extends": ["bun-types"]
// other options...
}
```
{% 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.
### 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",
// if TS 5.x+
"moduleResolution": "bundler",
"noEmit": true,
"allowImportingTsExtensions": true,
"moduleDetection": "force",
// if TS 4.x or earlier
"moduleResolution": "nodenext",
"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 DOM types
Settings `"types": ["bun-types"]` means TypeScript will ignore other global type definitions, including `lib: ["dom"]`. To add DOM types into your project, add the following [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at the top of any TypeScript file in your project.
```ts
/// <reference lib="dom" />
/// <reference lib="dom.iterable" />
```
The same applies to other global type definition _libs_ like `webworker`.
## 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.
Given the following `tsconfig.json`...
```json
{
"compilerOptions": {
"paths": {
"data": ["./data.ts"]
}
}
}
```
...the import from `"data"` will work as expected.
{% codetabs %}
```ts#index.ts
import { foo } from "data";
console.log(foo); // => "Hello world!"
```
```ts#data.ts
export const foo = "Hello world!"
```
{% /codetabs %}
|
