Web Accessible Resources#

Web-accessible resources are files within an extension that can be accessed by web pages or other extensions. These resources are often used for images, scripts, or stylesheets that are required by content scripts or pages embedded within an extension's context.

How It Works?#

Extension.js performs the following tasks for web-accessible resources:

1. Generate Manifest Patches: Updates the manifest.json file with paths for web-accessible resources based on the content scripts and assets being used.
2. Add Resources to Compilation: Assets used in content scripts or referenced in the manifest are added to the compilation process.
3. Emit Assets: All assets declared as web-accessible are emitted to the output directory.
4. Support for Multiple Asset Types: Various file types, including images, scripts, and stylesheets, are supported.
5. Error Handling: Checks for missing assets and issues warnings if resources declared in the manifest are not found during the build process.

Web Accessible Resources Support#

The following manifest field is used to declare web-accessible resources:

Sample manifest.json File#

If the resources you need to declare are already imported by the content scripts, you don't need to declare them in the web_accessible_resources field. For all other cases, you can declare the resources in the manifest.json file.

Manifest V3#

Here's an example of how to declare web-accessible resources in the manifest.json file for manifest V3.

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "web_accessible_resources": [
    {
      "resources": ["images/*.png", "scripts/*.js", "styles/*.css"],
      "matches": ["<all_urls>"]
    }
  ],
  "content_scripts": [
    {
      "matches": ["https://example.com/*"],
      "css": ["styles/content.css"],
      "js": ["scripts/content.js"]
    }
  ]
}

Manifest V2#

Here's an example of how to declare web-accessible resources in the manifest.json file for manifest V2.

{
  "manifest_version": 2,
  "name": "My Extension",
  "version": "1.0",
  "web_accessible_resources": ["images/*.png", "scripts/*.js", "styles/*.css"],
  "content_scripts": [
    {
      "matches": ["https://example.com/*"],
      "css": ["styles/content.css"],
      "js": ["scripts/content.js"]
    }
  ]
}

In the examples above, the web_accessible_resources field exposes specific resources (images, scripts, styles) for web pages that match the pattern defined in matches.

Output Path#

For a resource to be web-accessible, it must be emitted to the output directory. The easiest way to achieve this is to place the resources in the /public folder. Assets declared in there will be automatically copied to the output directory during the build process and will be accessible from the root of the extension.

Example with public folder#

/public
  /images
    icon.png
  /scripts
    content.js
  /styles
    content.css

In the example above, the icon.png, content.js, and content.css files are web-accessible resources that can be accessed by web pages or other extensions, so the way they should be declared in the web_accessible_resources field would be:

For Manifest V3#

{
  "web_accessible_resources": [
    {
      "resources": [
        "images/icon.png",
        "scripts/content.js",
        "styles/content.css"
      ],
      "matches": ["<all_urls>"]
    }
  ]
}

For Manifest V2#

{
  "web_accessible_resources": [
    "images/icon.png",
    "scripts/content.js",
    "styles/content.css"
  ]
}

For resources not declared in the web_accessible_resources field, you can predict their path by examining the /dist folder after building the extension. The resources will be placed in the root of the output directory. To reference them in your code, you can use the chrome.runtime.getURL method.

Example with dist/ folder#

/dist
  /pages
    my-page.html
  /sandbox
    page-0.html
  manifest.json

In the example above, the my-page.html and page-0.html files are web-accessible resources that can be accessed by web pages or other extensions, so the way they should be declared in the web_accessible_resources field would be:

For Manifest V3#

{
  "web_accessible_resources": [
    {
      "resources": ["pages/my-page.html", "sandbox/page-0.html"],
      "matches": ["<all_urls>"]
    }
  ]
}

Best Practices#

• Always declare resources in web_accessible_resources if they are intended to be accessible by web pages or other external scripts.
• Place additional resources that need to be web-accessible in the /public folder to keep your manifest.json clean and organized.
• Ensure your content scripts correctly reference these assets, especially when working with external web pages.

Next Steps#

• Learn more about managing assets and resources with Special Folders.