Defines API
defineBackground, defineContentScript, defineUnlistedScript, and definePage.
#Import from the addonova/defines subpath.
import {
defineBackground,
defineContentScript,
definePage,
defineUnlistedScript,
} from 'addonova/defines';
The helpers attach manifest metadata and run main when the module is imported.
They are not event registrars.
defineBackground
#function defineBackground(
definition: BackgroundDefinition | (() => void | Promise<void>),
): BackgroundDefinition;
import { defineBackground } from 'addonova/defines';
export default defineBackground(() => {
browser.runtime.onInstalled.addListener(() => {
console.log('installed');
});
});
Object form:
export default defineBackground({
persistent: false,
type: 'module',
include: ['chrome', 'firefox'],
main() {
console.log('background ready');
},
});
| Field | Type | Description |
|---|---|---|
persistent |
boolean | MV2 persistence. |
type |
'module' |
Module background. |
main |
function | Runs on import. |
include |
target[] | Restrict targets. |
exclude |
target[] | Skip targets. |
defineContentScript
#function defineContentScript(
definition: ContentScriptDefinition,
): ContentScriptDefinition;
export default defineContentScript({
matches: ['https://example.com/*'],
excludeMatches: ['https://example.com/private/*'],
runAt: 'document_idle',
allFrames: false,
world: 'ISOLATED',
cssInjectionMode: 'manifest',
main(context) {
console.log('content script ready', context.isValid);
},
});
main runs immediately unless registration: 'runtime' is set. Runtime
registration leaves loading to application code using the scripting API.
| Field | Type | Description |
|---|---|---|
matches |
string[] | Required match patterns. |
excludeMatches |
string[] | Excluded match patterns. |
includeGlobs |
string[] | Include globs. |
excludeGlobs |
string[] | Exclude globs. |
allFrames |
boolean | Run in all frames. |
runAt |
document_start, document_end, document_idle |
Injection timing. |
matchAboutBlank |
boolean | Match about:blank. |
matchOriginAsFallback |
boolean | Fall back to origin matching. |
world |
ISOLATED, MAIN |
Execution world. |
cssInjectionMode |
manifest, manual, none |
CSS handling. |
registration |
manifest, runtime |
Who registers the script. |
include |
string[] | Include filter. |
exclude |
string[] | Exclude filter. |
The manifest requires matches; without it the build reports
ADDONOVA_MANIFEST_CONTENT_SCRIPT_MATCHES.
ContentScriptContext
#interface ContentScriptContext {
readonly isValid: boolean;
onInvalidated(callback: () => void): () => void;
setTimeout(callback, delay?, ...args): number;
clearTimeout(id): void;
setInterval(callback, delay?, ...args): number;
clearInterval(id): void;
}
Timers are cancelled when the extension context is invalidated. The
onInvalidated callback returns an unsubscribe function.
export default defineContentScript({
matches: ['https://example.com/*'],
main(context) {
const id = context.setInterval(() => {
console.log('still valid', context.isValid);
}, 1000);
context.onInvalidated(() => {
console.log('context gone');
context.clearInterval(id);
});
},
});
defineUnlistedScript
#function defineUnlistedScript(
definition: UnlistedScriptDefinition | (() => void | Promise<void>),
): UnlistedScriptDefinition;
Builds a script without adding it to the manifest. Other code or a runtime mechanism loads it.
export default defineUnlistedScript(() => {
console.log('unlisted script ready');
});
definePage
#function definePage(definition?: PageDefinition): PageDefinition;
Marks an HTML entrypoint as a page and provides target filters without adding a manifest field by itself.
export default definePage({
include: ['chrome', 'edge'],
});
HTML meta tags
#HTML entrypoints may declare:
<meta name="manifest.type" content="sandbox" />
<meta name="manifest.include" content="chrome,edge" />
<meta name="manifest.exclude" content="firefox" />
Error handling
#If main throws or rejects, Addonova logs
[addonova] Entrypoint failed: and continues. Build-time validation does not
execute entrypoints.