Dependency Injection in Chrome Extensions: A Complete Guide

28 min read

Dependency Injection in Chrome Extensions: A Complete Guide

· 28 min read · Chrome Extensions, Architecture

Dependency Injection in Chrome Extensions: A Complete Guide

Dependency injection has become one of the most important software design patterns in modern application development, and Chrome extensions are no exception. As extensions grow in complexity, managing dependencies between different components becomes increasingly challenging. This guide explores how to implement dependency injection in Chrome extensions, with a focus on the popular Inversify library, and demonstrates why this pattern is essential for building maintainable, testable extension architectures.

Understanding Dependency Injection

Dependency injection is a technique where an object receives other objects it depends on, rather than creating them internally. This inversion of control fundamentally changes how you structure your code and offers significant benefits for Chrome extension development.

In traditional programming, a class that needs a service or utility typically creates it directly:

class TabManager {
  constructor() {
    this.storage = new ChromeStorage();
    this.notifier = new NotificationService();
  }
  
  async saveTabs(tabs) {
    await this.storage.set('tabs', tabs);
    this.notifier.show('Tabs saved!');
  }
}

This approach creates tight coupling between components. The TabManager class is directly responsible for creating its dependencies, making it difficult to test in isolation or swap implementations later. When you need to mock ChromeStorage for unit tests, you cannot do so without modifying the actual class implementation.

Dependency injection resolves this by injecting dependencies from outside:

class TabManager {
  constructor(storage, notifier) {
    this.storage = storage;
    this.notifier = notifier;
  }
  
  async saveTabs(tabs) {
    await this.storage.set('tabs', tabs);
    this.notifier.show('Tabs saved!');
  }
}

// Usage
const storage = new ChromeStorage();
const notifier = new NotificationService();
const tabManager = new TabManager(storage, notifier);

Now TabManager is decoupled from its dependencies. You can easily pass mock implementations during testing or swap the NotificationService for a different implementation without touching the TabManager class itself.

Why Dependency Injection Matters for Chrome Extensions

Chrome extensions present unique challenges that make dependency injection particularly valuable:

Multiple Entry Points: Extensions have service workers, content scripts, popup pages, and options pages that all need to share functionality. DI provides a clean way to inject shared services across these different contexts.

Complex Messaging Systems: Chrome extensions rely heavily on message passing between components. DI helps organize the handlers and services that respond to these messages.

Testing Constraints: Extensions run in a constrained browser environment. DI makes it possible to mock Chrome APIs and test business logic without actual browser context.

Version Migration: As Chrome extension APIs evolve, you may need to swap implementations. DI makes this transition smoother by isolating API-specific code.

Setting Up Inversify in Your Extension

Inversify is a powerful dependency injection library for TypeScript and JavaScript. It provides a complete solution with features like constructor injection, property injection, decorators, and container management. Here’s how to set it up in your Chrome extension.

Installation

First, install the required packages:

npm install inversify reflect-metadata

Add the following to your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true
  }
}

Creating Your Service Container

The Inversify container is the core of your dependency injection setup. It manages the registration and resolution of dependencies:

import 'reflect-metadata';
import { Container, inject, injectable } from 'inversify';

const container = new Container();

// Register services
container.bind<StorageService>('StorageService').to(ChromeStorageService);
container.bind<NotificationService>('NotificationService').to(NotificationServiceImpl);
container.bind<TabManager>('TabManager').to(TabManager);

export { container };

Defining Services with Decorators

Inversify uses decorators to mark classes as injectable:

import { injectable } from 'inversify';

@injectable()
class ChromeStorageService implements StorageService {
  async get<T>(key: string): Promise<T | null> {
    return new Promise((resolve) => {
      chrome.storage.local.get(key, (result) => {
        resolve(result[key] ?? null);
      });
    });
  }

  async set<T>(key: string, value: T): Promise<void> {
    return new Promise((resolve) => {
      chrome.storage.local.set({ [key]: value }, () => {
        resolve();
      });
    });
  }
}

@injectable()
class NotificationServiceImpl implements NotificationService {
  show(message: string): void {
    chrome.notifications.create({
      type: 'basic',
      iconUrl: 'icons/icon.png',
      message: message,
      title: 'Extension'
    });
  }
}

Implementing DI Patterns in Chrome Extension Components

Now let’s explore how to apply dependency injection across the different components of a Chrome extension.

Service Worker Implementation

