0
# Environment & Performance
1

2
Environment detection and performance measurement utilities for cross-platform development and debugging.
3

4
## Capabilities
5

6
### Environment Detection
7

8
Detect the runtime environment and access global objects safely.
9

10
```typescript { .api }
11
/**
12
 * Boolean indicating if code is running in a browser environment
13
 */
14
const inBrowser: boolean;
15

16
/**
17
 * Get the global this object safely across environments
18
 * @returns Global object (globalThis/window/global/self)
19
 */
20
function getGlobalThis(): any;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { inBrowser, getGlobalThis } from "@intlify/shared";
27

28
// Environment-specific code
29
if (inBrowser) {
30
  // Browser-only code
31
  console.log("Running in browser");
32
  const userAgent = navigator.userAgent;
33
} else {
34
  // Node.js or other environment
35
  console.log("Running in non-browser environment");
36
}
37

38
// Access global object safely
39
const globalObj = getGlobalThis();
40
if (inBrowser) {
41
  // globalObj is window in browser
42
  console.log(globalObj.location?.href);
43
} else {
44
  // globalObj is global in Node.js
45
  console.log(globalObj.process?.version);
46
}
47
```
48

49
### Performance Measurement
50

51
Performance marking and measurement utilities for development debugging.
52

53
```typescript { .api }
54
/**
55
 * Performance marking function (development mode only)
56
 * Undefined in production builds
57
 */
58
let mark: (tag: string) => void | undefined;
59

60
/**
61
 * Performance measurement function (development mode only)
62
 * Undefined in production builds
63
 * @param name - Measurement name
64
 * @param startTag - Start mark tag
65
 * @param endTag - End mark tag
66
 */
67
let measure: (
68
  name: string,
69
  startTag: string,
70
  endTag: string
71
) => void | undefined;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { mark, measure } from "@intlify/shared";
78

79
// Performance measurement in development
80
function performHeavyOperation() {
81
  // Mark start of operation
82
  mark?.("heavy-operation-start");
83
  
84
  // Perform the operation
85
  doSomeHeavyWork();
86
  
87
  // Mark end of operation
88
  mark?.("heavy-operation-end");
89
  
90
  // Measure the duration
91
  measure?.("heavy-operation", "heavy-operation-start", "heavy-operation-end");
92
}
93

94
// Conditional usage with type safety
95
if (mark && measure) {
96
  mark("initialization-start");
97
  initializeApp();
98
  mark("initialization-end");
99
  measure("app-initialization", "initialization-start", "initialization-end");
100
}
101
```
102

103
### Development Environment
104

105
The performance utilities are only available in development mode (`__DEV__` is true) and when running in a browser environment with performance API support.
106

107
**Behavior:**
108
- In **development**: Functions use browser Performance API if available
109
- In **production**: Functions are `undefined` (tree-shaken out)
110
- In **non-browser environments**: Functions are `undefined`
111

112
**Performance API Requirements:**
113
- Browser must support `window.performance`
114
- Must have `mark`, `measure`, `clearMarks`, and `clearMeasures` methods
115

116
## Environment Detection Details
117

118
### Browser Detection
119

120
The `inBrowser` constant is determined at module load time:
121

122
```typescript
123
// Simplified implementation
124
const inBrowser = typeof window !== 'undefined';
125
```
126

127
This provides a reliable way to detect browser environments for:
128
- Conditional imports
129
- Platform-specific functionality
130
- Feature detection
131

132
### Global Object Access
133

134
The `getGlobalThis` function provides a unified way to access the global object across different JavaScript environments:
135

136
**Resolution Order:**
137
1. `globalThis` (modern standard)
138
2. `self` (Web Workers, Service Workers)
139
3. `window` (browsers)
140
4. `global` (Node.js)
141
5. Empty object fallback
142

143
**Usage Scenarios:**
144

145
```typescript
146
import { getGlobalThis, inBrowser } from "@intlify/shared";
147

148
const globalObj = getGlobalThis();
149

150
// Safe global variable access
151
function setGlobalVariable(key: string, value: any) {
152
  globalObj[key] = value;
153
}
154

155
function getGlobalVariable(key: string) {
156
  return globalObj[key];
157
}
158

159
// Environment-specific global access
160
if (inBrowser) {
161
  // Access browser-specific globals
162
  const location = globalObj.location;
163
  const document = globalObj.document;
164
} else {
165
  // Access Node.js-specific globals
166
  const process = globalObj.process;
167
  const buffer = globalObj.Buffer;
168
}
169
```
170

171
## Performance Monitoring Best Practices
172

173
### Development Usage
174

175
```typescript
176
import { mark, measure } from "@intlify/shared";
177

178
// Mark important application lifecycle events
179
function trackLifecycle() {
180
  mark?.("app-mount-start");
181
  mountApplication();
182
  mark?.("app-mount-end");
183
  
184
  mark?.("data-load-start");
185
  loadInitialData();
186
  mark?.("data-load-end");
187
  
188
  // Measure durations
189
  measure?.("app-mount-duration", "app-mount-start", "app-mount-end");
190
  measure?.("data-load-duration", "data-load-start", "data-load-end");
191
}
192
```
193

194
### Production Considerations
195

196
In production builds, performance utilities are `undefined` to:
197
- Reduce bundle size
198
- Eliminate runtime overhead
199
- Remove development-only code
200

201
Always use optional chaining or conditional checks:
202

203
```typescript
204
// Recommended: Optional chaining
205
mark?.("operation-start");
206

207
// Alternative: Conditional check
208
if (mark) {
209
  mark("operation-start");
210
}
211
```