fix(types): Add type safety to `browser.runtime.executeScript` `files` option by nickbar01234 · Pull Request #2142 · wxt-dev/wxt

nickbar01234 · 2026-02-21T04:54:37Z

Overview

Previously, browser.script.executeScript({ files: [] }) does not provide any type hint about what file paths are injectable. This PR augments the type definition to all ScriptPublicPath, generated from path.d.ts.

A couple of notes

I think ScriptPublicPath union is wider than what can be provided to executeScript. The worst case is we run into runtime errors, which is similar to the state before this change.
This is a breaking change for downstream consumers that specifies a non-existent scripts

Manual Testing

Manual link with a local extension to confirm the build generates the right type definition

Related Issue

This PR closes #<issue_number>

netlify · 2026-02-21T04:54:42Z

✅ Deploy Preview for creative-fairy-df92c4 ready!

Name	Link
🔨 Latest commit	`e2293ad`
🔍 Latest deploy log	https://app.netlify.com/projects/creative-fairy-df92c4/deploys/699a1a939cc20c0008cf9b7e
😎 Deploy Preview	https://deploy-preview-2142--creative-fairy-df92c4.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

nickbar01234 · 2026-02-21T04:56:27Z

packages/wxt/src/core/generate-wxt-dir.ts

+      WxtBrowser["scripting"]["executeScript"]
+    >[0] & { files: Array<${paths.join(' | ')}>; func?: never | undefined };
+
+    type ReplaceFirstArg<Fnc, Arg> = Fnc extends {


tbh: Not a big fan of this typescript magic, so open to other suggestions

Alternatively, @aklinker1 curious if it's an option to update the backing @wxt-dev/browser package to have a generic T for file paths, which we can dynamically declare when generating the declaration file based on the filenames

@nickbar01234 Did you try how we do it here?

wxt/packages/wxt/src/core/generate-wxt-dir.ts

Lines 89 to 108 in 430a3ac

const template = `// Generated by wxt

import "wxt/browser";

declare module "wxt/browser" {

export type PublicPath =

{{ union }}

type HtmlPublicPath = Extract<PublicPath, \`\${string}.html\`>

export interface WxtRuntime {

getURL(path: PublicPath): string;

getURL(path: \`\${HtmlPublicPath}\${string}\`): string;

}

}

`;

return {

path: 'types/paths.d.ts',

text: template.replace('{{ union }}', unions || ' | never'),

tsReference: true,

};

}

wxt/packages/wxt/src/browser.ts

Lines 14 to 31 in 430a3ac

/**

* This interface is empty because it is generated per-project when running `wxt prepare`. See:

* - `.wxt/types/paths.d.ts`

*/

export interface WxtRuntime {}

/**

* This interface is empty because it is generated per-project when running `wxt prepare`. See:

* - `.wxt/types/i18n.d.ts`

*/

export interface WxtI18n {}

export type WxtBrowser = Omit<typeof _browser, 'runtime' | 'i18n'> & {

runtime: WxtRuntime & Omit<(typeof _browser)['runtime'], 'getURL'>;

i18n: WxtI18n & Omit<(typeof _browser)['i18n'], 'getMessage'>;

};

export const browser: WxtBrowser = _browser;

We should be able to simplify this quite a bit. Unless there's something different about what you're doing here.

if it's an option to update the backing @wxt-dev/browser package to have a generic T for file paths, which we can dynamically declare when generating the declaration file based on the filenames

I'm hesitant to make excessive changes to that package since it's generated based on @types/chrome. It may be possible to automate, but it would become more fragile. I'd prefer we use the existing patterns for augmenting the browser types

Gotcha, I think I see what wxt/packages/wxt/src/browser.ts is doing. Let me try refactoring this code to match the pattern

nickbar01234 · 2026-02-21T20:20:50Z

packages/wxt/src/browser.ts

+type ScriptInjection<Args extends any[], Result> =
+  Browser.scripting.ScriptInjection<Args, Result> extends infer T
+    ? T extends { files: string[] }
+      ? Omit<T, 'files'> & { files: ScriptPublicPath[] }


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

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.

nickbar01234 · 2026-02-21T20:21:55Z

@aklinker1 just updated the implementation whenever you have some downtime to review!

aklinker1

