Docs
Blog
Docs
Blog

HTML

In an extension, HTML files serve as the foundation for user interfaces such as popups, options pages, and new tab pages. Extension.js ensures that HTML files defined in the manifest.json file are correctly processed, with full support for styles, scripts, and static assets.

HTML File Support

Extension.js offers first-class support for HTML files, ensuring hot-module replacement (HMR) where applicable. It handles asset injection (images, CSS, JS), live-reloading, and updates.

The following manifest fields use HTML files as entry points:

Manifest Field File Type Expected HMR Support
action.default_popup .html Yes
background.page .html Yes
chrome_settings_overrides.homepage .html Yes
chrome_url_overrides.newtab .html Yes
chrome_url_overrides.history .html Yes
chrome_url_overrides.bookmarks .html Yes
devtools_page .html Yes
options_ui.page .html Yes
page_action.default_popup .html Yes
sandbox.pages .html Yes
side_panel.default_panel .html Yes
sidebar_action.default_panel .html Yes

Sample HTML File

Here’s a basic example of an HTML file used in an extension:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Extension Page</title>
    <link rel="stylesheet" href="./css/styles.css" />
  </head>
  <body>
    <div id="content">
      <h1>Welcome to My Extension</h1>
      <p>This is a sample extension page.</p>
    </div>
    <script src="./js/main.js"></script>
  </body>
</html>

Handling HTML Files Not Declared in manifest.json

If you need to include additional HTML files that are not declared in the manifest.json, such as sandboxed iframes or extra pages, you can place these files in the /pages folder. Extension.js will process the HTML files in this folder as it would for any HTML entry point defined in the manifest.

Example Usage: Place your HTML file in the /pages folder, and it will be bundled and available for use, with full support for HMR, asset injection, and other processing steps.

pages/
└── extra-page.html

This allows you to add extra pages to your extension without cluttering the manifest or needing to specify them directly there.

For more details, refer to the Special Folders documentation.

Output Path

The output path for HTML files is always structured as [feature]/index[ext]. For example, if you're working on a new tab override, the resulting files would look like this:

chrome_url_overrides/
├── index.html
├── index.css
└── index.js

How Extension.js Handles HTML

The plugin for HTML file support in Extension.js ensures that the following steps occur during compilation:

  1. Emit HTML File: The original HTML file is included in the compilation process.
  2. Inject Assets: Static assets like <img>, <link>, and <script> are added to the compilation.
  3. Inject Styles and Scripts: CSS and JavaScript files referenced in the HTML file are processed and included as part of the output.
  4. Hot Module Replacement (HMR): HMR is enabled for the scripts in HTML files, allowing live-reloading during development.
  5. Error Handling: Common errors related to HTML files are caught, and suggestions are made to resolve them.

Best Practices

  • Always reference assets using relative paths to ensure they are correctly bundled.
  • Use special folders like pages/ for additional HTML pages outside the scope of the manifest.
  • Ensure your manifest fields correctly reference HTML files, especially for features like action.default_popup and chrome_url_overrides.

Next Steps