0
# @sentry/minimal
1

2
@sentry/minimal is a lightweight Sentry SDK designed specifically for library authors. It provides a minimal set of Sentry functions that delegate to a configured client when embedded into an application, allowing libraries to add error tracking without bundling the entire SDK or being dependent on a specific platform.
3

4
## Package Information
5

6
- **Package Name**: @sentry/minimal
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @sentry/minimal`
10

11
## Core Imports
12

13
```typescript
14
import * as Sentry from '@sentry/minimal';
15
```
16

17
Individual imports:
18

19
```typescript
20
import {
21
  captureException,
22
  captureMessage,
23
  captureEvent,
24
  addBreadcrumb,
25
  configureScope,
26
  withScope,
27
  setUser,
28
  setTag,
29
  setTags,
30
  setExtra,
31
  setExtras,
32
  setContext,
33
  startTransaction
34
} from '@sentry/minimal';
35
```
36

37
For CommonJS:
38

39
```javascript
40
const Sentry = require('@sentry/minimal');
41
const { captureException, captureMessage } = require('@sentry/minimal');
42
```
43

44
## Basic Usage
45

46
```typescript
47
import * as Sentry from '@sentry/minimal';
48

49
// Add a breadcrumb for future events
50
Sentry.addBreadcrumb({
51
  message: 'User clicked button',
52
  category: 'ui',
53
  level: 'info'
54
});
55

56
// Capture exceptions, messages or manual events
57
Sentry.captureMessage('Hello, world!');
58
Sentry.captureException(new Error('Something went wrong'));
59
Sentry.captureEvent({
60
  message: 'Manual event',
61
  level: 'warning'
62
});
63

64
// Set context information
65
Sentry.configureScope(scope => {
66
  scope.setUser({ id: '4711', email: 'user@example.com' });
67
  scope.setTag('component', 'MyLibrary');
68
  scope.setExtra('debug_info', { version: '1.0.0' });
69
});
70
```
71

72
## Architecture
73

74
@sentry/minimal operates as a thin wrapper that:
75

76
- **Delegates Operations**: All functions delegate to the current Sentry hub via `getCurrentHub()`
77
- **No SDK Initialization**: Library authors don't need to initialize the SDK - it uses whatever client is configured by the consuming application
78
- **Error Handling**: Throws descriptive errors when no hub is available or methods are missing
79
- **Lightweight**: Minimal bundle size with only essential functionality for library instrumentation
80

81
## Capabilities
82

83
### Exception Capture
84

85
Captures exception events and sends them to Sentry.
86

87
```typescript { .api }
88
/**
89
 * Captures an exception event and sends it to Sentry.
90
 * @param exception - An exception-like object
91
 * @param captureContext - Optional context for the capture operation
92
 * @returns The generated eventId
93
 */
94
function captureException(exception: any, captureContext?: CaptureContext): string;
95

96
type CaptureContext = Scope | Partial<ScopeContext> | ((scope: Scope) => Scope);
97

98
interface ScopeContext {
99
  user: User;
100
  level: Severity;
101
  extra: Extras;
102
  contexts: Contexts;
103
  tags: Record<string, Primitive>;
104
  fingerprint: string[];
105
  requestSession: RequestSession;
106
}
107
```
108

109
### Message Capture
110

111
Captures message events and sends them to Sentry.
112

113
```typescript { .api }
114
/**
115
 * Captures a message event and sends it to Sentry.
116
 * @param message - The message to send to Sentry
117
 * @param captureContext - Optional context or severity level
118
 * @returns The generated eventId
119
 */
120
function captureMessage(message: string, captureContext?: CaptureContext | Severity): string;
121

122
enum Severity {
123
  Fatal = 'fatal',
124
  Error = 'error',
125
  Warning = 'warning',
126
  Log = 'log',
127
  Info = 'info',
128
  Debug = 'debug',
129
  Critical = 'critical'
130
}
131
```
132

133
### Event Capture
134

135
Captures manually created events and sends them to Sentry.
136

137
```typescript { .api }
138
/**
139
 * Captures a manually created event and sends it to Sentry.
140
 * @param event - The event to send to Sentry
141
 * @returns The generated eventId
142
 */
143
function captureEvent(event: Event): string;
144

