Forem: Ran Tayeb

Structuring Modern Browser Extensions for Maintainability and Scale

Ran Tayeb — Sat, 16 May 2026 21:06:00 +0000

Browser extensions rarely stay simple for long.

What starts as a popup, a content script, and a few background listeners can quickly grow into a system with multiple runtime contexts, cross-context messaging, state management, browser-specific APIs, and UI surfaces like popup or DevTools.

At that point, the biggest challenge is no longer “how do I make this work?”

It becomes: how do I keep this maintainable as it grows?

That is the problem HexaJS is built to solve.

HexaJS is a new framework for modern browser extension development that brings structure to a naturally fragmented environment. It uses Dependency Injection, tokens, controllers, handlers, and a context-aware build pipeline to help teams build extensions that are easier to reason about, easier to test, and easier to scale.

Browser extensions need real architecture

A modern extension is not a single application running in one process.

It is split across isolated runtime environments:

Background
Content
Managed UI such as popup and DevTools

Each context has different rules, different capabilities, and different lifecycle behavior.

If those boundaries are not reflected in the architecture, complexity spreads fast:

background logic becomes a catch-all
message routes turn into scattered string contracts
browser APIs leak into too many layers
content scripts become harder to scope and reason about
testing becomes more difficult as dependencies become implicit

HexaJS treats those contexts as first-class architectural boundaries instead of just folders in a project.

Context-aware Dependency Injection

HexaJS uses a decorator-based DI model that works across browser extension contexts.

A service can be declared with an explicit runtime context:

import { Injectable, HexaContext } from '@hexajs-dev/common';

@Injectable({ context: HexaContext.Background })
export class TabQueryService {
  getActiveIdFromTabs(tabs: Array<{ id?: number }>): number {
    return tabs[0]?.id ?? -1;
  }
}

This makes dependencies explicit, but more importantly, it makes context ownership explicit.

In browser extensions, background, content, and UI do not share the same runtime world. A class that is valid in one context should not automatically be available in another.

HexaJS uses its AOT pipeline to scan decorators, analyze dependency graphs, and validate those boundaries before bootstrap generation. That means dependency injection is not just a runtime convenience — it becomes part of the framework’s architectural enforcement.

Tokens for configuration and platform values

Some dependencies are services. Others are values.

Things like:

active browser platform
build mode
API base URLs
feature flags

HexaJS supports token-based injection so values can be treated as explicit dependencies too.

import { createToken, Inject, Injectable, HexaContext } from '@hexajs-dev/common';

export const API_BASE_URL = createToken(
  'API_BASE_URL',
  'https://api.example.com',
  HexaContext.Background
);

@Injectable({ context: HexaContext.Background })
export class ApiConfigService {
  constructor(@Inject(API_BASE_URL) private apiBaseUrl: string) {}

  getBaseUrl(): string {
    return this.apiBaseUrl;
  }
}

This is especially useful in extension development because environment and platform differences are common. Making those values injectable keeps them visible, testable, and easy to override through build configuration.

HexaJS also provides built-in system tokens such as HEXA_PLATFORM and HEXA_BUILD_MODE.

Controllers for background routing

The background context usually becomes the orchestration layer of the extension. In many projects, that eventually turns into a long chain of listeners and switch statements.

HexaJS introduces Controllers to make background messaging explicit and organized.

import { Controller, Action } from '@hexajs-dev/core';
import { TabsPort } from '@hexajs-dev/ports';

@Controller({ namespace: 'tabs' })
export class TabsController {
  constructor(private tabsPort: TabsPort) {}

  @Action('active')
  async activeTab(): Promise<{ tabId: number }> {
    const tabs = await this.tabsPort.queryTabs({ active: true, currentWindow: true });
    return { tabId: tabs[0]?.id ?? -1 };
  }
}

This creates a clean route structure based on namespace:action, such as:

tabs:active

Instead of treating background communication as a raw transport concern, HexaJS models it as named application behavior.

That leads to code that is easier to navigate, easier to extend, and easier to test.

Handlers for content-side behavior

Content scripts have a very different responsibility from background logic. They run inside the page, interact with the DOM, and often need to be scoped to specific sites or entry points.

HexaJS introduces Handlers for content-side endpoints.

