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.

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.

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.

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.

For example.

src/content/index.css

.web-extend-content-container {
  position: fixed;
  bottom: 20px;
  right: 20px;
  display: flex;
  align-items: end;
  z-index: 1000;
}

.web-extend-content {
  color: #000;
  background-color: #fff;
  margin-right: 8px;
  border: 1px solid #ccc;
  border-radius: 6px;
  text-align: center;
  padding: 12px;
}

src/content/index.ts

import "./index.css";

let root = document.getElementById("myContent");
if (!root) {
  root = document.createElement("div");
  root.id = "myContent";
  root.innerHTML = `<div class="web-extend-content-container">
    <div class="web-extend-content">
      <p>This is a content script.</p>
    </div>
  </div>`;
  document.body.appendChild(root);
}

You can also apply CSS inside Shadow DOM, which is helpful to avoid style conflicts with the styles in the main site.

For example.

src/content/index.ts

import inlineStyles from "./index.css?inline";

let host = document.getElementById("myContentHost");
if (!host) {
  host = document.createElement("div");
  host.id = "myContentHost";

  const shadow = host.attachShadow({ mode: "open" });

  const sheet = new CSSStyleSheet();
  sheet.replaceSync(inlineStyles);
  shadow.adoptedStyleSheets = [sheet];

  const root = document.createElement("div");
  root.innerHTML = `<div class="web-extend-content-container">
    <div class="web-extend-content">
      <p>This is a content script.</p>
    </div>
  </div>`;
  shadow.appendChild(root);

  document.body.appendChild(host);
}

For advanced styling, you can utilize CSS Modules, CSS preprocessors, Tailwind CSS, or UnoCSS. See using CSS libraries.

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.

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.

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.

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.

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.

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.

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.

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.