0
# Storybook Client Logger
1

2
A client-side logging library for Storybook applications that provides configurable log levels, one-time logging, deprecation warnings, and styled console output. This package respects global LOGLEVEL settings and integrates seamlessly with browser console APIs.
3

4
## Package Information
5

6
- **Package Name**: @storybook/client-logger
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/client-logger`
10

11
## Core Imports
12

13
```typescript
14
import { logger, once, deprecate, pretty } from "@storybook/client-logger";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { logger, once, deprecate, pretty } = require("@storybook/client-logger");
21
```
22

23
Selective imports:
24

25
```typescript
26
import { logger } from "@storybook/client-logger";
27
import { once } from "@storybook/client-logger";
28
import { pretty } from "@storybook/client-logger";
29
import { deprecate } from "@storybook/client-logger";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { logger, once, deprecate, pretty } from "@storybook/client-logger";
36

37
// Basic logging
38
logger.info("Application started");
39
logger.warn("This is a warning");
40
logger.error("Something went wrong");
41

42
// One-time logging (won't repeat the same message)
43
once.warn("This warning will only show once per session");
44
once.info("First time setup complete");
45

46
// Deprecation warnings
47
deprecate("This feature is deprecated, use newFeature() instead");
48

49
// Styled logging with HTML-like formatting
50
pretty.info('<span style="color: blue; font-weight: bold">Styled message</span>');
51
```
52

53
## Configuration
54

55
The logger respects the global `LOGLEVEL` variable (accessed via `@storybook/global`) to control output. Log levels are numerical with lower numbers showing more messages:
56

57
- `trace` (level 1) - Shows all messages including trace
58
- `debug` (level 2) - Shows debug and above
59
- `info` (level 3) - Default level when LOGLEVEL is invalid or unset, shows info and above
60
- `warn` (level 4) - Shows warnings and errors only
61
- `error` (level 5) - Shows errors only
62
- `silent` (level 10) - Suppresses all output
63

64
**Implementation Notes:**
65
- If `LOGLEVEL` is not set or invalid, defaults to `info` level (3)
66
- Level filtering uses `<=` comparison (e.g., `currentLogLevelNumber <= levels.debug`)
67
- The `log` method respects all levels except `silent` (uses `< levels.silent` comparison)
68

69
## Capabilities
70

71
### Standard Logging
72

73
Core logging functionality with level-based filtering using native browser console methods.
74

75
```typescript { .api }
76
interface Logger {
77
  /** Trace level logging - lowest priority, includes stack trace */
78
  trace(message: any, ...rest: any[]): void;
79
  /** Debug level logging for development information */
80
  debug(message: any, ...rest: any[]): void;
81
  /** Info level logging for general information */
82
  info(message: any, ...rest: any[]): void;
83
  /** Warning level logging for non-critical issues */
84
  warn(message: any, ...rest: any[]): void;
85
  /** Error level logging for critical issues */
86
  error(message: any, ...rest: any[]): void;
87
  /** General logging that respects silent level */
88
  log(message: any, ...rest: any[]): void;
89
}
90

91
declare const logger: Logger;
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
import { logger } from "@storybook/client-logger";
98

99
// Different log levels
100
logger.trace("Detailed execution trace");
101
logger.debug("Debug information", { userId: 123 });
102
logger.info("User logged in successfully");
103
logger.warn("API rate limit approaching");
104
logger.error("Authentication failed", error);
105
logger.log("General message");
106
```
107

108
### One-Time Logging
109

110
Prevents duplicate log messages by tracking previously logged content. Each message is only displayed once per session.
111

112
```typescript { .api }
113
interface OnceLogger {
114
  /** Create a one-time logger for the specified level */
115
  (type: keyof Logger): (message: any, ...rest: any[]) => void | undefined;
116
  /** Clear the logged messages cache */
117
  clear(): void;
118
  /** One-time trace logging */
119
  trace(message: any, ...rest: any[]): void | undefined;
120
  /** One-time debug logging */
121
  debug(message: any, ...rest: any[]): void | undefined;
122
  /** One-time info logging */
123
  info(message: any, ...rest: any[]): void | undefined;
124
  /** One-time warning logging */
125
  warn(message: any, ...rest: any[]): void | undefined;
126
  /** One-time error logging */
127
  error(message: any, ...rest: any[]): void | undefined;
128
  /** One-time general logging */
129
  log(message: any, ...rest: any[]): void | undefined;
130
}
131