The service worker is the background brain of your extension. Here’s how to use DI there:

// service-worker.ts
import 'reflect-metadata';
import { Container } from 'inversify';
import { TYPES } from './types';
import { StorageService, NotificationService, TabManager } from './services';
import { ChromeStorageService } from './services/ChromeStorageService';
import { NotificationServiceImpl } from './services/NotificationServiceImpl';
import { TabManagerImpl } from './services/TabManagerImpl';

// Create and configure container
const container = new Container();

container.bind<StorageService>(TYPES.StorageService).to(ChromeStorageService);
container.bind<NotificationService>(TYPES.NotificationService).to(NotificationServiceImpl);
container.bind<TabManager>(TYPES.TabManager).to(TabManagerImpl);

// Use the container
const tabManager = container.get<TabManager>(TYPES.TabManager);

// Handle messages from content scripts
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'SAVE_TABS') {
    tabManager.saveTabs(message.tabs).then(() => {
      sendResponse({ success: true });
    });
    return true;
  }
});

Content Script Integration

Content scripts run in the context of web pages. While they cannot directly use the Inversify container from your service worker, you can share code by organizing your services properly:

// services/TabManager.ts
export interface TabManager {
  saveTabs(tabs: chrome.tabs.Tab[]): Promise<void>;
  getSavedTabs(): Promise<chrome.tabs.Tab[]>;
}

@injectable()
export class TabManagerImpl implements TabManager {
  constructor(
    @inject(TYPES.StorageService) private storage: StorageService,
    @inject(TYPES.NotificationService) private notifier: NotificationService
  ) {}

  async saveTabs(tabs: chrome.tabs.Tab[]): Promise<void> {
    const tabData = tabs.map(tab => ({
      url: tab.url,
      title: tab.title,
      favIconUrl: tab.favIconUrl
    }));
    
    await this.storage.set('savedTabs', tabData);
    this.notifier.show(`Saved ${tabs.length} tabs`);
  }

  async getSavedTabs(): Promise<chrome.tabs.Tab[]> {
    const saved = await this.storage.get<any[]>('savedTabs');
    return saved || [];
  }
}

For popup and options pages, create separate containers or use a singleton pattern:

// popup.ts
import 'reflect-metadata';
import { PopupController } from './controllers/PopupController';
import { container } from './service-container';

const controller = container.get(PopupController);
controller.initialize();

Advanced DI Patterns for Extensions

Using Symbols for Type Safety

Instead of string-based identifiers, use TypeScript symbols for type-safe dependency keys:

// types.ts
const TYPES = {
  StorageService: Symbol.for('StorageService'),
  NotificationService: Symbol.for('NotificationService'),
  TabManager: Symbol.for('TabManager'),
  Logger: Symbol.for('Logger')
};

export { TYPES };

Lazy Injection

For services that are expensive to initialize or may not be needed, use lazy injection:

import { lazyInject } from 'inversify';

class ContentScriptController {
  @lazyInject(TYPES.Logger)
  private logger: Logger;
  
  initialize() {
    // Logger is only instantiated when first accessed
    this.logger.info('Content script initialized');
  }
}

Scoped Bindings

Inversify supports different scoping strategies:

// Singleton (default) - one instance per container
container.bind<AnalyticsService>('AnalyticsService').to(AnalyticsService);

// Transient - new instance each time
container.bind<Logger>('Logger').to(ConsoleLogger).inTransientScope();

// Request scope - useful for web requests
container.bind<RequestContext>('RequestContext').to(RequestContext).inRequestScope();

Testing with Dependency Injection

One of the greatest benefits of dependency injection is improved testability. Here’s how to leverage DI for testing your Chrome extension.

Creating Mock Services

// tests/mocks/MockStorageService.ts
@injectable()
class MockStorageService implements StorageService {
  private storage: Map<string, any> = new Map();

  async get<T>(key: string): Promise<T | null> {
    return this.storage.get(key) ?? null;
  }

  async set<T>(key: string, value: T): Promise<void> {
    this.storage.set(key, value);
  }

  async remove(key: string): Promise<void> {
    this.storage.delete(key);
  }
}

Writing Unit Tests

import { Container } from 'inversify';
import { TabManagerImpl } from '../../src/services/TabManager';
import { MockStorageService } from '../mocks/MockStorageService';
import { MockNotificationService } from '../mocks/MockNotificationService';
import { TYPES } from '../../src/types';