import { Handler, Handle } from '@hexajs-dev/core';
import { LoggerService } from '../services/logger.service';
import { MyContentEntry } from './content';

@Handler({ namespace: 'tabs', Contents: [MyContentEntry] })
export class TabsHandler {
  constructor(private logger: LoggerService) {}

  @Handle('active-id')
  onActiveId(payload: { tabId: number }): { ok: boolean } {
    this.logger.log('Active tab id from background:', payload.tabId);
    return { ok: true };
  }
}

This pattern helps keep content code narrow and intentional.

The Contents binding is particularly useful for modern extensions that target multiple websites or different page families. Instead of letting content behavior spread globally, HexaJS allows handlers to be attached to the content entries where they actually belong.

That keeps large extensions more modular as they evolve.

A better way to handle browser-specific complexity

Cross-browser support is one of the hardest parts of extension development.

Without an architectural boundary, browser API differences start leaking into business logic:

function getActiveTab() {
  if (isChrome) {
    chrome.tabs.query({ active: true }, (tabs) => handle(tabs));
  } else if (isFirefox) {
    browser.tabs.query({ active: true }).then((tabs) => handle(tabs));
  } else if (isSafari) {
    const tab = safari.application.activeBrowserWindow.activeTab;
    handle([tab]);
  }
}

HexaJS addresses this by pushing platform-specific behavior into ports and routing browser-facing orchestration through structured background controllers.

import { Controller, Action } from '@hexajs-dev/core';
import { TabsPort, StoragePort } from '@hexajs-dev/ports';

@Controller({ namespace: 'tabInfo' })
export class TabInfoController {
  constructor(
    private readonly tabsPort: TabsPort,
    private readonly storagePort: StoragePort
  ) {}

  @Action('current')
  async onGetCurrentTabInfo(): Promise<{ tabId: number; url: string; metadata?: unknown }> {
    const [activeTab] = await this.tabsPort.query({ active: true });
    if (!activeTab) throw new Error('No active tab found');

    const cached = await this.storagePort.get('tabMetadata', { [activeTab.id]: {} });

    return {
      tabId: activeTab.id,
      url: activeTab.url,
      metadata: cached[activeTab.id] ?? {},
    };
  }
}

The application layer stays focused on behavior, while browser-specific details are handled below it.

That separation becomes increasingly valuable as an extension grows across browsers and features.

Why this structure scales

The biggest scaling challenge in browser extensions is usually not runtime performance first. It is codebase complexity.

A structured architecture helps with that in very practical ways:

Better onboarding

New contributors can quickly understand where logic belongs:

services for reusable behavior
controllers for background entry points
handlers for content behavior
tokens for configuration and environment values

Easier testing

Constructor injection makes dependencies explicit and easier to mock.

Safer refactoring

When context boundaries and routes are structured, changes become easier to reason about.

Cleaner cross-context communication

Named routes are easier to track than scattered transport calls.

Better long-term maintainability

A project with clear boundaries and generated wiring stays understandable longer than one built from ad hoc listeners and utility modules.

Final thought

Browser extensions have evolved far beyond a few loose scripts.

They now behave more like distributed applications running inside isolated browser-managed environments. That reality needs stronger architecture than raw listeners, global state, and hand-wired messaging.

HexaJS is built around that idea.

By combining:

Dependency Injection
Tokens
Controllers
Handlers
AOT analysis
Context-aware bootstrapping

…it gives browser extension teams a foundation for building codebases that are structured from the start and ready to grow.

If you are exploring a more maintainable way to build modern browser extensions, HexaJS is now in beta and ready to try: hexajs.dev

Quick snippets

Background service

import { Injectable, HexaContext } from '@hexajs-dev/common';

@Injectable({ context: HexaContext.Background })
export class TabQueryService {
  getActiveIdFromTabs(tabs: Array<{ id?: number }>): number {
    return tabs[0]?.id ?? -1;
  }
}

Token injection

import { Inject, Injectable, HEXA_PLATFORM } from '@hexajs-dev/common';

@Injectable()
export class PlatformLabelService {
  constructor(@Inject(HEXA_PLATFORM) private platform: string) {}

  getLabel(): string {
    return `running on ${this.platform}`;
  }
}

Background controller

