Architecture overview

# Overview

A Chrome extension is composed of different parts. This page describes the structure of an extension, the role each part plays, and how they work together. It does not describe the code-level details of how to write an extension.

If you are not familiar with Chrome extension development, we recommend first reading Extensions 101 and Development Basics.

# The structure of a Chrome extension

The following sections describe the files that compose a Chrome extension. Here's an example of a Chrome Extension file structure:

# The manifest

The manifest (manifest.json) is the configuration file of a Chrome extension. It is a required JSON file that must be located at the root of the project. It provides the browser with a blueprint of the extension, with important information such as:

• The name of the extension, a description of what it does, the current version number, and what icons to use.
• The Chrome API keys and permissions that the extension needs.
• The files assigned as the extension service worker, the popup HTML file, the options page, the content scripts, etc.

The Manifest keys article contains the complete list of default and optional keys. For ready to use code samples, check out the Manifest examples.

# The extension service worker

An extension service worker (service-worker.js) is an event-based script that the browser runs in the background. It is often used to process data, coordinate tasks in different parts of an extension, and as an extension's event manager. For example, the service worker can listen for and react to events when the extension is first installed, a new tab is created, a new bookmark is added, the extension toolbar icon is clicked, etc.

A service worker can access all the Extension APIs, but as a type of Worker it can't use the DOM APIs that a document's global Window object provides. It also runs in its own environment, so it cannot directly modify a web page's content.

See Handling events in the extension service worker for more details.

# Content scripts

Extensions use content scripts (content-script.js) to inject code into host pages. They allow the extension to interact with and modify pages in the browser. For example, they can insert a new element on the page, change the style of a website, modify the DOM elements, etc.

Content Scripts share access to the same DOM tree as the host page but run in a separate JavaScript environment (the extension's isolated world). They also have access to a limited number of Chrome APIs. See Understanding content scripts for more details.

# Extension HTML pages

An extension can have different HTML pages depending on the design. All extension HTML files can use the Chrome APIs, but cannot include inline Javascript; they must point to a JavaScript file. The two most common HTML pages are:

The popup

Many extensions use a popup (popup.html) to provide functionality, such as displaying a list of tabs, or additional information regarding the current tab. Users can easily find it by clicking on the extension toolbar icon. When the user navigates away it will automatically close.

The options page

The options page (options.html) provides a way for users to customize an extension, such as choosing which sites the extension will run on. Users can access the options page in several ways as described in Finding the options page.

Side panels

A side panel (sidepanel.html) can be used to assist users throughout their browsing journey. Users can find extension side panels by navigating to Chrome's side panel UI or by clicking the extension toolbar icon. Side panels can be configured to only be displayed on specific sites.

Other extension HTML pages include Chrome override pages, sandbox pages or any custom page included for a specific purpose like onboarding the user.

# Other assets

An extension can include many types of resources, such as images and fonts, but only the extension icons are required for extensions hosted in the Chrome Web Store. Also, Chrome Web Store policy requires that extensions include all code that the extension executes in the extension's package.

# How they work together

In this section, we will describe how these extension components communicate, store data, and share access to resources.

# Sending messages

Many times content scripts, or other extension pages, need to send or receive information from the extension service worker. In these cases, either side can listen for messages sent from the other end, and respond on the same channel. Extensions can send a one-time request or establish a long-lived connection to support multiple messages.

See Message passing for more details.

# Storing data

Chrome provides extensions with a specialized Storage API, available to all extension components. It includes four separate storage areas for specific use cases and an event listener that tracks whenever data is updated. For example, when you save changes in the popup, the extension service worker can respond with specified logic.

See Storage API for usage and code samples.

# Referencing extension resources

Extension HTML pages can use the same tags as a regular HTML page to add an extension asset. Content scripts can also access extension resources, such as images and fonts, but require extra steps which are described in Accessing extension files in Content Scripts.

# Take the next step

Now that you have completed the Getting Started guides and understand the structure of a Chrome extension, you are ready to dive deeper with the following resources:

• Learn about the UI elements you can use in a Chrome extension.
• Browse a complete list of Chrome extension capabilities.
• Discover best practices for building secure extensions that respect user privacy.