145
interface Event {
146
  event_id?: string;
147
  message?: string;
148
  timestamp?: number;
149
  start_timestamp?: number;
150
  level?: Severity;
151
  platform?: string;
152
  logger?: string;
153
  server_name?: string;
154
  release?: string;
155
  dist?: string;
156
  environment?: string;
157
  sdk?: SdkInfo;
158
  request?: Request;
159
  transaction?: string;
160
  modules?: Record<string, string>;
161
  fingerprint?: string[];
162
  exception?: {
163
    values?: Exception[];
164
  };
165
  stacktrace?: Stacktrace;
166
  breadcrumbs?: Breadcrumb[];
167
  contexts?: Contexts;
168
  tags?: Record<string, Primitive>;
169
  extra?: Extras;
170
  user?: User;
171
  type?: EventType;
172
  spans?: Span[];
173
  measurements?: Measurements;
174
  debug_meta?: DebugMeta;
175
  sdkProcessingMetadata?: Record<string, any>;
176
}
177
```
178

179
### Breadcrumb Management
180

181
Records breadcrumbs which will be attached to future events.
182

183
```typescript { .api }
184
/**
185
 * Records a new breadcrumb which will be attached to future events.
186
 * Breadcrumbs provide context on user actions prior to an error or crash.
187
 * @param breadcrumb - The breadcrumb to record
188
 */
189
function addBreadcrumb(breadcrumb: Breadcrumb): void;
190

191
interface Breadcrumb {
192
  message?: string;
193
  category?: string;
194
  level?: Severity;
195
  timestamp?: number;
196
  type?: string;
197
  data?: Record<string, any>;
198
}
199
```
200

201
### Scope Configuration
202

203
Configures context information that will be attached to events.
204

205
```typescript { .api }
206
/**
207
 * Callback to set context information onto the scope.
208
 * @param callback - Callback function that receives the current scope
209
 */
210
function configureScope(callback: (scope: Scope) => void): void;
211

212
/**
213
 * Creates a new scope and executes the given operation within it.
214
 * The scope is automatically removed once the operation finishes or throws.
215
 * @param callback - Callback that will be enclosed in push/popScope
216
 */
217
function withScope(callback: (scope: Scope) => void): void;
218

219
interface Scope {
220
  setUser(user: User | null): this;
221
  setTag(key: string, value: Primitive): this;
222
  setTags(tags: Record<string, Primitive>): this;
223
  setExtra(key: string, extra: any): this;
224
  setExtras(extras: Record<string, any>): this;
225
  setContext(name: string, context: Record<string, any> | null): this;
226
  setLevel(level: Severity): this;
227
  setFingerprint(fingerprint: string[]): this;
228
  clear(): this;
229
}
230
```
231

232
### Context Management
233

234
Functions for setting various types of context information.
235

236
```typescript { .api }
237
/**
238
 * Updates user context information for future events.
239
 * @param user - User context object or null to unset
240
 */
241
function setUser(user: User | null): void;
242

243
/**
244
 * Set key:value that will be sent as tags data with events.
245
 * Can also be used to unset a tag by passing undefined.
246
 * @param key - String key of tag
247
 * @param value - Value of tag
248
 */
249
function setTag(key: string, value: Primitive): void;
250

251
/**
252
 * Set an object that will be merged as tags data with events.
253
 * @param tags - Tags context object to merge into current context
254
 */
255
function setTags(tags: Record<string, Primitive>): void;
256

257
/**
258
 * Set key:value that will be sent as extra data with events.
259
 * @param key - String key of extra data
260
 * @param extra - Any kind of data (will be normalized)
261
 */
262
function setExtra(key: string, extra: any): void;
263

264
/**
265
 * Set an object that will be merged as extra data with events.
266
 * @param extras - Extras object to merge into current context
267
 */
268
function setExtras(extras: Record<string, any>): void;
269

270
/**
271
 * Sets context data with the given name.
272
 * @param name - Name of the context
273
 * @param context - Any kind of data (will be normalized)
274
 */
275
function setContext(name: string, context: Record<string, any> | null): void;
276

277
interface User {
278
  id?: string;
279
  username?: string;
280
  email?: string;
281
  ip_address?: string;
282
  [key: string]: any;
283
}
284

