0
# Configuration & Settings
1

2
Global and instance-level configuration options for customizing logger behavior, appearance, and output format. Signale provides flexible configuration through package.json global settings and per-instance options.
3

4
## Capabilities
5

6
### Instance Configuration
7

8
Configure individual Signale instances with runtime settings.
9

10
```javascript { .api }
11
/**
12
 * Update the configuration of a Signale instance
13
 * @param settingsObj - Configuration options object
14
 */
15
function config(settingsObj: ConfigOptions): void;
16

17
/**
18
 * Get the current package.json configuration
19
 */
20
readonly packageConfiguration: object;
21

22
interface ConfigOptions {
23
  displayScope?: boolean;      // Show scope names in output (default: true)
24
  displayBadge?: boolean;      // Show logger badges/icons (default: true) 
25
  displayDate?: boolean;       // Show date in output (default: false)
26
  displayFilename?: boolean;   // Show calling filename (default: false)
27
  displayLabel?: boolean;      // Show logger labels (default: true)
28
  displayTimestamp?: boolean;  // Show timestamp in output (default: false)
29
  underlineLabel?: boolean;    // Underline logger labels (default: true)
30
  underlineMessage?: boolean;  // Underline log messages (default: false)
31
  underlinePrefix?: boolean;   // Underline message prefixes (default: false)
32
  underlineSuffix?: boolean;   // Underline message suffixes (default: false)
33
  uppercaseLabel?: boolean;    // Display labels in uppercase (default: false)
34
}
35
```
36

37
### Global Configuration
38

39
Configure Signale globally through package.json settings.
40

41
**package.json Configuration:**
42

43
```json
44
{
45
  "signale": {
46
    "displayScope": true,
47
    "displayBadge": true,
48
    "displayDate": false,
49
    "displayFilename": false,
50
    "displayLabel": true,
51
    "displayTimestamp": false,
52
    "underlineLabel": true,
53
    "underlineMessage": false,
54
    "underlinePrefix": false,
55
    "underlineSuffix": false,
56
    "uppercaseLabel": false
57
  }
58
}
59
```
60

61
### Runtime Configuration
62

63
Change configuration settings at runtime for existing instances.
64

65
**Usage Examples:**
66

67
```javascript
68
const signale = require('signale');
69

70
// Default appearance
71
signale.success('Default configuration');
72
// Output: ✔  success  Default configuration
73

74
// Update configuration
75
signale.config({
76
  displayTimestamp: true,
77
  displayDate: true,
78
  displayFilename: true,
79
  uppercaseLabel: true
80
});
81

82
signale.success('Updated configuration');
83
// Output: [2023-12-07] [14:30:25] [index.js] › ✔  SUCCESS  Updated configuration
84

85
// Multiple configuration changes
86
signale.config({
87
  underlineMessage: true,
88
  underlineLabel: true,
89
  displayBadge: false
90
});
91

92
signale.info('Styled message');
93
// Output: [2023-12-07] [14:30:26] [index.js] › INFO  Styled message
94
// (with underlines applied)
95
```
96

97
### Constructor Configuration
98

99
Set configuration when creating new Signale instances.
100

101
**Usage Examples:**
102

103
```javascript
104
const { Signale } = require('signale');
105

106
// Instance with custom configuration
107
const styledLogger = new Signale({
108
  config: {
109
    displayDate: true,
110
    displayTimestamp: true,
111
    uppercaseLabel: true,
112
    underlineMessage: true
113
  }
114
});
115

116
styledLogger.info('Custom styled logger');
117
// Output: [2023-12-07] [14:30:25] › ℹ  INFO  Custom styled logger (underlined)
118

119
// Minimal configuration
120
const minimalLogger = new Signale({
121
  config: {
122
    displayBadge: false,
123
    displayLabel: false
124
  }
125
});
126

127
minimalLogger.success('Minimal output');
128
// Output: Minimal output (no badge or label)
129
```
130

131
### Display Options
132

133
Control what elements appear in log output.
134

135
**Usage Examples:**
136

137
```javascript
138
const { Signale } = require('signale');
139

140
// Show all available metadata
141
const verboseLogger = new Signale({
142
  config: {
143
    displayScope: true,
144
    displayBadge: true,
145
    displayDate: true,
146
    displayFilename: true,
147
    displayLabel: true,
148
    displayTimestamp: true
149
  }
150
});
151

152
const scoped = verboseLogger.scope('app', 'module');
153
scoped.info('Verbose logging enabled');
154
// Output: [2023-12-07] [14:30:25] [config-example.js] [app] [module] › ℹ  info  Verbose logging enabled
155

156
// Hide all metadata  
157
const cleanLogger = new Signale({
158
  config: {
159
    displayScope: false,
160
    displayBadge: false,
161
    displayDate: false,
162
    displayFilename: false,
163
    displayLabel: false,
164
    displayTimestamp: false
165
  }
166
});
167

168
cleanLogger.error('Clean output');
169
// Output: Clean output (no decorations)
170
```
171

172
### Text Styling Options
173

174
Control text styling and formatting.
175

176
**Usage Examples:**
177