Perfect, thanks. Much simpler!

aklinker1 · 2026-02-21T20:28:07Z

packages/wxt/src/browser.ts

+interface WxtScripting {
+  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;
+  };
+}


Huh, I guess we don't need to generate some of the overrides per-project, like the runtime overrides... I could just import the PublicPath type like you did here...

not too familiar with the typescript build process itself, so I was mostly referencing https://github.com/wxt-dev/wxt/blob/main/packages/wxt/src/utils/inject-script.ts#L4-L8 that also uses the public type before they existed

Yeah, I think I'll move to this when possible. Modules like i18n will still need to generate it's own module augmentations, but the static stuff can be put here.

packages/wxt/src/browser.ts

pkg-pr-new · 2026-02-21T20:38:06Z

Open in StackBlitz

@wxt-dev/analytics

npm i https://pkg.pr.new/@wxt-dev/analytics@2142

@wxt-dev/auto-icons

npm i https://pkg.pr.new/@wxt-dev/auto-icons@2142

@wxt-dev/browser

npm i https://pkg.pr.new/@wxt-dev/browser@2142

@wxt-dev/i18n

npm i https://pkg.pr.new/@wxt-dev/i18n@2142

@wxt-dev/module-react

npm i https://pkg.pr.new/@wxt-dev/module-react@2142

@wxt-dev/module-solid

npm i https://pkg.pr.new/@wxt-dev/module-solid@2142

@wxt-dev/module-svelte

npm i https://pkg.pr.new/@wxt-dev/module-svelte@2142

@wxt-dev/module-vue

npm i https://pkg.pr.new/@wxt-dev/module-vue@2142

@wxt-dev/runner

npm i https://pkg.pr.new/@wxt-dev/runner@2142

@wxt-dev/storage

npm i https://pkg.pr.new/@wxt-dev/storage@2142

@wxt-dev/unocss

npm i https://pkg.pr.new/@wxt-dev/unocss@2142

@wxt-dev/webextension-polyfill

npm i https://pkg.pr.new/@wxt-dev/webextension-polyfill@2142

wxt

npm i https://pkg.pr.new/wxt@2142

commit: e2293ad

codecov · 2026-02-21T20:38:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.14%. Comparing base (3b15450) to head (e2293ad).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2142      +/-   ##
==========================================
+ Coverage   75.94%   76.14%   +0.19%     
==========================================
  Files         113      113              
  Lines        3043     3043              
  Branches      680      680              
==========================================
+ Hits         2311     2317       +6     
+ Misses        646      641       -5     
+ Partials       86       85       -1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nickbar01234 · 2026-02-21T20:57:08Z

btw @aklinker1, I notice that we don't collect CSS files in public path and the scripts eligible for injectScripts should be declared web_accessible_resources right? Is it worth doing a cleanup here too?

github-actions · 2026-02-21T20:58:23Z

Thanks for helping make WXT better!

aklinker1 · 2026-02-22T14:53:55Z

scripts eligible for injectScripts should be declared web_accessible_resources right? Is it worth doing a cleanup here too?

@nickbar01234 I'm against making assumptions to generate web_accessible_resources. For unlisted scripts, they can also be used as web workers, which don't always need to be added to web_accessible_resources.

That said, I could see a feature like this being useful. Feel free to implement if you'd like: #536 (comment)

nickbar01234 · 2026-02-22T18:13:28Z

scripts eligible for injectScripts should be declared web_accessible_resources right? Is it worth doing a cleanup here too?

@nickbar01234 I'm against making assumptions to generate web_accessible_resources. For unlisted scripts, they can also be used as web workers, which don't always need to be added to web_accessible_resources.

That said, I could see a feature like this being useful. Feel free to implement if you'd like: #536 (comment)

gotcha. Is anyone actively working on #544? The issue you referenced seems like it can be bundled as part of the issue

aklinker1 · 2026-02-22T20:28:27Z

Actually, nevermind. After looking at #544 again, I don't think I want to add these features. It might seem convenient at first, but managing all these global options (permissions, web accessible resources) in one place keeps things simple. If they're spread all over the place, you have to look everywhere for them - imagine removing a permission from one entrypoint, forgetting to remove it from another. Seems like it will cause bugs and tech debt... I think having them in one place is the right move.