132
declare const once: OnceLogger;
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
import { once } from "@storybook/client-logger";
139

140
// These will only show once, even if called multiple times
141
once.warn("This feature will be removed in v9.0");
142
once.info("Welcome to the application");
143

144
// Dynamic one-time loggers
145
const onceError = once('error');
146
onceError("Critical system error occurred");
147

148
// Clear the cache to allow messages to show again
149
once.clear();
150
```
151

152
### Deprecation Warnings
153

154
Specialized one-time warning function for deprecation notices.
155

156
```typescript { .api }
157
/** 
158
 * Log a deprecation warning that will only appear once per session
159
 * Alias for once('warn')
160
 */
161
declare function deprecate(message: any, ...rest: any[]): void | undefined;
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
import { deprecate } from "@storybook/client-logger";
168

169
deprecate("myOldFunction() is deprecated, use myNewFunction() instead");
170
deprecate("Config option 'oldOption' is deprecated", { 
171
  suggestion: "Use 'newOption' instead" 
172
});
173
```
174

175
### Styled Logging
176

177
Enhanced logging with HTML-style span formatting for colored and styled console output.
178

179
```typescript { .api }
180
interface PrettyLogger {
181
  /** Create a pretty logger for the specified level */
182
  (type: keyof Logger): (...args: Parameters<LoggingFn>) => void;
183
  /** Pretty trace logging with styling support */
184
  trace(...args: Parameters<LoggingFn>): void;
185
  /** Pretty debug logging with styling support */
186
  debug(...args: Parameters<LoggingFn>): void;
187
  /** Pretty info logging with styling support */
188
  info(...args: Parameters<LoggingFn>): void;
189
  /** Pretty warning logging with styling support */
190
  warn(...args: Parameters<LoggingFn>): void;
191
  /** Pretty error logging with styling support */
192
  error(...args: Parameters<LoggingFn>): void;
193
}
194

195
declare const pretty: PrettyLogger;
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
import { pretty } from "@storybook/client-logger";
202

203
// Styled messages using HTML-like span tags
204
pretty.info('<span style="color: blue; font-weight: bold">Important:</span> System ready');
205
pretty.warn('<span style="color: orange">Warning:</span> <span style="font-style: italic">Check configuration</span>');
206
pretty.error('<span style="color: red; text-decoration: underline">Error:</span> Connection failed');
207

208
// Dynamic pretty loggers
209
const prettyDebug = pretty('debug');
210
prettyDebug('<span style="color: green">DEBUG:</span> User action completed');
211
```
212

213
The pretty logger converts HTML-style `<span style="...">` tags into console formatting directives, enabling colored and styled output in browser developer tools.
214

215
## Types
216

217
```typescript { .api }
218
/** Log level configuration options */
219
type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
220

221
/** Standard logging function signature */
222
type LoggingFn = (message: any, ...args: any[]) => void;
223
```
224

225
## Error Handling
226

227
The logger is designed to be robust and will gracefully handle:
228

229
- Invalid log levels (defaults to 'info')
230
- Missing global LOGLEVEL (defaults to 'info') 
231
- Console method unavailability (fails silently)
232
- Malformed HTML in pretty logger (renders as plain text)
233

234
## Browser Compatibility
235

236
This library is designed for browser environments and uses:
237

238
- `console.trace()`, `console.debug()`, `console.info()`, `console.warn()`, `console.error()`, `console.log()`
239
- Browser console styling capabilities for pretty logging
240
- Global object access for configuration