0
# Runtime Detection
1

2
JavaScript runtime identification following the WinterCG Runtime Keys proposal, with support for Node.js, Deno, Bun, and various edge computing platforms.
3

4
## Capabilities
5

6
### Node.js Runtime Detection
7

8
Detects Node.js runtime, including compatibility mode in other runtimes.
9

10
```typescript { .api }
11
/**
12
 * Indicates if running in Node.js or a Node.js compatible runtime
13
 * Note: When running code in Bun and Deno with Node.js compatibility mode,
14
 * isNode flag will be true, indicating running in a Node.js compatible runtime.
15
 * Use runtime === "node" for strict Node.js runtime check.
16
 */
17
const isNode: boolean;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { isNode, runtime } from "std-env";
24

25
if (isNode) {
26
  console.log("Running in Node.js or Node.js compatible runtime");
27
  // Can use Node.js APIs
28
  const fs = require('fs');
29
}
30

31
// Strict Node.js check
32
if (runtime === "node") {
33
  console.log("Running in actual Node.js runtime");
34
}
35
```
36

37
### Deno Runtime Detection
38

39
Detects Deno runtime based on global Deno object.
40

41
```typescript { .api }
42
/**
43
 * Indicates if running in Deno runtime
44
 * Based on presence of globalThis.Deno
45
 */
46
const isDeno: boolean;
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { isDeno } from "std-env";
53

54
if (isDeno) {
55
  console.log("Running in Deno");
56
  // Use Deno-specific APIs
57
  const text = await Deno.readTextFile("./file.txt");
58
  // Use Deno permissions
59
  await Deno.permissions.query({ name: "read" });
60
}
61
```
62

63
### Bun Runtime Detection
64

65
Detects Bun runtime based on global Bun object or process versions.
66

67
```typescript { .api }
68
/**
69
 * Indicates if running in Bun runtime
70
 * Based on globalThis.Bun or process.versions.bun
71
 */
72
const isBun: boolean;
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
import { isBun } from "std-env";
79

80
if (isBun) {
81
  console.log("Running in Bun");
82
  // Use Bun-specific APIs
83
  const file = Bun.file("./data.json");
84
  const data = await file.json();
85
}
86
```
87

88
### Fastly Compute Runtime Detection
89

90
Detects Fastly Compute@Edge runtime.
91

92
```typescript { .api }
93
/**
94
 * Indicates if running in Fastly Compute@Edge runtime
95
 * Based on globalThis.fastly
96
 */
97
const isFastly: boolean;
98
```
99

100
**Usage Examples:**
101

102
```typescript
103
import { isFastly } from "std-env";
104

105
if (isFastly) {
106
  console.log("Running in Fastly Compute@Edge");
107
  // Use Fastly-specific APIs
108
  // Handle edge requests
109
}
110
```
111

112
### Netlify Edge Runtime Detection
113

114
Detects Netlify Edge Functions runtime.
115

116
```typescript { .api }
117
/**
118
 * Indicates if running in Netlify Edge Functions runtime
119
 * Based on globalThis.Netlify
120
 */
121
const isNetlify: boolean;
122
```
123

124
**Usage Examples:**
125

126
```typescript
127
import { isNetlify } from "std-env";
128

129
if (isNetlify) {
130
  console.log("Running in Netlify Edge Functions");
131
  // Use Netlify-specific context
132
  // Access geo-location data
133
}
134
```
135

136
### Vercel Edge Runtime Detection
137

138
Detects Vercel Edge Runtime (EdgeLight).
139

140
```typescript { .api }
141
/**
142
 * Indicates if running in EdgeLight (Vercel Edge) runtime
143
 * Based on globalThis.EdgeRuntime
144
 */
145
const isEdgeLight: boolean;
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
import { isEdgeLight } from "std-env";
152

153
if (isEdgeLight) {
154
  console.log("Running in Vercel Edge Runtime");
155
  // Use edge-specific optimizations
156
  // Handle streaming responses
157
}
158
```
159

160
### Cloudflare Workers Runtime Detection
161

162
Detects Cloudflare Workers runtime based on user agent.
163

164
```typescript { .api }
165
/**
166
 * Indicates if running in Cloudflare Workers runtime
167
 * Based on navigator.userAgent === "Cloudflare-Workers"
168
 */
169
const isWorkerd: boolean;
170
```
171