import { Controller, Action } from '@hexajs-dev/core';
import { TabsPort } from '@hexajs-dev/ports';

@Controller({ namespace: 'tabs' })
export class TabsController {
  constructor(private tabsPort: TabsPort) {}

  @Action('active')
  async activeTab(): Promise<{ tabId: number }> {
    const tabs = await this.tabsPort.queryTabs({ active: true, currentWindow: true });
    return { tabId: tabs[0]?.id ?? -1 };
  }
}

Content handler

import { Handler, Handle } from '@hexajs-dev/core';
import { MyContentEntry } from './content';

@Handler({ namespace: 'tabs', Contents: [MyContentEntry] })
export class TabsHandler {
  @Handle('active-id')
  onActiveId(payload: { tabId: number }): { ok: boolean } {
    return { ok: true };
  }
}

Why AOT Compilation is Crucial for Modern Browser Extension Development

Ran Tayeb — Fri, 15 May 2026 08:29:07 +0000

If you’ve been building browser extensions recently, you already know that Manifest V3 (MV3) changed the game. With the removal of background pages in favor of service workers and stricter Content Security Policies (CSP), extension developers have had to rethink how their code is bundled and executed.

One of the most important architectural shifts in this new era is the move toward Ahead-of-Time (AOT) compilation.

But why is AOT so important for browser extensions today? Let’s break it down.

The Problem with JIT and Dynamic Execution in Extensions

Historically, JavaScript relies heavily on Just-in-Time (JIT) compilation and dynamic execution. However, modern browser extensions run in highly restricted environments.

With Manifest V3:

Strict CSPs: You can no longer use eval() or dynamically construct functions from strings. Many traditional frameworks rely on these features for runtime template compilation or dynamic routing.
Service Worker Lifecycles: Background scripts are now ephemeral Service Workers. They spin up, do their job, and shut down. If your framework takes too long to initialize routing or state at runtime, your extension feels sluggish and might even be terminated by the browser.

Why AOT is the Answer

Ahead-of-Time compilation shifts the heavy lifting from the user's browser at runtime to your machine at build time. Here is why it is essential for modern extension development:

1. Lightning-Fast Initialization ⚡

Because MV3 service workers sleep and wake up constantly, cold start time is critical. AOT compilation resolves routes, dependency injection trees, and state structures during the build process. When the service worker wakes up, it executes pure, pre-optimized JavaScript without having to "figure out" its architecture first.

2. Built-in CSP Compliance 🛡️

AOT eliminates the need for runtime template compilers or dynamic code evaluation. Everything your extension needs to do is compiled down to static, CSP-compliant JavaScript before it ever reaches the browser.

3. Compile-Time Route Validation 🚦

In a typical extension, the UI, content scripts, and background scripts communicate via complex message-passing (e.g., chrome.runtime.sendMessage). With an AOT build pipeline, you can scan and validate these messaging routes at compile time. If a content script tries to call a background action that doesn't exist, the build fails, saving you from painful runtime debugging.

4. Context-Aware Code Splitting 📦

Extensions are essentially distributed systems living in the browser. You have the Popup (UI context), Content Scripts (DOM context), and the Background (Service Worker context). An intelligent AOT compiler knows exactly which code belongs to which context, stripping out dead code and generating context-ready artifacts.

How HexaJS Uses AOT

When I was building HexaJS—a TypeScript-first framework for browser extension backends—I knew an AOT-first approach was the only way to solve the MV3 puzzle effectively.

Instead of relying on fragile runtime reflection, the HexaJS build pipeline features an AOT-first architecture that:

Discovers Routes Early: It scans your @Controller and @Action decorators at build time.
Generates Metadata: It creates compile-time metadata and route validation generation.
Outputs Context-Ready Artifacts: It perfectly splits your logic between background, content, and UI so you never ship background logic to a content script.

The Takeaway

Browser extensions are no longer just simple scripts injected into web pages—they are full-fledged applications running in highly isolated, strict environments. By adopting AOT compilation, we can build extensions that are safer, faster, and much easier to debug.

If you're interested in seeing an AOT-first extension framework in action, check out HexaJS and let me know your thoughts!

Are you building for Manifest V3? How has your build pipeline changed? Let's discuss in the comments!