A high-level explanation of the structure of a Chrome Extension.
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 (
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 copy-paste-ready 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.
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.
Host pages are the websites that a content script interacts with. An extension can choose which websites a content script should run on by specifying match patterns.
Extension HTML pages
- 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.
Other extension HTML pages include Chrome override pages, sandbox pages or any custom page included for a specific purpose like onboarding the user.
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.
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.
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.