0
# Color Detection and Configuration
1

2
Kleur automatically detects terminal color support and provides manual override capabilities. Both the main API and colors API share the same detection logic but use different configuration interfaces.
3

4
## Automatic Detection
5

6
Kleur automatically detects color support based on environment variables and TTY context.
7

8
### Detection Logic
9

10
```javascript { .api }
11
// Pseudo-code for detection logic
12
const colorSupport = 
13
  !NODE_DISABLE_COLORS &&           // Not explicitly disabled
14
  NO_COLOR == null &&               // NO_COLOR not set
15
  TERM !== 'dumb' &&                // Not a dumb terminal
16
  (
17
    FORCE_COLOR != null &&          // FORCE_COLOR is set and not '0'
18
    FORCE_COLOR !== '0' ||
19
    isTTY                           // Or running in a TTY context
20
  );
21
```
22

23
### Environment Variables
24

25
The following environment variables affect color detection:
26

27
- **`FORCE_COLOR`**: Force enable colors (set to non-'0' value) or disable (set to '0')
28
- **`NODE_DISABLE_COLORS`**: Disable colors when set to any value
29
- **`NO_COLOR`**: Disable colors when set to any value (follows NO_COLOR standard)
30
- **`TERM`**: Terminal type, colors disabled when set to 'dumb'
31

32
### TTY Context
33

34
Colors are automatically disabled in non-TTY contexts such as:
35
- Piped output (`node app.js | grep error`)
36
- Redirected output (`node app.js > log.txt`)
37
- Process spawning contexts
38

39
## Manual Configuration
40

41
Override automatic detection for both APIs.
42

43
### Main API Configuration
44

45
```javascript { .api }
46
kleur.enabled: boolean;
47
```
48

49
### Colors API Configuration
50

51
```javascript { .api }
52
declare const $: { enabled: boolean };
53
```
54

55
## Usage Examples
56

57
### Environment Variable Control
58

59
```bash
60
# Force colors in piped output
61
FORCE_COLOR=1 node app.js > log.txt
62

63
# Disable colors explicitly
64
NODE_DISABLE_COLORS=1 node app.js
65

66
# Use NO_COLOR standard
67
NO_COLOR=1 node app.js
68

69
# Disable colors by setting FORCE_COLOR to '0'
70
FORCE_COLOR=0 node app.js
71
```
72

73
### Manual Override - Main API
74

75
```javascript
76
import kleur from "kleur";
77

78
// Check current state
79
console.log("Colors enabled:", kleur.enabled);
80

81
// Disable colors manually
82
kleur.enabled = false;
83
console.log(kleur.red("Won't be colored"));
84

85
// Re-enable colors
86
kleur.enabled = true;
87
console.log(kleur.red("Will be colored"));
88

89
// Conditional based on environment
90
kleur.enabled = process.env.NODE_ENV !== 'test';
91

92
// Use external color detection library
93
kleur.enabled = require('color-support').level > 0;
94
```
95

96
### Manual Override - Colors API
97

98
```javascript
99
import { $, red, green } from "kleur/colors";
100

101
// Check current state
102
console.log("Colors enabled:", $.enabled);
103

104
// Disable colors manually
105
$.enabled = false;
106
console.log(red("Won't be colored"));
107

108
// Re-enable colors
109
$.enabled = true;
110
console.log(red("Will be colored"));
111

112
// Conditional based on environment
113
$.enabled = process.env.NODE_ENV !== 'test';
114

115
// Use external color detection library
116
$.enabled = require('color-support').level > 0;
117
```
118

119
### Runtime Detection Examples
120

121
```javascript
122
import kleur from "kleur";
123

124
// Detect CI environments
125
if (process.env.CI) {
126
  kleur.enabled = process.env.FORCE_COLOR === '1';
127
}
128

129
// Detect specific terminals
130
if (process.env.TERM_PROGRAM === 'vscode') {
131
  kleur.enabled = true; // VS Code supports colors
132
}
133

134
// Detect Windows Command Prompt
135
if (process.platform === 'win32' && !process.env.CI) {
136
  kleur.enabled = process.stdout.isTTY;
137
}
138

139
// Progressive enhancement
140
function setupColors() {
141
  // Start with automatic detection
142
  const autoDetected = kleur.enabled;
143
  
144
  // Override for known environments
145
  if (process.env.NODE_ENV === 'test') {
146
    kleur.enabled = false;
147
  } else if (process.env.DEBUG) {
148
    kleur.enabled = true; // Always show colors in debug mode
149
  }
150
  
151
  console.log(`Colors: auto=${autoDetected}, final=${kleur.enabled}`);
152
}
153
```
154

155
## Cross-Platform Compatibility
156

157
### Windows Support
158

159
```javascript
160
// Windows-specific considerations
161
if (process.platform === 'win32') {
162
  // Windows Terminal and modern terminals support colors
163
  // Legacy Command Prompt may have limited support
164
  const windowsColorSupport = 
165
    process.env.WT_SESSION ||              // Windows Terminal
166
    process.env.TERM_PROGRAM === 'vscode' || // VS Code terminal
167
    process.env.TERM === 'xterm-256color';   // Other modern terminals
168
    
169
  if (windowsColorSupport) {
170
    kleur.enabled = true;
171
  }
172
}
173
```
174

175
### Unix/Linux Support
176

177
```javascript
178
// Unix-like systems generally have good color support
179
if (process.platform !== 'win32') {
180
  // Most Unix terminals support colors
181
  // Check for specific terminal capabilities
182
  const colorTerms = ['xterm', 'xterm-color', 'xterm-256color', 'screen', 'screen-256color'];
183
  const supportsColor = colorTerms.some(term => process.env.TERM?.includes(term));
184
  
185
  if (supportsColor) {
186
    kleur.enabled = true;
187
  }
188
}
189
```
190

191
### Docker and Container Support
192

193
```javascript
194
// Container-specific detection
195
function detectContainerColors() {
196
  // Check for Docker environment
197
  if (process.env.DOCKER_CONTAINER) {
198
    // Colors work in Docker if TTY is available
199
    return process.stdout.isTTY;
200
  }
201
  
202
  // Check for other container runtimes
203
  if (process.env.KUBERNETES_SERVICE_HOST) {
204
    // Kubernetes pods may not have TTY
205
    return process.env.FORCE_COLOR === '1';
206
  }
207
  
208
  return kleur.enabled; // Use default detection
209
}
210

211
kleur.enabled = detectContainerColors();
212
```