And thinking about it more, a accessible: true option wouldn't be enough to build a MV3 web accessible resources entry.

So I'm actually gonna close #544 as not planned, sorry about that.

…` option (#2142) Co-authored-by: nickbar01234 <nickbar01234gmail.com> Co-authored-by: Aaron <aaronklinker1@gmail.com>

Augment executeScript type

1fd9fd8

nickbar01234 requested review from Timeraa and aklinker1 as code owners February 21, 2026 04:54

nickbar01234 commented Feb 21, 2026

View reviewed changes

nickbar01234 added 2 commits February 21, 2026 00:06

Fix tests

d827f7a

Refactor implementation

c2ba008

nickbar01234 commented Feb 21, 2026

View reviewed changes

aklinker1 changed the title ~~Augment executeScript type~~ fix(types): Add type safety to browser.runtime.executeScript files option. Feb 21, 2026

aklinker1 approved these changes Feb 21, 2026

View reviewed changes

aklinker1 changed the title ~~fix(types): Add type safety to browser.runtime.executeScript files option.~~ fix(types): Add type safety to browser.runtime.executeScript files option Feb 21, 2026

nickbar01234 and others added 3 commits February 21, 2026 15:43

Merge branch 'main' into nickbar01234/typed-execute-script

e204bce

Small cleanup and demo changes

b301497

fix comment

e2293ad

aklinker1 approved these changes Feb 21, 2026

View reviewed changes

aklinker1 enabled auto-merge (squash) February 21, 2026 20:57

aklinker1 merged commit 42d65cb into wxt-dev:main Feb 21, 2026
18 checks passed

nickbar01234 deleted the nickbar01234/typed-execute-script branch February 21, 2026 20:58

dahomita mentioned this pull request Feb 22, 2026

fix(types): include CSS entrypoints in PublicPath generation #2150

Merged

2 tasks

aklinker1 mentioned this pull request Feb 22, 2026

Support more manifest fields in entrypoint options #544

Closed

3 tasks

aklinker1 added a commit that referenced this pull request Feb 22, 2026

fix(types): Add type safety to browser.runtime.executeScript `files…

4500ca5

…` option (#2142) Co-authored-by: nickbar01234 <nickbar01234gmail.com> Co-authored-by: Aaron <aaronklinker1@gmail.com>

	const template = `// Generated by wxt
	import "wxt/browser";

	declare module "wxt/browser" {
	export type PublicPath =
	{{ union }}
	type HtmlPublicPath = Extract<PublicPath, \`\${string}.html\`>
	export interface WxtRuntime {
	getURL(path: PublicPath): string;
	getURL(path: \`\${HtmlPublicPath}\${string}\`): string;
	}
	}
	`;

	return {
	path: 'types/paths.d.ts',
	text: template.replace('{{ union }}', unions \|\| ' \| never'),
	tsReference: true,
	};
	}

	/**
	* This interface is empty because it is generated per-project when running `wxt prepare`. See:
	* - `.wxt/types/paths.d.ts`
	*/
	export interface WxtRuntime {}

	/**
	* This interface is empty because it is generated per-project when running `wxt prepare`. See:
	* - `.wxt/types/i18n.d.ts`
	*/
	export interface WxtI18n {}

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

	export const browser: WxtBrowser = _browser;

Uh oh!

Conversation

nickbar01234 commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Manual Testing

Related Issue

Uh oh!

netlify bot commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for creative-fairy-df92c4 ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aklinker1 Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aklinker1 Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nickbar01234 commented Feb 21, 2026

Uh oh!

aklinker1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pkg-pr-new bot commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nickbar01234 commented Feb 21, 2026

Uh oh!

Uh oh!

github-actions bot commented Feb 21, 2026

Uh oh!

aklinker1 commented Feb 22, 2026

Uh oh!

nickbar01234 commented Feb 22, 2026

Uh oh!

aklinker1 commented Feb 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nickbar01234 commented Feb 21, 2026 •

edited

Loading

netlify bot commented Feb 21, 2026 •

edited

Loading

aklinker1 Feb 21, 2026 •

edited

Loading

aklinker1 Feb 21, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 21, 2026 •

edited

Loading

codecov bot commented Feb 21, 2026 •

edited

Loading