Skip to content

Project Structure

Overview

WebExtend provides a standardized project structure that helps you organize your browser extension code efficiently. This guide explains the key directories and files in a WebExtend project.

A typical WebExtend project structure looks like this:

my-web-extension/
├── public/                # Static assets
│   └── _locales/          # Localization files
├── src/                   # Source code
│   ├── assets/            # Processed assets
│   │   ├── icon-16.png
│   │   ├── icon-32.png
│   │   └── icon-128.png
│   ├── background/        # Background script
│   │   └── index.js
│   ├── content/           # Content script
│   │   └── index.js
│   ├── devtools.js        # DevTools page
│   ├── pages/
│   │   ├── welcome/
│   │   │   ├── index.js
│   │   │   └── style.css
│   │   └── panel/         # Panel implementation
│   │       ├── index.js
│   │       └── style.css
│   ├── popup/             # Popup UI
│   │   ├── index.js
│   │   └── style.css
│   ├── options/           # Options page
│   │   └── index.js
│   ├── scripting/         # Scripting injection
│   │   └── index.js
│   └── sidepanel/         # Side panel
│       └── index.js
├── .env                   # Environment variables
├── .env.development       # Development env vars
├── .env.production        # Production env vars
├── .gitignore             # Git ignore rules
├── package.json           # Project metadata
├── web-extend.config.js   # WebExtend configuration
├── web-ext.config.js      # Web-ext configuration
├── rsbuild.config.ts      # Rsbuild configuration
└── tsconfig.json          # TypeScript configuration

Top-level Directory

The following table describes the main files and directories at the root of your project:

NameDescription
public/Static assets that will be copied directly to the dist folder
src/Source code directory containing your extension's implementation
.web-extend/Temporary directory used by WebExtend for build artifacts
.envEnvironment variables loaded in all scenarios
.env.localLocal environment overrides (should be added to .gitignore)
.env.developmentDevelopment-specific environment variables
.env.productionProduction-specific environment variables
.env.development.localLocal development environment overrides (add to .gitignore)
.env.production.localLocal production environment overrides (add to .gitignore)
.gitignoreSpecifies which files Git should ignore
package.jsonProject metadata, dependencies and scripts
rsbuild.config.tsRsbuild configuration file for build customization
web-extend.config.jsConfiguration file for WebExtend
web-ext.config.jsConfiguration file for web-ext
tsconfig.jsonTypeScript configuration (if using TypeScript)

Source Directory

The src/ directory contains your extension's source code, organized by feature/entry point. Here's the standard structure:

NameDescription
assets/Static assets that need processing (e.g., images, styles)
background/Background script implementation
bookmarks/Bookmarks page override implementation
content/ or contents/Content scripts (single or multiple)
devtools/DevTools implementation
history/History page override implementation
newtab/New tab page override implementation
options/Options page implementation
pages/HTML Pages
popup/Extension popup UI implementation
sandbox/ or sandboxes/Sandbox pages (single or multiple)
scripting/Scripting injection implementation
sidepanel/Side panel implementation

Manifest Generation

There is no need to manually write manifest.json file, WebExtend will generate it automatically based on your project structure. The following table shows how your files map to manifest fields:

Manifest KeysSource Location
manifest_versionDefaults to 3
namedisplayName or name from package.json
versionversion from package.json
descriptiondescription from package.json
authorauthor from package.json
homepage_urlhomepage from package.json
icons, action.default_iconsrc/assets/icon-[size].png
action.default_popupsrc/popup/index.js or src/popup.js
background.service_workersrc/background/index.js or src/background.js
content_scriptssrc/content/index.js or src/contents/*.js
options_ui.pagesrc/options/index.js or src/options.js
devtools_pagesrc/devtools/index.js or src/devtools.js
sandbox.pagessrc/sandbox/index.js or src/sandboxes/*.js
chrome_url_overrides.newtabsrc/newtab/index.js or src/newtab.js
chrome_url_overrides.bookmarkssrc/bookmarks/index.js or src/bookmarks.js
chrome_url_overrides.historysrc/history/index.js or src/history.js
side_panel.default_pathsrc/sidepanel/index.js or src/sidepanel.js
_localespublic/_locales/*
web_accessible_resourcespublic/*

Configuration Files

.env

WebExtend uses a flexible environment configuration system:

.env                   # Base variables, always loaded
.env.local             # Local overrides (git-ignored)
.env.development       # Development-specific variables
.env.production        # Production-specific variables
.env.[mode].local      # Local mode-specific overrides (git-ignored)

Loading priority (highest to lowest):

  1. .env.[mode].local
  2. .env.[mode]
  3. .env.local
  4. .env

Example configuration:

env
# .env
API_ENDPOINT=https://api.example.com
DEBUG=false

# .env.development
API_ENDPOINT=https://dev-api.example.com
DEBUG=true

See environment variables for more details.

web-extend.config.js

WebExtend allows customization of various aspects of your project through the web-extend.config.(ts|js|mjs) file.

For example:

web-extend.config.js
ts
import { defineConfig } from "web-extend";

export default defineConfig({
  srcDir: "src", // Source directory (default: "src")
  outDir: ".output", // Output directory (default: "dist")
  manifest: {}, // Custom manifest overrides (default: {})
  target: "firefox-mv2", // Browser target (default: "chrome-mv3")
  webExt: {}, // Customize web-ext configurations
  rsbuild: {}, // Customize Rsbuild configurations
});

web-ext.config.js

WebExtend uses web-ext as the browser runner. You can customize runner configurations through either:

  • The webExt option in web-extend.config.js file
  • A separate web-ext.config.(ts|js|mjs) file

When both configuration methods are provided, the webExt option in web-extend.config.js will take precedence, and web-ext.config.js will be ignored.

For example:

web-ext.config.js
javascript
import { defineWebExtConfig } from "web-extend";

export default defineWebExtConfig({
  startUrl: ["https://example.com"],
});

rsbuild.config.js

WebExtend uses Rsbuild as the bundler. You can customize Rsbuild configurations through either:

  • The rsbuild option in web-extend.config.js file
  • A separate rsbuild.config.(ts|js|mjs) file

When both configuration methods are provided, the rsbuild option in web-extend.config.js will take precedence, and rsbuild.config.js will be ignored.

For example:

rsbuild.config.js
js
import { defineConfig } from "@rsbuild/core";
import { pluginReact } from "@rsbuild/plugin-react";

export default defineConfig({
  plugins: [pluginReact()],
});

Released under the MIT License.