285
type Primitive = number | string | boolean | bigint | symbol | null | undefined;
286
```
287

288
### Transaction Management
289

290
Creates transactions for manual tracing instrumentation.
291

292
```typescript { .api }
293
/**
294
 * Starts a new Transaction and returns it. This is the entry point to manual tracing instrumentation.
295
 * The transaction must be finished with a call to its .finish() method.
296
 * @param context - Properties of the new Transaction
297
 * @param customSamplingContext - Information given to the transaction sampling function
298
 * @returns The transaction which was just started
299
 */
300
function startTransaction(
301
  context: TransactionContext,
302
  customSamplingContext?: CustomSamplingContext
303
): Transaction;
304

305
interface TransactionContext extends SpanContext {
306
  /** Human-readable identifier for the transaction */
307
  name: string;
308
  /** If true, sets end timestamp to highest child span timestamp */
309
  trimEnd?: boolean;
310
  /** If this transaction has a parent, the parent's sampling decision */
311
  parentSampled?: boolean;
312
  /** Metadata associated with the transaction, for internal SDK use */
313
  metadata?: TransactionMetadata;
314
}
315

316
interface SpanContext {
317
  description?: string;
318
  op?: string;
319
  status?: string;
320
  parentSpanId?: string;
321
  sampled?: boolean;
322
  spanId?: string;
323
  traceId?: string;
324
  tags?: Record<string, Primitive>;
325
  data?: Record<string, any>;
326
  startTimestamp?: number;
327
  endTimestamp?: number;
328
}
329

330
interface CustomSamplingContext {
331
  [key: string]: any;
332
}
333

334
interface Transaction extends TransactionContext, Span {
335
  spanId: string;
336
  traceId: string;
337
  startTimestamp: number;
338
  tags: Record<string, Primitive>;
339
  data: Record<string, any>;
340
  metadata: TransactionMetadata;
341
  
342
  /** Set the name of the transaction */
343
  setName(name: string): void;
344
  /** Returns current transaction properties as TransactionContext */
345
  toContext(): TransactionContext;
346
  /** Updates the current transaction with a new TransactionContext */
347
  updateWithContext(transactionContext: TransactionContext): this;
348
}
349

350
interface TransactionMetadata {
351
  transactionSampling?: { rate?: number; method: TransactionSamplingMethod };
352
  tracestate?: { sentry?: string; thirdparty?: string };
353
  requestPath?: string;
354
}
355

356
type TransactionSamplingMethod = 'explicitly_set' | 'client_sampler' | 'client_rate' | 'inheritance';
357
```
358

359
### Internal Client Access
360

361
Internal helper function for calling methods on the latest client.
362

363
```typescript { .api }
364
/**
365
 * Calls a function on the latest client. Use with caution - meant as internal helper.
366
 * Not guaranteed that the client actually implements the function.
367
 * @param method - The method to call on the client
368
 * @param args - Arguments to pass to the client method
369
 * @hidden
370
 */
371
function _callOnClient(method: string, ...args: any[]): void;
372
```
373

374
## Types
375

376
```typescript { .api }
377
interface Exception {
378
  type?: string;
379
  value?: string;
380
  module?: string;
381
  thread_id?: string;
382
  stacktrace?: {
383
    frames?: StackFrame[];
384
  };
385
}
386

387
interface StackFrame {
388
  filename?: string;
389
  function?: string;
390
  module?: string;
391
  platform?: string;
392
  lineno?: number;
393
  colno?: number;
394
  abs_path?: string;
395
  context_line?: string;
396
  pre_context?: string[];
397
  post_context?: string[];
398
  in_app?: boolean;
399
  vars?: Record<string, any>;
400
}
401

402
interface Request {
403
  url?: string;
404
  method?: string;
405
  data?: any;
406
  query_string?: string;
407
  cookies?: Record<string, string>;
408
  headers?: Record<string, string>;
409
  env?: Record<string, string>;
410
}
411

