tryError Documentation

Plugin System

Extend tryError with reusable plugins that add new capabilities, integrations, and error types

Plugin Architecture

Plugins are self-contained modules that can hook into various aspects of tryError.

1import { Plugin, PluginMetadata, PluginHooks, PluginCapabilities } from 'tryError';
2
3interface Plugin {
4  // Plugin identification and dependencies
5  metadata: PluginMetadata;
6  
7  // Lifecycle hooks
8  hooks?: PluginHooks;
9  
10  // Features the plugin provides
11  capabilities?: PluginCapabilities;
12}
13
14interface PluginMetadata {
15  name: string;
16  version: string;
17  description?: string;
18  author?: string;
19  dependencies?: string[]; // Other plugins required
20}
21
22interface PluginHooks {
23  onInstall?: () => void | Promise<void>;
24  onUninstall?: () => void | Promise<void>;
25  onEnable?: () => void | Promise<void>;
26  onDisable?: () => void | Promise<void>;
27  onConfigChange?: (config: TryErrorConfig) => void | Promise<void>;
28}
29
30interface PluginCapabilities {
31  config?: Partial<TryErrorConfig>;
32  middleware?: ErrorMiddleware[];
33  errorTypes?: Record<string, (message: string, context?: any) => TryError>;
34  utilities?: Record<string, Function>;
35  transformers?: {
36    error?: (error: TryError) => TryError;
37    result?: <T>(result: TryResult<T>) => TryResult<T>;
38  };
39}

Using Plugins

1import { pluginManager } from 'tryError';
2import sentryPlugin from 'tryError-sentry';
3import datadogPlugin from 'tryError-datadog';
4
5// Install plugins
6await pluginManager.install(sentryPlugin);
7await pluginManager.install(datadogPlugin);
8
9// Enable plugins
10await pluginManager.enable('tryError-sentry');
11await pluginManager.enable('tryError-datadog');
12
13// Plugins with dependencies
14import advancedPlugin from 'tryError-advanced';
15
16// This plugin requires 'tryError-sentry'
17// The plugin manager ensures dependencies are installed
18await pluginManager.install(advancedPlugin);

Creating a Plugin

Build your own plugin to share functionality across projects or with the community.

1// my-plugin.ts
2import { Plugin } from 'tryError';
3
4export const myPlugin: Plugin = {
5  metadata: {
6    name: 'my-custom-plugin',
7    version: '1.0.0',
8    description: 'Adds custom error handling features',
9    author: 'Your Name'
10  },
11  
12  hooks: {
13    onInstall: async () => {
14      console.log('My plugin installed!');
15    },
16    
17    onEnable: async () => {
18      console.log('My plugin enabled!');
19      // Initialize resources
20    },
21    
22    onDisable: async () => {
23      console.log('My plugin disabled!');
24      // Cleanup resources
25    },
26    
27    onConfigChange: async (config) => {
28      console.log('Config changed:', config);
29      // React to configuration changes
30    }
31  },
32  
33  capabilities: {
34    // Add custom configuration
35    config: {
36      customOption: true,
37      debugMode: false
38    },
39    
40    // Add middleware
41    middleware: [
42      (result, next) => {
43        console.log('Plugin middleware executed');
44        return next();
45      }
46    ],
47    
48    // Add custom error types
49    errorTypes: {
50      CustomError: (message, context) => ({
51        [TRY_ERROR_BRAND]: true,
52        type: 'CustomError',
53        message,
54        source: 'my-plugin',
55        timestamp: Date.now(),
56        context
57      })
58    },
59    
60    // Add utility functions
61    utilities: {
62      customHelper: (value: any) => {
63        return `Processed: ${value}`;
64      }
65    }
66  }
67};

Example Plugins

Monitoring & Observability
Integrate with APM and monitoring services
tryError-sentry

Full Sentry integration with error tracking, breadcrumbs, and user context

tryError-datadog

DataDog APM integration with custom metrics and distributed tracing

tryError-newrelic

New Relic integration with error insights and custom attributes

Development Tools
Enhance development experience
tryError-devtools

Browser DevTools extension for debugging tryError in development

tryError-prettier

Pretty-print errors with syntax highlighting and formatting

tryError-testing

Testing utilities and matchers for Jest, Vitest, and Mocha

Framework Integrations
Seamless integration with popular frameworks
tryError-nextjs

Next.js integration with API routes and middleware support

tryError-express

Express middleware for automatic error handling in routes

tryError-graphql

GraphQL resolver error handling with proper error formatting

Plugin Development Best Practices

Version Compatibility
// Declare peer dependencies in package.json
{
  "peerDependencies": {
    "tryError": "^1.0.0"
  },
  "devDependencies": {
    "tryError": "^1.0.0"
  }
}

// Check version compatibility
if (!isCompatibleVersion(tryErrorVersion, '1.0.0')) {
  throw new Error('This plugin requires tryError v1.0.0 or higher');
}
Error Handling
// Always handle errors gracefully
hooks: {
  onEnable: async () => {
    try {
      await initializePlugin();
    } catch (error) {
      console.error('Failed to initialize plugin:', error);
      // Optionally disable the plugin
      throw new Error('Plugin initialization failed');
    }
  }
}

// Don't let middleware break the application
middleware: [
  (result, next) => {
    try {
      // Plugin logic
      doSomethingRisky();
    } catch (error) {
      // Log but don't throw
      console.error('Plugin error:', error);
    }
    return next();
  }
]
Resource Management
class MyPlugin implements Plugin {
  private resources: Resource[] = [];
  
  hooks = {
    onEnable: async () => {
      // Initialize resources
      this.resources.push(await createResource());
    },
    
    onDisable: async () => {
      // Always cleanup
      await Promise.all(
        this.resources.map(r => r.cleanup())
      );
      this.resources = [];
    },
    
    onUninstall: async () => {
      // Ensure cleanup even if not disabled first
      if (this.resources.length > 0) {
        await this.hooks.onDisable();
      }
    }
  };
}