172
**Usage Examples:**
173

174
```typescript
175
import { isWorkerd } from "std-env";
176

177
if (isWorkerd) {
178
  console.log("Running in Cloudflare Workers");
179
  // Use Cloudflare Workers APIs
180
  // Access KV storage
181
  // Handle fetch events
182
}
183
```
184

185
### Runtime Information
186

187
Structured runtime information following WinterCG Runtime Keys proposal.
188

189
```typescript { .api }
190
/**
191
 * Current runtime name following WinterCG Runtime Keys proposal
192
 * Empty string if runtime cannot be determined
193
 */
194
const runtime: RuntimeName;
195

196
/**
197
 * Detected runtime information object
198
 * undefined if runtime cannot be determined
199
 */
200
const runtimeInfo: RuntimeInfo | undefined;
201

202
type RuntimeName = 
203
  | "workerd"      // Cloudflare Workers
204
  | "deno"         // Deno
205
  | "netlify"      // Netlify Edge Functions  
206
  | "node"         // Node.js
207
  | "bun"          // Bun
208
  | "edge-light"   // Vercel Edge Runtime
209
  | "fastly"       // Fastly Compute@Edge
210
  | "";            // Unknown/undetected
211

212
interface RuntimeInfo {
213
  name: RuntimeName;
214
}
215
```
216

217
**Usage Examples:**
218

219
```typescript
220
import { runtime, runtimeInfo } from "std-env";
221

222
console.log(`Detected runtime: ${runtime}`);
223

224
// Runtime-specific logic
225
switch (runtime) {
226
  case "node":
227
    console.log("Node.js specific features available");
228
    break;
229
  case "deno":
230
    console.log("Deno specific features available");
231
    break;
232
  case "bun":
233
    console.log("Bun specific features available");
234
    break;
235
  case "workerd":
236
    console.log("Cloudflare Workers features available");
237
    break;
238
  case "edge-light":
239
    console.log("Vercel Edge Runtime features available");
240
    break;
241
  default:
242
    console.log("Unknown or undetected runtime");
243
}
244

245
// Check if runtime info is available
246
if (runtimeInfo) {
247
  console.log(`Runtime info: ${JSON.stringify(runtimeInfo)}`);
248
}
249
```
250

251
## Runtime Detection Priority
252

253
Runtime detection follows this priority order (first match wins):
254

255
1. **Netlify** (`isNetlify`) - `globalThis.Netlify`
256
2. **EdgeLight** (`isEdgeLight`) - `globalThis.EdgeRuntime`
257
3. **Cloudflare Workers** (`isWorkerd`) - `navigator.userAgent === "Cloudflare-Workers"`
258
4. **Fastly** (`isFastly`) - `globalThis.fastly`
259
5. **Deno** (`isDeno`) - `globalThis.Deno`
260
6. **Bun** (`isBun`) - `globalThis.Bun` or `process.versions.bun`
261
7. **Node.js** (`isNode`) - `process.release.name === "node"`
262

263
## Runtime-Specific Usage Patterns
264

265
### Cross-Runtime File Reading
266

267
```typescript
268
import { runtime, isNode, isDeno, isBun } from "std-env";
269

270
async function readFile(path: string): Promise<string> {
271
  switch (runtime) {
272
    case "node":
273
    case "bun":
274
      const fs = await import('fs/promises');
275
      return fs.readFile(path, 'utf-8');
276
    
277
    case "deno":
278
      return Deno.readTextFile(path);
279
    
280
    default:
281
      throw new Error(`File reading not supported in ${runtime} runtime`);
282
  }
283
}
284
```
285

286
### Runtime-Specific HTTP Clients
287

288
```typescript
289
import { runtime } from "std-env";
290

291
async function fetchData(url: string) {
292
  switch (runtime) {
293
    case "node":
294
      // Use Node.js native fetch (v18+) or polyfill
295
      return fetch(url);
296
    
297
    case "deno":
298
    case "bun":
299
    case "workerd":
300
    case "edge-light":
301
      // Native fetch available
302
      return fetch(url);
303
    
304
    default:
305
      throw new Error(`HTTP requests not supported in ${runtime} runtime`);
306
  }
307
}
308
```