< _

Building a Browser Extension With TypeScript

Abstract generated cover for Building a Browser Extension With TypeScript.

A browser extension is a small app that runs inside or alongside the browser. It can add buttons, modify pages, listen for browser events, store local settings, talk to APIs, and automate parts of a browsing workflow. Extensions are a good project type for frontend developers because they sit between normal web development and local tooling. You still use HTML, CSS, JavaScript, and TypeScript. But you also need to understand browser extension concepts like manifests, permissions, content scripts, background scripts, and extension storage.

The Mental Model

Think of a browser extension as several small pieces that work together. Common pieces include:

  • manifest
  • popup UI
  • background script
  • content script
  • options page
  • extension storage The manifest describes the extension. The popup is the little UI that opens from the browser toolbar. The background script handles long-running extension behavior. The content script runs inside web pages. The options page stores settings. You do not need every piece for every extension. Start with the smallest set that solves the problem.

The Manifest

The manifest is the configuration file for the extension. It tells the browser:

  • extension name
  • version
  • permissions
  • scripts
  • icons
  • popup page
  • allowed sites Conceptually:
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "0.1.0",
  "action": {
    "default_popup": "popup.html"
  },
  "permissions": ["storage"]
}

This file matters because extensions are permissioned. The browser needs to know what your extension wants to do.

Popup UI

The popup is often the first piece people build. It is just a small web page shown when the user clicks the extension icon. It can have:

  • buttons
  • forms
  • status text
  • settings
  • quick actions For example, a popup might let you save the current page, toggle a feature, or open a dashboard. Because it is a web page, TypeScript and normal frontend tooling can be useful. The popup should stay focused. If the UI becomes complicated, consider opening a full options page or app page instead.

Content Scripts

A content script runs in the context of a web page. This is how an extension can inspect or modify page content. Examples:

  • highlight matching text
  • add a button to a page
  • collect selected text
  • read page metadata
  • improve a specific internal tool Content scripts are powerful, but they should be used carefully. Web pages are messy. DOM structures change. Sites ship updates. A content script that depends on fragile selectors may break. Keep content scripts small and defensive.

Background Scripts

A background script handles extension-level behavior. In modern extensions, this is often a service worker. It may handle:

  • browser events
  • messages from content scripts
  • API calls
  • alarms or scheduled work
  • extension lifecycle behavior For example, a content script might find information on a page, then send a message to the background script to save it. This separation is useful because not every part of the extension has access to the same APIs.

Permissions

Permissions are one of the most important parts of extension development. Ask for the smallest permission set that works. If your extension only needs local storage, do not request access to every website. If it only runs on one internal domain, limit it to that domain. Permissions affect user trust and security review. They also affect your own debugging. Broad permissions can hide unclear architecture.

Where TypeScript Fits

TypeScript helps because extensions often have message passing and shared data shapes. For example:

type SavePageMessage = {
  type: "save-page";
  title: string;
  url: string;
};

That type can be shared between popup, content script, and background code. It makes refactoring safer. If a message field changes, TypeScript can help find the places that need updating.

Common Mistakes

Mistake 1: Requesting too many permissions

Broad permissions may be convenient during development, but they are not a good default. Start narrow.

Mistake 2: Putting too much logic in the popup

The popup opens and closes quickly. Do not treat it like a long-running app process.

Mistake 3: Depending on fragile page selectors

Content scripts break when page structure changes. Make selectors specific, defensive, and easy to update.

Where This Shows Up in Real Projects

Browser extensions are useful for personal workflow tools and business software. Examples:

  • save selected text to a notes system
  • improve an internal admin page
  • add shortcuts to a CRM
  • collect metadata from product pages
  • inspect API data while browsing
  • connect a browser workflow to a local app They are a good bridge between frontend development and automation.

Key Takeaways

  • Browser extensions are made of several small pieces.
  • The manifest defines configuration and permissions.
  • Content scripts run inside pages.
  • Background scripts handle extension-level behavior.
  • TypeScript is useful for message shapes and shared data.

  • Request the smallest permission set that solves the problem.

    Related Articles

  • TypeScript for Python Developers

  • Local Storage vs IndexedDB vs Cookies
  • Fetch API Error Handling in Frontend Apps

← Back to Blog Index