178
```javascript
179
const { Signale } = require('signale');
180

181
// Underline everything
182
const underlinedLogger = new Signale({
183
  config: {
184
    underlineLabel: true,
185
    underlineMessage: true,
186
    underlinePrefix: true,
187
    underlineSuffix: true
188
  }
189
});
190

191
underlinedLogger.success({
192
  prefix: '[deploy]',
193
  message: 'Application deployed successfully', 
194
  suffix: '(v1.2.0)'
195
});
196
// Output: [deploy] ✔  success  Application deployed successfully (v1.2.0)
197
// (with underlines applied to label, message, prefix, and suffix)
198

199
// Uppercase labels
200
const uppercaseLogger = new Signale({
201
  config: {
202
    uppercaseLabel: true
203
  }
204
});
205

206
uppercaseLogger.warn('Uppercase labels enabled');
207
// Output: ⚠  WARNING  Uppercase labels enabled
208
```
209

210
### Configuration Inheritance
211

212
Configuration inheritance patterns with scoped loggers.
213

214
**Usage Examples:**
215

216
```javascript
217
const { Signale } = require('signale');
218

219
// Parent with configuration
220
const parent = new Signale({
221
  config: {
222
    displayTimestamp: true,
223
    uppercaseLabel: true
224
  }
225
});
226

227
// Scoped logger inherits configuration
228
const child = parent.scope('module');
229

230
parent.info('Parent logger');
231
// Output: [14:30:25] › ℹ  INFO  Parent logger
232

233
child.success('Child logger');  
234
// Output: [14:30:25] [module] › ✔  SUCCESS  Child logger
235

236
// Override configuration in child
237
child.config({
238
  displayTimestamp: false,
239
  displayDate: true
240
});
241

242
child.warn('Modified child logger');
243
// Output: [2023-12-07] [module] › ⚠  WARNING  Modified child logger
244
```
245

246
### File and Timestamp Display
247

248
Control filename and time information display.
249

250
**Usage Examples:**
251

252
```javascript
253
// config-demo.js
254
const { Signale } = require('signale');
255

256
const timestampLogger = new Signale({
257
  config: {
258
    displayDate: true,
259
    displayTimestamp: true,
260
    displayFilename: true
261
  }
262
});
263

264
timestampLogger.info('Time and file information');
265
// Output: [2023-12-07] [14:30:25] [config-demo.js] › ℹ  info  Time and file information
266

267
// Date only
268
const dateLogger = new Signale({
269
  config: {
270
    displayDate: true,
271
    displayTimestamp: false,
272
    displayFilename: false
273
  }
274
});
275

276
dateLogger.success('Date only');
277
// Output: [2023-12-07] › ✔  success  Date only
278

279
// Filename only
280
const fileLogger = new Signale({
281
  config: {
282
    displayDate: false,
283
    displayTimestamp: false,
284
    displayFilename: true
285
  }
286
});
287

288
fileLogger.warn('Filename only');
289
// Output: [config-demo.js] › ⚠  warning  Filename only
290
```
291

292
### Configuration Validation
293

294
Signale handles invalid configuration gracefully.
295

296
**Usage Examples:**
297

298
```javascript
299
const { Signale } = require('signale');
300

301
// Invalid options are ignored
302
const logger = new Signale({
303
  config: {
304
    displayBadge: true,
305
    invalidOption: 'ignored',    // This will be ignored
306
    displayLabel: 'not-boolean', // This will be ignored
307
    displayScope: true           // This will be applied
308
  }
309
});
310

311
logger.info('Configuration with invalid options');
312
// Output: [scope] › ℹ  info  Configuration with invalid options (works normally)
313

314
// Null/undefined config is handled safely
315
const safeLogger = new Signale({
316
  config: null  // No error thrown
317
});
318

319
safeLogger.success('Safe configuration');
320
// Output: ✔  success  Safe configuration (uses defaults)
321
```
322

323
### Dynamic Configuration
324

325
Change configuration multiple times during runtime.
326

327
**Usage Examples:**
328

329
```javascript
330
const signale = require('signale');
331

332
// Start with default configuration
333
signale.info('Default style');
334
// Output: ℹ  info  Default style
335

336
// Switch to verbose mode
337
signale.config({
338
  displayDate: true,
339
  displayTimestamp: true,
340
  displayFilename: true
341
});
342

343
signale.info('Verbose mode');
344
// Output: [2023-12-07] [14:30:25] [dynamic-config.js] › ℹ  info  Verbose mode
345

346
// Switch to minimal mode
347
signale.config({
348
  displayDate: false,
349
  displayTimestamp: false, 
350
  displayFilename: false,
351
  displayBadge: false,
352
  displayLabel: false
353
});
354

355
signale.info('Minimal mode');
356
// Output: Minimal mode
357

358
// Back to styled mode
359
signale.config({
360
  displayBadge: true,
361
  displayLabel: true,
362
  uppercaseLabel: true,
363
  underlineMessage: true
364
});
365

366
signale.success('Styled mode');
367
// Output: ✔  SUCCESS  Styled mode (with underline)
368
```