2026 Showdown: Browser Extension Frameworks – Plasmo 4.0 vs. WXT 2.0 vs. Raw TypeScript 5.8

// Plasmo 4.0 Background Service Worker Example
// @ts-ignore: Plasmo-specific module resolution
import { Storage } from "@plasmohq/storage"
import type { PlasmoCSConfig } from "plasmo"

// Configure content script matching for all domains
export const config: PlasmoCSConfig = {
  matches: [""],
  all_frames: true
}

const storage = new Storage({
  area: "local"
})

// Track extension install/update events
chrome.runtime.onInstalled.addListener(async (details) => {
  try {
    if (details.reason === "install") {
      await storage.set("installDate", new Date().toISOString())
      await storage.set("version", chrome.runtime.getManifest().version)
      console.log(`Plasmo Ext installed: v${chrome.runtime.getManifest().version}`)

      // Open onboarding page on first install
      await chrome.tabs.create({
        url: chrome.runtime.getURL("onboarding.html")
      })
    } else if (details.reason === "update") {
      const oldVersion = details.previousVersion
      const newVersion = chrome.runtime.getManifest().version
      await storage.set("lastUpdate", new Date().toISOString())
      console.log(`Plasmo Ext updated: ${oldVersion} -> ${newVersion}`)
    }
  } catch (error) {
    console.error("Install handler failed:", error)
    // Report to error tracking (Sentry mock)
    await fetch("https://errors.example.com/report", {
      method: "POST",
      body: JSON.stringify({
        error: error.message,
        stack: error.stack,
        context: "onInstalled"
      })
    }).catch(e => console.error("Error reporting failed:", e))
  }
})

// Handle messages from content scripts
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  ;(async () => {
    try {
      if (request.type === "GET_STORAGE") {
        const value = await storage.get(request.key)
        sendResponse({ success: true, value })
      } else if (request.type === "SET_STORAGE") {
        await storage.set(request.key, request.value)
        sendResponse({ success: true })
      } else if (request.type === "OPEN_OPTIONS") {
        await chrome.runtime.openOptionsPage()
        sendResponse({ success: true })
      } else {
        sendResponse({ success: false, error: "Unknown request type" })
      }
    } catch (error) {
      console.error("Message handler failed:", error)
      sendResponse({ success: false, error: error.message })
    }
  })()
  return true // Keep message channel open for async response
})

// Periodic cleanup of old storage keys (runs every 24h)
chrome.alarms.create("storageCleanup", {
  delayInMinutes: 1,
  periodInMinutes: 1440
})

chrome.alarms.onAlarm.addListener(async (alarm) => {
  if (alarm.name === "storageCleanup") {
    try {
      const allKeys = await storage.getAll()
      const now = Date.now()
      const expiryMs = 30 * 24 * 60 * 60 * 1000 // 30 days
      for (const [key, value] of Object.entries(allKeys)) {
        if (value?.timestamp && now - new Date(value.timestamp).getTime() > expiryMs) {
          await storage.remove(key)
          console.log(`Cleaned up expired key: ${key}`)
        }
      }
    } catch (error) {
      console.error("Storage cleanup failed:", error)
    }
  }
})

// WXT 2.0 Content Script Example: DOM Mutation Tracker
// Requires WXT 2.0.3+, TypeScript 5.8+
import { defineContentScript } from "wxt/sandbox"
import type { Browser } from "wxt/browser"

