Skip to content

fix(types): Add type safety to browser.runtime.executeScript files option #2142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aklinker1 merged 6 commits into from
Feb 21, 2026
Merged

fix(types): Add type safety to browser.runtime.executeScript files option #2142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1fd9fd8
Augment executeScript type
Feb 21, 2026
d827f7a
Fix tests
Feb 21, 2026
c2ba008
Refactor implementation
Feb 21, 2026
e204bce
Merge branch 'main' into nickbar01234/typed-execute-script
nickbar01234 Feb 21, 2026
b301497
Small cleanup and demo changes
aklinker1 Feb 21, 2026
e2293ad
fix comment
aklinker1 Feb 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions packages/wxt-demo/src/entrypoints/background.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,3 +43,14 @@ export default defineBackground({
storage.setItem('session:startTime', Date.now());
},
});

function _otherTypeChecksNotEvaluated() {
browser.scripting.executeScript({
target: { tabId: 1 },
files: [
'/background.js',
// @ts-expect-error: Should error for non-existing paths
'/other.js',
],
});
}
33 changes: 32 additions & 1 deletion packages/wxt/src/browser.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
* @module wxt/browser
*/
import { browser as _browser, type Browser } from '@wxt-dev/browser';
import type { ScriptPublicPath } from './utils/inject-script';

/**
* This interface is empty because it is generated per-project when running `wxt prepare`. See:
Expand All @@ -23,9 +24,39 @@ export interface WxtRuntime {}
*/
export interface WxtI18n {}

export type WxtBrowser = Omit<typeof _browser, 'runtime' | 'i18n'> & {
type ScriptInjection<Args extends any[], Result> =
Browser.scripting.ScriptInjection<Args, Result> extends infer T
? T extends { files: string[] }
? Omit<T, 'files'> & { files: ScriptPublicPath[] }
Copy link
Contributor Author

@nickbar01234 nickbar01234 Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API docs say that file injections can be either CSS or JS, which does not align with my understanding of executeScript API.

The path of the JS or CSS files to inject, relative to the extension's root directory. Exactly one of the files or func must be specified.

If this is the case, we'd need to add more union to ScriptPublicPath. The other concern is downstream consumers with wrong file name will break when they pick up this version. My thought is that it's ok for better type safety

Copy link
Member

@aklinker1 aklinker1 Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, it should be fine for now.

MDN doesn't include CSS files in their docs: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/executeScript

I'd say it's fine for now, if someone opens an issue we'll know what needs added.

: T
: never;
type InjectionResult<Result> = Array<
Browser.scripting.InjectionResult<Awaited<Result>>
>;

export interface WxtScripting {
executeScript: {
/**
* @see {@link Browser.scripting.executeScript}
*/
<Args extends any[], Result>(
injection: ScriptInjection<Args, Result>,
): Promise<InjectionResult<Result>>;
<Args extends any[], Result>(
injection: ScriptInjection<Args, Result>,
callback: (results: InjectionResult<Result>) => void,
): void;
};
}

export type WxtBrowser = Omit<
typeof _browser,
'runtime' | 'i18n' | 'scripting'
> & {
runtime: WxtRuntime & Omit<(typeof _browser)['runtime'], 'getURL'>;
i18n: WxtI18n & Omit<(typeof _browser)['i18n'], 'getMessage'>;
scripting: WxtScripting &
Omit<(typeof _browser)['scripting'], 'executeScript'>;
};

export const browser: WxtBrowser = _browser;
Expand Down
Loading