Scripts#

JavaScript files power multiple aspects of an extension's functionality. User scripts, background processes, content scripts, and service workers all leverage JavaScript to deliver dynamic behavior and respond to user interactions. Extension.js ensures that JavaScript and TypeScript files defined in the manifest.json are correctly processed, with full support for hot-module replacement (HMR) and other development tools.

How It Works#

Extension.js handles the following for script resources:

1. Emit Script Files: All JavaScript files are processed and emitted to the dist output directory.
2. Add Script Dependencies: Script files are included in the file dependencies of the build, so updates trigger recompilation.
3. Enable HMR for Development: During development, HMR is enabled for content scripts, background scripts, and user scripts, facilitating fast iteration.
4. Error Handling: Missing or misconfigured scripts referenced in manifest.json are flagged during the build to prevent runtime issues.

Supported Manifest Fields for Scripts#

Sample Script Declaration in manifest.json#

Here's an example of defining JavaScript files in manifest.json:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "background": {
    "service_worker": "./scripts/background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["./scripts/content-script.js"],
      "css": ["./styles/content-style.css"]
    }
  ]
}

Adding and Managing JavaScript#

You should be able to manage y Extension.js processes additional JavaScript files that provide auxiliary functions, like utilities or helper functions, even if they're not defined in the manifest. Place these scripts in the /scripts folder for automatic inclusion in the build.

Example Usage#

Add utility scripts or other JavaScript resources to /scripts:

scripts/
└── extra-script.js

Output Path#

Script output paths are structured according to their context within the manifest:

# Background scripts:

background/
└── scripts.js

# Service Workers:

background/
└── service-worker.js

# Content Scripts:

content_scripts/
└── scripts-0.js

# User Scripts:

user_scripts/
└── api_script.js

How Extension.js Handles Scripts#

The plugin for script file support in Extension.js ensures the following during compilation:

1. Script Entries: Entries from both the manifest and the /scripts folder are included in the build process.
2. Inject CSS for Content Scripts: CSS files within content_scripts are dynamically injected to support HMR.
3. Public Path Fixes: The public path for content scripts is corrected in production to prevent resource loading issues.
4. Handle Main World Scripts: Ensures scripts running in the main world have the correct public path.

Best Practices#

• Utilize the /scripts Folder: Place all utility and helper scripts that aren't declared in manifest.json here.
• Optimize HMR: Leverage HMR to quickly iterate on content and background scripts during development.
• Modularize Code: Organize scripts by functionality to improve maintainability and readability of your extension's codebase.

Next Steps#

• Learn how to structure and manage scripts using Special Folders.