Entrypoints

WebExtend uses the file system to parse entry files and generates the corresponding fields for manifest.json.

INFO

All entry files are located in the src directory, which can be a folder or a file except the icons entry.

• When the entry is a file, only the file ends with .js|.jsx|.ts|.tsx will be discovered. The build tool will inject an HTML template for every entry if necessary and generate the corresponding .html file.
• When the entry is a folder,
  • if it has a single-entry, the index.js file in the folder will be discovered as an entry.
  • if it has multi-entries, all the direct *.js or */index.js files in the folder will be discovered as entries. Currently, only files in contents、sandboxes and panels will be discovered as multiple entries.

Icons

Chrome Docs | Firefox Docs

Create the assets/icon-{size}.png files under the src directory as follows, which will be reflected to the icons and action.default_icons fields in manifest.json.

src/assets/
├─ icon-16.png
├─ icon-32.png
├─ icon-48.png
└─ icon-128.png

Alternatively, you can use web-extend to generate the corressponding sized icons files, which needs a high quality image assets/icon.png (>= 128 * 128 px) as the template.

npx web-extend g icons

See with-icons.

Background

Chrome Docs | Firefox Docs

The background entry will be reflected to the background.service_worker or background.scripts field in manifest.json.

Generate the entry automatically.

npx web-extend g background

Alternatively, create the src/background.js file manually whose content is as follows:

src/background.js

console.log("This is a background script.");

See with-background.

Popup

Chrome Docs | Firefox Docs

The popup entry will be reflected to the action.default_popup field in manifest.json.

Generate the entry automatically.

npx web-extend g popup

Alternatively, create the src/popup.js or src/popup/index.js file manually whose content is as follows:

src/popup/index.jsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

const rootEl = document.getElementById("root");
if (rootEl) {
  const root = createRoot(rootEl);
  root.render(
    <StrictMode>
      <App />
    </StrictMode>
  );
}

See with-popup.

Options

Chrome Docs | Firefox Docs

The options entry will be reflected to the options_ui.page field in manifest.json.

Generate the entry automatically.

npx web-extend g options

Alternatively, create the src/options.js or src/options/index.js file manually.

See with-options.

Sidepanel

Chrome Docs | Firefox Docs

The sidepanel entry will be reflected to the side_panel.default_path or sidebar_action.default_panel field in manifest.json.

Generate the entry automatically.

npx web-extend g sidepanel

Alternatively, create the src/sidepanel.js or src/sidepanel/index.js file manually.

See with-sidepanel.

Content Scripts

Chrome Docs | Firefox Docs

Adding a single content script

A single content entry will be reflected to the content_scripts[0].js field in manifest.json.

Generate the entry automatically.

npx web-extend g content

Alternatively, create the src/content.js orsrc/content/index.js file manually.

Adding multiple content scripts

Multiple content entries will be reflected to the content_scripts[index].js field in manifest.josn respectively.

Generate the entry automatically.

npx web-extend g contents/site-one,contents/site-two

Alternatively, create the src/contents/*.js or src/contents/*/index.js file manually.

Adding CSS

Import CSS files directly in the content entry file, which will be reflected to the content_scripts[index].css field in manifest.json.

src/content/index.js

import "./index.css";

Alternatively, you can use CSS Modules, Tailwind CSS, UnoCSS or CSS-in-JS for styling.

Adding config

Export an obejct named config in the content entry, which will be reflected to other fields in content_scripts[index], as follows.

src/content/index.js

export const config = {
  matches: ["https://www.google.com/*"],
};

src/content/index.ts

import type { ContentScriptConfig } from "web-extend";

export const config: ContentScriptConfig = {
  matches: ["https://www.google.com/*"],
};

See with-content, with-multi-contents.

Devtools

Chrome Docs | Firefox Docs

The devtools entry will be reflected to the devtools_page field in manifest.json.

Generate the entry automatically.

npx web-extend g devtools

Alternatively, create the src/devtools.js file manually.

Adding panels

The devtools page is composed of a single panel or multiple panels. There are two methods to create panels.

Generate the panel automatically.

# create a single panel
npx web-extend g panel

# create multiple panels
npx web-extend g panels/panel1,panels/panel2

Alternatively, create src/panel/index.js file for a single panel, or create src/panels/panel1/index.js for multiple panels.

Then you can use the panel in the detools entry, as follows.

src/devtools.js

// for a single panel
chrome.devtools.panels.create("My panel", "", "panel.html");

// for multiple panels
chrome.devtools.panels.create("My panel", "", "panels/panel1.html");

See with-devtools.

Bookmarks

Chrome Docs, Firefox doesn't support bookmarks.

The bookmarks entry will be reflected to the chrome_url_overrides.bookmarks field in manifest.json.

Generate the entry automatically.

npx web-extend g bookmarks

Alternatively, create the src/bookmarks.js or src/bookmarks/index.js file manually.

Newtab

Chrome Docs | Firefox Docs

The newtab entry will be reflected to the chrome_url_overrides.newtab field in manifest.json.

Generate the entry automatically.

npx web-extend g newtab

Alternatively, create the src/newtab.js or src/newtab/index.js file manually.

History

Chrome Docs, Firefox doesn't support history.

The history entry will be reflected to the chrome_url_overrides.history field in manifest.json.

Generate the entry automatically.

npx web-extend g history

Alternatively, create the src/history.js or src/history/index.js file manually.

Sandbox

Chrome Docs, Firefox doesn't support sandbox.

The sandbox entry will be reflected to the sandbox.pages field in manifest.json.

Generate the entry automatically.

# create a single entry
npx web-extend g sandbox

# create multiple entries
npx web-extend g sandboxes/sandbox1,sandboxes/sandbox2

Alternatively, create the src/sandbox.js or src/sandboxes/*.js file manually.

To use the sandbox, you can embed it as an iframe inside an extension page or a content script.

src/popup/index.js

document.querySelector("#root").innerHTML = `
  <div class="content">
    <!-- embed a single sandbox -->
    <iframe id="sandboxFrame1" src="sandbox.html"></iframe>
    <!-- embed multiple sandboxes -->
    <iframe id="sandboxFrame1" src="sandboxes/sandbox1.html"></iframe>
  </div>
  `;
}

See with-sandbox, with-multi-sandboxes.