describe('TabManager', () => {
  let container: Container;
  let tabManager: TabManagerImpl;
  let mockStorage: MockStorageService;
  let mockNotifier: MockNotificationService;

  beforeEach(() => {
    container = new Container();
    mockStorage = new MockStorageService();
    mockNotifier = new MockNotificationService();

    container.bind<StorageService>(TYPES.StorageService).toConstantValue(mockStorage);
    container.bind<NotificationService>(TYPES.NotificationService).toConstantValue(mockNotifier);
    container.bind<TabManager>(TYPES.TabManager).to(TabManagerImpl);

    tabManager = container.get<TabManager>(TYPES.TabManager);
  });

  it('should save tabs to storage', async () => {
    const tabs = [
      { url: 'https://example.com', title: 'Example' }
    ] as chrome.tabs.Tab[];

    await tabManager.saveTabs(tabs);

    const saved = await mockStorage.get('savedTabs');
    expect(saved).toHaveLength(1);
    expect(saved[0].url).toBe('https://example.com');
  });
});

Best Practices for DI in Chrome Extensions

1. Keep Containers Localized

Create separate containers for different extension contexts:

// service-container.sw.ts - for service worker
// service-container.popup.ts - for popup
// service-container.content.ts - for content scripts

This prevents unintended sharing of state between contexts.

2. Use Interface Segregation

Define clear interfaces for your services:

interface StorageService {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
  remove(key: string): Promise<void>;
}

This allows you to create different implementations for testing and production.

3. Avoid Service Worker Memory Leaks

Be careful with container scope in service workers, which can be recreated by Chrome:

// Always recreate container on service worker startup
// Do not store container in a module-level variable that persists
const container = new Container();
// ... configure container

4. Document Your Bindings

Create a clear binding documentation:

/**
 * Service Container Bindings
 * 
 * Services:
 * - StorageService: Handles Chrome storage operations
 * - NotificationService: Manages extension notifications
 * - TabManager: Provides tab management functionality
 * 
 * Scopes:
 * - All services are singletons within their container
 */

Common Pitfalls and How to Avoid Them

Circular Dependencies

Avoid circular dependencies between services. If Service A needs Service B and vice versa, refactor using an intermediary:

// Instead of circular dependency
class A { constructor(b: B) {} }
class B { constructor(a: A) {} }

// Use a third service
class C { constructor(a: A, b: B) {} }

Over-Injection

Don’t inject every single utility function. Simple utilities don’t need DI:

// Don't inject this
@injectable()
class StringUtils {
  uppercase(str: string): string {
    return str.toUpperCase();
  }
}

// Just use a regular function
function uppercase(str: string): string {
  return str.toUpperCase();
}

Forgetting reflect-metadata

Always import reflect-metadata before using Inversify:

import 'reflect-metadata';
import { Container } from 'inversify';
// ... rest of your code

Conclusion

Dependency injection transforms Chrome extension development by enabling clean separation of concerns, improved testability, and maintainable codebases. Using Inversify, you can implement professional-grade architecture that scales with your extension’s complexity.

The pattern proves especially valuable in Chrome extensions due to their unique multi-context nature and the complexity of Chrome’s messaging system. By properly implementing dependency injection, you create an extension that is easier to test, maintain, and extend with new features.

Start implementing DI in your extensions today, and you’ll immediately see improvements in code quality and developer experience. The initial setup overhead pays dividends throughout the extension’s lifecycle.

Additional Resources

Real-World Example: Refactoring an Extension with DI

Let’s walk through a practical example of how to refactor an existing Chrome extension to use dependency injection. This will demonstrate the transformation process and highlight the benefits at each step.

Before: Monolithic Extension Architecture

Consider a typical Chrome extension with tightly coupled code:

// Without DI - everything is coupled
class TabSuspenderExtension {
  private storage: ChromeStorage;
  private tabs: TabTracker;
  private scheduler: SuspensionScheduler;
  private notifier: NotificationManager;
  private logger: ConsoleLogger;
  
  constructor() {
    this.storage = new ChromeStorage();
    this.tabs = new TabTracker(this.storage);
    this.scheduler = new SuspensionScheduler(this.tabs);
    this.notifier = new NotificationManager();
    this.logger = new ConsoleLogger();
  }
  