// Define content script metadata for WXT build
export default defineContentScript({
  matches: ["*://*.github.com/*"],
  css: ["github-overlay.css"],
  runAt: "document_idle",
  world: "MAIN", // Run in main world to access GitHub's internal APIs
  async main(ctx) {
    const { browser } = ctx
    let observer: MutationObserver | null = null
    const trackedMutations: Array<{
      type: string
      target: string
      timestamp: number
    }> = []

    // Initialize storage for mutation logs
    const getStorage = () => browser.storage.local

    // Error boundary for content script execution
    const safeExecute = async (fn: () => Promise, context: string): Promise => {
      try {
        return await fn()
      } catch (error) {
        console.error(`WXT Content Script error in ${context}:`, error)
        // Send error to background script
        await browser.runtime.sendMessage({
          type: "CONTENT_SCRIPT_ERROR",
          error: error instanceof Error ? error.message : String(error),
          stack: error instanceof Error ? error.stack : undefined,
          context,
          url: window.location.href
        }).catch(e => console.error("Failed to send error report:", e))
        return null
      }
    }

    // Setup DOM mutation observer
    const setupObserver = async () => {
      return safeExecute(async () => {
        observer = new MutationObserver((mutations) => {
          mutations.forEach((mutation) => {
            trackedMutations.push({
              type: mutation.type,
              target: mutation.target.nodeName,
              timestamp: Date.now()
            })
          })

          // Throttle storage writes to every 5s
          if (trackedMutations.length > 0 && Date.now() % 5000 < 100) {
            getStorage().set({
              [`mutations_${Date.now()}`]: {
                url: window.location.href,
                mutations: trackedMutations.slice(-50), // Keep last 50
                timestamp: new Date().toISOString()
              }
            }).catch(e => console.error("Storage write failed:", e))
            trackedMutations.length = 0 // Clear buffer
          }
        })

        observer.observe(document.body, {
          childList: true,
          subtree: true,
          attributes: true,
          characterData: true
        })

        console.log("WXT Mutation Observer started on GitHub")
        return true
      }, "setupObserver")
    }

    // Handle messages from popup/background
    browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
      safeExecute(async () => {
        if (message.type === "GET_MUTATIONS") {
          const storage = getStorage()
          const allItems = await storage.get(null)
          const mutationLogs = Object.entries(allItems)
            .filter(([key]) => key.startsWith("mutations_"))
            .map(([_, value]) => value)
          sendResponse({ success: true, logs: mutationLogs })
        } else if (message.type === "CLEAR_MUTATIONS") {
          const storage = getStorage()
          const allItems = await storage.get(null)
          const mutationKeys = Object.keys(allItems).filter(key => key.startsWith("mutations_"))
          await storage.remove(mutationKeys)
          sendResponse({ success: true })
        }
        return true
      }, "messageHandler")
      return true
    })

    // Cleanup on script unload
    ctx.addEventListener("wxt:unload", () => {
      if (observer) {
        observer.disconnect()
        observer = null
        console.log("WXT Mutation Observer disconnected")
      }
    })

    // Start observer
    await setupObserver()
  }
})

// Raw TypeScript 5.8 Background Service Worker (No Framework)
// Requires tsconfig.json with target ES2022, module ESNext, lib ["chrome", "dom", "es2022"]
// Manifest V3 manifest.json must be manually configured
import type { Chrome } from "chrome-types"

// Augment Chrome type for storage
declare global {
  interface Chrome {
    storage: {
      local: {
        get: (keys: string | string[] | null) => Promise
        set: (items: Record) => Promise
        remove: (keys: string | string[]) => Promise
      }
    }
  }
}

const chrome = globalThis.chrome as unknown as Chrome

// Storage wrapper with error handling
class ExtensionStorage {
  private area = chrome.storage.local

  async get(key: string): Promise {
    try {
      const result = await this.area.get(key)
      return result[key as keyof T]
    } catch (error) {
      console.error(`Storage get failed for key ${key}:`, error)
      return undefined
    }
  }

  async set(key: string, value: unknown): Promise {
    try {
      await this.area.set({ [key]: value })
      return true
    } catch (error) {
      console.error(`Storage set failed for key ${key}:`, error)
      return false
    }
  }

  async remove(key: string | string[]): Promise {
    try {
      await this.area.remove(key)
      return true
    } catch (error) {
      console.error(`Storage remove failed for key ${key}:`, error)
      return false
    }
  }
}

const storage = new ExtensionStorage()

// Message handler type guard
type MessageRequest = 
  | { type: "GET_STORAGE"; key: string }
  | { type: "SET_STORAGE"; key: string; value: unknown }
  | { type: "CLEAR_ALL_STORAGE" }

const isMessageRequest = (msg: unknown): msg is MessageRequest => {
  return typeof msg === "object" && msg !== null && "type" in msg && typeof (msg as { type: unknown }).type === "string"
}

