browser-extension-manifest-fields

browser-extension-manifest-fields

Parse and resolve browser extension manifest fields to absolute paths.

Parse a manifest.json and resolve file paths for HTML, icons, JSON, scripts, locales, web accessible resources; also surface theme image paths and semantic fields used for restart-required decisions.

What it does

• HTML, icons, JSON, and scripts declared in the manifest are resolved to absolute file system paths, with public-root inputs normalized (e.g., /something, /public/something, public/something).
• Browser-prefixed manifest keys are honored using the current target browser (e.g., chromium:action for Chrome vs gecko:action for Firefox/Gecko).
• content_scripts entries include both JS and CSS assets when present, preserving ordering.
• web_accessible_resources are passed through as-is for MV3, or strings for MV2.
• Locales under _locales/* are discovered if present.
• In development, manifest data cooperates with the reload pipeline: CSP and permissions are patched, and minimal background entries are ensured so the reloader can be injected.

Usage

import { getManifestFieldsData } from "browser-extension-manifest-fields";

// Resolve manifest field paths
const fields = getManifestFieldsData({
  manifestPath: "/abs/path/to/manifest.json",
});

Sample output:

{
  "html": {
    "action/index": "/abs/path/to/public/chrome-popup.html",
    "options/index": "/abs/path/to/public/options.html"
  },
  "icons": {
    "action": "/abs/path/to/icons/action.png",
    "icons": ["/abs/path/to/icons/16.png", "/abs/path/to/icons/48.png"]
  },
  "json": {
    "declarative_net_request": [
      {
        "id": "rules",
        "enabled": true,
        "path": "/abs/path/to/rules/rules_1.json"
      }
    ]
  },
  "scripts": {
    "background/service_worker": "/abs/path/to/src/background.js",
    "content_scripts/content-0": [
      "/abs/path/to/src/content.js",
      "/abs/path/to/src/content.css"
    ]
  },
  "web_accessible_resources": [
    {
      "resources": ["/abs/path/to/assets/*"],
      "matches": ["<all_urls>"]
    }
  ],
  "theme": {
    "theme/images/frame.png": "/abs/path/to/public/theme/frame.png"
  },
  "semantic": {
    "permissions": ["storage"],
    "host_permissions": ["https://*/*"],
    "csp": {"mv": 3, "extension_pages": "script-src 'self'"}
  }
}

API

// manifest-fields
export interface ManifestFields {
  html: Record<string, any>
  icons: Record<string, any>
  json: Record<string, any>
  locales?: string[] | undefined
  scripts: Record<string, any>
  web_accessible_resources?: Array<string | Record<string, any>> | undefined
  theme?: Record<string, string> | undefined
  semantic?:
    | {
        permissions?: string[]
        optional_permissions?: string[]
        host_permissions?: string[]
        csp?:
          | {mv: 2; value?: string}
          | {
              mv: 3
              extension_pages?: string
              sandbox?: string
              raw?: Record<string, any>
            }
        externally_connectable?: Record<string, any>
        gecko_id?: string
      }
    | undefined
}

export function getManifestFieldsData(args: {
  manifestPath: string;
  browser?: string;
}): ManifestFields;

Special folders helper

import {getSpecialFoldersData} from 'browser-extension-manifest-fields'

// Discovers assets under public/, html pages/ and script entries
const entries = getSpecialFoldersData({manifestPath: '/abs/path/manifest.json'})
// entries: {
//   public: Record<string, string>
//   pages: Record<string, string>
//   scripts: Record<string, string>
// }

Publish provenance helper

import {getProvenanceData} from 'browser-extension-manifest-fields'

const prov = getProvenanceData({manifestPath: '/abs/path/manifest.json'})
// prov.enabled is true when package.json has publishConfig.provenance=true and
// CI workflows request id-token: write and use `--provenance` on publish.
// You can inspect prov.workflows for details.

Path resolution conventions

• Relative paths resolve from the manifest directory.
• Leading / resolves from the extension root (package root), not the OS root.
• OS-absolute filesystem paths are not part of the browser extension spec; prefer relative or /public/... references instead.

License

MIT (c) Cezar Augusto