  initialize() {
    chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
      if (changeInfo.status === 'complete') {
        this.tabs.trackTab(tab);
        this.logger.log(`Tab tracked: ${tabId}`);
      }
    });
    
    chrome.tabs.onRemoved.addListener((tabId) => {
      this.tabs.untrackTab(tabId);
    });
    
    this.scheduler.start();
  }
}

const app = new TabSuspenderExtension();
app.initialize();

This code has several problems. The TabSuspenderExtension class knows too much about its dependencies. Testing requires mocking Chrome APIs or using the actual extension context. Adding new features means modifying the existing class. Different environments (testing, production) require different implementations of the same services.

After: Refactored with Dependency Injection

Here’s the same extension refactored to use dependency injection:

// Service interfaces define contracts
interface StorageService {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
}

interface TabTrackerService {
  trackTab(tab: chrome.tabs.Tab): Promise<void>;
  untrackTab(tabId: number): Promise<void>;
  getTrackedTabs(): Promise<chrome.tabs.Tab[]>;
}

interface SchedulerService {
  start(): void;
  stop(): void;
}

interface NotificationService {
  show(title: string, message: string): void;
}

interface LoggerService {
  log(message: string): void;
  error(error: Error): void;
}

// Service implementations with Inversify decorators
@injectable()
class ChromeStorageService implements StorageService {
  async get<T>(key: string): Promise<T | null> {
    return new Promise((resolve) => {
      chrome.storage.local.get(key, (result) => resolve(result[key] ?? null));
    });
  }

  async set<T>(key: string, value: T): Promise<void> {
    return new Promise((resolve) => {
      chrome.storage.local.set({ [key]: value }, () => resolve());
    });
  }
}

@injectable()
class TabTrackerImpl implements TabTrackerService {
  constructor(
    @inject(TYPES.StorageService) private storage: StorageService,
    @inject(TYPES.LoggerService) private logger: LoggerService
  ) {}

  async trackTab(tab: chrome.tabs.Tab): Promise<void> {
    const tabs = await this.getTrackedTabs();
    tabs.push({ id: tab.id, url: tab.url, title: tab.title });
    await this.storage.set('trackedTabs', tabs);
    this.logger.log(`Tab tracked: ${tab.id}`);
  }

  async untrackTab(tabId: number): Promise<void> {
    const tabs = await this.getTrackedTabs();
    const filtered = tabs.filter(t => t.id !== tabId);
    await this.storage.set('trackedTabs', filtered);
  }

  async getTrackedTabs(): Promise<chrome.tabs.Tab[]> {
    return await this.storage.get<chrome.tabs.Tab[]>('trackedTabs') ?? [];
  }
}

@injectable()
class SchedulerImpl implements SchedulerService {
  private intervalId: number | null = null;
  
  constructor(
    @inject(TYPES.TabTrackerService) private tabs: TabTrackerService
  ) {}

  start(): void {
    this.intervalId = window.setInterval(() => {
      this.checkAndSuspend();
    }, 60000); // Check every minute
  }

  stop(): void {
    if (this.intervalId) {
      clearInterval(this.intervalId);
      this.intervalId = null;
    }
  }

  private async checkAndSuspend(): void {
    const tabs = await this.tabs.getTrackedTabs();
    // Suspension logic here
  }
}

// Application entry point uses injected services
@injectable()
class ExtensionBootstrap {
  constructor(
    @inject(TYPES.TabTrackerService) private tabs: TabTrackerService,
    @inject(TYPES.SchedulerService) private scheduler: SchedulerService,
    @inject(TYPES.LoggerService) private logger: LoggerService
  ) {}

  initialize(): void {
    chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
      if (changeInfo.status === 'complete' && tab.id) {
        this.tabs.trackTab(tab);
      }
    });

    chrome.tabs.onRemoved.addListener((tabId) => {
      this.tabs.untrackTab(tabId);
    });

    this.scheduler.start();
    this.logger.log('Extension initialized');
  }
}

// Container configuration
const container = new Container();
container.bind<StorageService>(TYPES.StorageService).to(ChromeStorageService);
container.bind<TabTrackerService>(TYPES.TabTrackerService).to(TabTrackerImpl);
container.bind<SchedulerService>(TYPES.SchedulerService).to(SchedulerImpl);
container.bind<LoggerService>(TYPES.LoggerService).to(ConsoleLogger);
container.bind<ExtensionBootstrap>(TYPES.ExtensionBootstrap).to(ExtensionBootstrap);