412
interface Span extends SpanContext {
413
  spanId: string;
414
  traceId: string;
415
  startTimestamp: number;
416
  tags: Record<string, Primitive>;
417
  data: Record<string, any>;
418
  transaction?: Transaction;
419
  
420
  /** Sets the finish timestamp on the current span */
421
  finish(endTimestamp?: number): void;
422
  /** Sets the tag attribute on the current span */
423
  setTag(key: string, value: Primitive): this;
424
  /** Sets the data attribute on the current span */
425
  setData(key: string, value: any): this;
426
  /** Sets the status attribute on the current span */
427
  setStatus(status: string): this;
428
  /** Sets the status attribute based on http code */
429
  setHttpStatus(httpStatus: number): this;
430
  /** Creates a new Span while setting current Span.id as parentSpanId */
431
  startChild(spanContext?: Pick<SpanContext, Exclude<keyof SpanContext, 'spanId' | 'sampled' | 'traceId' | 'parentSpanId'>>): Span;
432
  /** Determines whether span was successful */
433
  isSuccess(): boolean;
434
  /** Return a traceparent compatible header string */
435
  toTraceparent(): string;
436
  /** Returns current span properties as SpanContext */
437
  toContext(): SpanContext;
438
  /** Updates the current span with a new SpanContext */
439
  updateWithContext(spanContext: SpanContext): this;
440
  /** Convert the object to JSON for spans array info only */
441
  getTraceContext(): {
442
    data?: Record<string, any>;
443
    description?: string;
444
    op?: string;
445
    parent_span_id?: string;
446
    span_id: string;
447
    status?: string;
448
    tags?: Record<string, Primitive>;
449
    trace_id: string;
450
  };
451
  /** Convert the object to JSON */
452
  toJSON(): {
453
    data?: Record<string, any>;
454
    description?: string;
455
    op?: string;
456
    parent_span_id?: string;
457
    span_id: string;
458
    start_timestamp: number;
459
    status?: string;
460
    tags?: Record<string, Primitive>;
461
    timestamp?: number;
462
    trace_id: string;
463
  };
464
}
465

466
// Additional supporting types
467
interface Exception {
468
  type?: string;
469
  value?: string;
470
  mechanism?: Mechanism;
471
  module?: string;
472
  thread_id?: number;
473
  stacktrace?: Stacktrace;
474
}
475

476
interface StackFrame {
477
  filename?: string;
478
  function?: string;
479
  module?: string;
480
  platform?: string;
481
  lineno?: number;
482
  colno?: number;
483
  abs_path?: string;
484
  context_line?: string;
485
  pre_context?: string[];
486
  post_context?: string[];
487
  in_app?: boolean;
488
  instruction_addr?: string;
489
  addr_mode?: string;
490
  vars?: Record<string, any>;
491
}
492

493
interface Request {
494
  url?: string;
495
  method?: string;
496
  data?: any;
497
  query_string?: QueryParams;
498
  cookies?: Record<string, string>;
499
  env?: Record<string, string>;
500
  headers?: Record<string, string>;
501
}
502

503
interface Stacktrace {
504
  frames?: StackFrame[];
505
}
506

507
interface SdkInfo {
508
  name?: string;
509
  version?: string;
510
  integrations?: string[];
511
  packages?: Package[];
512
}
513

514
interface Package {
515
  name: string;
516
  version: string;
517
}
518

519
interface Mechanism {
520
  type: string;
521
  description?: string;
522
  help_link?: string;
523
  handled?: boolean;
524
  data?: Record<string, any>;
525
  synthetic?: boolean;
526
}
527

528
interface DebugMeta {
529
  images?: DebugImage[];
530
}
531

532
interface DebugImage {
533
  type: string;
534
  debug_id?: string;
535
  code_id?: string;
536
  name?: string;
537
}
538

539
interface RequestSession {
540
  status?: RequestSessionStatus;
541
}
542

543
type Contexts = Record<string, Context>;
544
type Context = Record<string, any>;
545
type EventType = 'transaction' | 'default';
546
type Measurements = Record<string, { value: number }>;
547
type QueryParams = string | Record<string, string> | Array<[string, string]>;
548
type RequestSessionStatus = 'ok' | 'errored' | 'crashed';
549
```
550

551
## Error Handling
552

553
All functions will throw an error if:
554
- No hub is defined (`getCurrentHub()` returns undefined)
555
- The requested method is not found on the hub
556

557
The error message format is: `"No hub defined or ${method} was not found on the hub, please open a bug report."`
558

559
## Usage Notes
560

561
- **No Initialization Required**: Library authors should not initialize the SDK - this is handled by the consuming application's main Sentry SDK
562
- **Context Isolation**: Use `withScope()` to isolate context changes to prevent interfering with the user's global context
563
- **Minimal Interference**: Be cautious when setting user context, tags, or extras as these might override the user's values
564
- **Type Safety**: All functions are fully typed for TypeScript usage with proper generic support where applicable
565
- **Lazy Evaluation**: All operations are synchronous and delegate immediately to the configured hub