🚀 Obsly SDK Angular

📋 Table of Contents

• Overview
• Features
• Installation
• Usage
  • Angular 18+
  • Other Angular Versions
• Best Practices
• Getting Help

🔍 Overview

The @obslysdk/angular package provides a comprehensive suite of utilities for Angular applications. Currently, it includes a custom global error handler for seamless error tracking and monitoring, with plans to expand the toolkit to include:

• HTTP interceptors for request/response handling
• Services for common functionality
• Additional utilities to enhance Angular applications

The error handler is specifically designed for Angular's error handling system, ensuring that no critical errors go unnoticed in your production environment. As the package evolves, more features will be added to provide a complete development toolkit.

✨ Features

• Global Error Handling: Automatically captures and reports all unhandled errors
• Angular-specific Error Context: Provides detailed stack traces with Angular component context
• Multiple Error Handlers: Support for combining multiple custom error handlers with the CombinedErrorHandler
• Minimal Performance Impact: Lightweight implementation with negligible overhead
• TypeScript Support: Full TypeScript support with type definitions included
• Easy Integration: Simple setup process with minimal configuration required

📦 Installation

# Using npm
npm install @obslysdk/angular

# Using yarn
yarn add @obslysdk/angular

# Using bun
bun add @obslysdk/angular

🔧 Usage

main.ts (Recommended)

In your app.config.ts (or in your configuration in main.ts):

import { ApplicationConfig, ErrorHandler } from '@angular/core'
import { ObslyErrorHandler } from '@obslysdk/angular'

export const appConfig: ApplicationConfig = {
  providers: [
    // ... other providers
    { provide: ErrorHandler, useClass: ObslyErrorHandler, deps: [] }
  ]
}

In your main.ts:

import { bootstrapApplication } from '@angular/platform-browser'
import { appConfig } from './app/app.config'
import { AppComponent } from './app/app.component'

bootstrapApplication(AppComponent, appConfig).catch(err =>
  console.error('Application bootstrap failed:', err)
)

Module-based registration

In your app.module.ts:

import { NgModule, ErrorHandler } from '@angular/core'
import { ObslyErrorHandler } from '@obslysdk/angular'

@NgModule({
  // ... other module configurations
  providers: [{ provide: ErrorHandler, useClass: ObslyErrorHandler, deps: [] }]
})
export class AppModule {}

Note: While module-based registration works for most scenarios, it's recommended to register the error handler at the highest possible level in your application. Registration inside feature modules or lazy-loaded modules may result in some errors not being captured, especially during bootstrapping or in code that executes before the module is loaded.

Using Multiple Error Handlers

If you already have a custom error handler and want to use it alongside the Obsly error handler, our SDK provides a CombinedErrorHandler that allows you to use multiple error handlers simultaneously. This way, you can maintain your existing error handling logic while also benefiting from Obsly's error tracking:

import { ApplicationConfig, ErrorHandler } from '@angular/core'
import {
  ObslyErrorHandler,
  CombinedErrorHandler,
  CUSTOM_ERROR_HANDLERS
} from '@obslysdk/angular'
import { CustomErrorHandler } from './your-custom-handler'

export const appConfig: ApplicationConfig = {
  providers: [
    // Register your custom error handlers
    {
      provide: CUSTOM_ERROR_HANDLERS,
      useClass: ObslyErrorHandler,
      multi: true,
      deps: []
    },
    {
      provide: CUSTOM_ERROR_HANDLERS,
      useClass: CustomErrorHandler,
      multi: true,
      deps: []
    },
    // Use the CombinedErrorHandler as the main error handler
    { provide: ErrorHandler, useClass: CombinedErrorHandler, deps: [] }
  ]
}

In your main.ts:

import { bootstrapApplication } from '@angular/platform-browser'
import { appConfig } from './app/app.config'
import { AppComponent } from './app/app.component'

bootstrapApplication(AppComponent, appConfig).catch(err =>
  console.error('Application bootstrap failed:', err)
)

💡 Best Practices

• Initialize the error handler as early as possible in your application lifecycle
• Avoid wrapping the error handler with other error handling mechanisms
• Use TypeScript for better type safety and development experience
• Consider environment-specific configuration for development and production

🤝 Getting Help

We're here to support you in implementing and using the Obsly SDK in your Angular applications:

• Email Support: Contact us at [email protected]
• Documentation: Visit our official documentation
• GitHub Issues: Report bugs or suggest features through our GitHub repository