// Bootstrap
const bootstrap = container.get<ExtensionBootstrap>(TYPES.ExtensionBootstrap);
bootstrap.initialize();

Benefits of the Refactored Architecture

The refactored version offers substantial improvements. Each service has a single responsibility, making the code easier to understand and maintain. Testing becomes straightforward because you can inject mock implementations. The code is more flexible since swapping implementations doesn’t require changes to consuming classes. Adding new features means creating new services rather than modifying existing ones. The architecture also scales better as the extension grows.

Container Management Strategies

Context-Aware Containers

Chrome extensions run in multiple contexts, each with its own JavaScript scope. Here’s how to manage containers appropriately:

// container-factory.ts
import { Container } from 'inversify';
import { TYPES } from './types';
import { StorageService, TabService, NotificationService } from './interfaces';
import { ChromeStorageService } from './services/ChromeStorageService';
import { NotificationServiceImpl } from './services/NotificationServiceImpl';

export function createServiceWorkerContainer(): Container {
  const container = new Container();
  
  container.bind<StorageService>(TYPES.StorageService).to(ChromeStorageService);
  container.bind<NotificationService>(TYPES.NotificationService).to(NotificationServiceImpl);
  
  return container;
}

export function createPopupContainer(): Container {
  const container = new Container();
  
  // Popup might need different bindings
  container.bind<StorageService>(TYPES.StorageService).to(ChromeStorageService);
  
  return container;
}

Sharing State Between Contexts

When you need to share state between extension contexts, use chrome.storage or message passing:

// Shared state manager
@injectable()
class SharedStateManager {
  constructor(
    @inject(TYPES.StorageService) private storage: StorageService
  ) {}

  async setSharedValue(key: string, value: any): Promise<void> {
    await this.storage.set(`shared.${key}`, value);
  }

  async getSharedValue<T>(key: string): Promise<T | null> {
    return await this.storage.get<T>(`shared.${key}`);
  }
}

Performance Considerations

While dependency injection adds a layer of abstraction, proper implementation ensures minimal performance impact.

Container Resolution Caching

Inversify caches resolved services by default, eliminating repeated instantiation costs:

// First resolution - creates instance
const service = container.get<MyService>(TYPES.MyService);

// Subsequent resolutions - returns cached instance
const service2 = container.get<MyService>(TYPES.MyService);
console.log(service === service2); // true

Lazy Loading for Heavy Services

For services that are resource-intensive, consider lazy loading:

import { lazyInject } from 'inversify';

class FeatureManager {
  @lazyInject(TYPES.HeavyAnalyticsService)
  private analytics: AnalyticsService;
  
  enableFeature(feature: string) {
    // Analytics only initialized when first used
    this.analytics.trackFeatureEnable(feature);
  }
}

Migrating from Other DI Solutions

If you’re currently using another dependency injection approach, here’s how to migrate to Inversify.

From Manual DI

If you’re manually passing dependencies, transition gradually:

// Manual DI - before
class ServiceA {
  constructor() {
    this.b = new ServiceB(new ServiceC());
  }
}

// Step 1: Accept dependencies in constructor
class ServiceA {
  constructor(b: ServiceB) {
    this.b = b;
  }
}

// Step 2: Add Inversify decorators
@injectable()
class ServiceA {
  constructor(@inject(TYPES.ServiceB) private b: ServiceB) {}
}

From Angular DI

If you’re coming from Angular, Inversify provides a similar experience:

// Angular style
// @Injectable()
// constructor(private service: MyService) {}

// Inversify style
@injectable()
class MyClass {
  constructor(@inject(TYPES.MyService) private service: MyService) {}
}

The main difference is that Inversify doesn’t have Angular’s hierarchical injectors, so you’ll need to manage container scopes manually.

Summary and Key Takeaways

Dependency injection represents a fundamental shift in how you structure Chrome extension code. By externalizing dependencies and using inversion of control, you create extensions that are cleaner, more testable, and easier to maintain.

Key takeaways from this guide include understanding the core principles of dependency injection and how they apply to Chrome extensions. Implement Inversify as your DI container for TypeScript-based extensions. Structure your extension with clear service interfaces and implementations. Leverage DI for testing by creating mock implementations of Chrome API services. Avoid common pitfalls like circular dependencies and over-injection.

As your extension grows, the investment in proper DI architecture pays dividends in code quality and maintainability. Start small, refactor incrementally, and enjoy the benefits of a well-architected Chrome extension.

No previous article
No next article