https://github.com/alii/bun-types-no-globals
Bun types with no globals to prevent polluting your environment
https://github.com/alii/bun-types-no-globals
bun runtime type-definitons types typescript typings
Last synced: about 1 month ago
JSON representation
Bun types with no globals to prevent polluting your environment
- Host: GitHub
- URL: https://github.com/alii/bun-types-no-globals
- Owner: alii
- Created: 2025-08-22T06:47:55.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-05-14T00:41:35.000Z (about 1 month ago)
- Last Synced: 2026-05-14T02:38:38.509Z (about 1 month ago)
- Topics: bun, runtime, type-definitons, types, typescript, typings
- Language: TypeScript
- Homepage: https://bun.com
- Size: 1.27 MB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# bun-types-no-globals
TypeScript type definitions for Bun's APIs without global namespace pollution. This package provides clean, isolated Bun types that won't interfere with other environments or type systems.
> **Note:** This package is for advanced use cases only. You are probably looking for [`@types/bun`](https://www.npmjs.com/package/@types/bun) instead.
## Why does this exist?
When building universal tools or libraries that support multiple runtimes (Node.js, Bun, browsers, etc.), importing `@types/bun` causes problems:
- **Global type pollution**: Regular Bun types modify global interfaces and add global variables that conflict with Node.js or browser types
- **Transitive type leakage**: If your library uses `@types/bun`, everyone who installs your library gets Bun's global types too - even if they're not using Bun
- **Multi-bundler compatibility issues**: Tools like [unplugin](https://github.com/unjs/unplugin) that support webpack, Vite, Rollup, esbuild, AND Bun can't use regular Bun types without forcing them on all users
This package solves these issues by providing Bun's type definitions in an isolated, non-global way.
## Common Use Cases
### 🔧 Multi-Runtime Libraries
Libraries that work across Node.js, Bun, and browsers can safely import Bun-specific APIs without breaking TypeScript for other runtimes:
```ts
import type { BunFile } from 'bun';
export function processFile(file: BunFile | Buffer) {
// Implementation that works with both Bun and Node.js
}
```
### 🛠️ Build Tool Plugins
Build tools and bundler plugins (like unplugin) can add Bun support without forcing Bun types on webpack, Vite, or Rollup users:
```ts
import type { BunPlugin } from 'bun';
export function createPlugin(): BunPlugin | WebpackPlugin | VitePlugin {
// Plugin implementation
}
```
### 🛠️ [Re-\]declaring the Bun namespace
Sometimes you'll still want the Bun namespace to globally exist - this is most helpful in situations where actually including a runtime import from `bun` is more inconvenient than using the Bun namespace itself. You can tell TypeScript about the namespace by including this code somewhere in your program:
```ts
import * as BunModule from 'bun';
declare global {
export import Bun = BunModule;
}
```
I wrote a little about the above syntax [on my blog about Ambient Declarations](https://alistair.sh/ambient-declarations).
## Usage
We recommend you require these types with a triple slash reference anywhere in your program
```ts
///
```
The **alternative** is to include it in your tsconfig.json types array
```jsonc
{
"compilerOptions": {
"types": ["bun-types-no-globals"],
},
}
```