// Background service worker entrypoint
const initBackground = async () => {
  try {
    // Handle install/update events
    chrome.runtime.onInstalled.addListener(async (details) => {
      try {
        if (details.reason === "install") {
          await storage.set("installDate", new Date().toISOString())
          await storage.set("version", chrome.runtime.getManifest().version)
          console.log(`Raw TS Ext installed: v${chrome.runtime.getManifest().version}`)

          // Open onboarding (must manually create onboarding.html)
          await chrome.tabs.create({
            url: chrome.runtime.getURL("onboarding.html")
          }).catch(e => console.error("Failed to open onboarding:", e))
        } else if (details.reason === "update") {
          await storage.set("lastUpdate", new Date().toISOString())
          console.log(`Raw TS Ext updated: ${details.previousVersion} -> ${chrome.runtime.getManifest().version}`)
        }
      } catch (error) {
        console.error("Install handler failed:", error)
      }
    })

    // Handle messages from content scripts/popup
    chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
      ;(async () => {
        try {
          if (!isMessageRequest(request)) {
            sendResponse({ success: false, error: "Invalid message format" })
            return
          }

          switch (request.type) {
            case "GET_STORAGE":
              const value = await storage.get(request.key)
              sendResponse({ success: true, value })
              break
            case "SET_STORAGE":
              const success = await storage.set(request.key, request.value)
              sendResponse({ success })
              break
            case "CLEAR_ALL_STORAGE":
              const allKeys = await chrome.storage.local.get(null)
              await storage.remove(Object.keys(allKeys))
              sendResponse({ success: true })
              break
            default:
              sendResponse({ success: false, error: "Unknown message type" })
          }
        } catch (error) {
          console.error("Message handler failed:", error)
          sendResponse({ success: false, error: error instanceof Error ? error.message : String(error) })
        }
      })()
      return true
    })

    // Periodic cleanup (requires chrome.alarms, must be declared in manifest)
    if (chrome.alarms) {
      chrome.alarms.create("rawTsCleanup", {
        delayInMinutes: 1,
        periodInMinutes: 1440
      })

      chrome.alarms.onAlarm.addListener(async (alarm) => {
        if (alarm.name === "rawTsCleanup") {
          try {
            const allItems = await chrome.storage.local.get(null)
            const now = Date.now()
            const expiryMs = 30 * 24 * 60 * 60 * 1000
            for (const [key, value] of Object.entries(allItems)) {
              if (typeof value === "object" && value !== null && "timestamp" in value) {
                const itemTimestamp = new Date((value as { timestamp: string }).timestamp).getTime()
                if (now - itemTimestamp > expiryMs) {
                  await storage.remove(key)
                  console.log(`Cleaned up expired key: ${key}`)
                }
              }
            }
          } catch (error) {
            console.error("Cleanup failed:", error)
          }
        }
      })
    }

    console.log("Raw TypeScript 5.8 background service worker initialized")
  } catch (error) {
    console.error("Background init failed:", error)
  }
}

// Start the background worker
initBackground()

// WXT 2.0 Deno Test Example: Message Handler
import { describe, it } from "wxt/testing"
import { createMockMessage } from "wxt/testing/chrome"

describe("Background Message Handler", () => {
  it("responds to GET_STORAGE requests", async () => {
    const mockMessage = createMockMessage({
      type: "GET_STORAGE",
      key: "test-key"
    })
    const response = await backgroundMessageHandler(mockMessage)
    expect(response.success).toBe(true)
    expect(response.value).toBe("test-value")
  })
})

// Replace Plasmo Storage with WXT Built-in Storage
// Before (Plasmo)
import { Storage } from "@plasmohq/storage"
const storage = new Storage()
await storage.set("key", "value")

// After (WXT)
import { useStorage } from "wxt/storage"
const storage = useStorage()
await storage.setItem("key", "value")

// unplugin-auto-expose Message Definition
// messages.ts
export interface GetStorageMessage {
  type: "GET_STORAGE"
  key: string
}

export interface SetStorageMessage {
  type: "SET_STORAGE"
  key: string
  value: unknown
}

// The plugin auto-generates handlers for these interfaces