WSL runner should check DISPLAY env var before refusing to open browser (WSLg support)
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 10.5k
- Forks
- 564
- PR merge metrics
- No merged PRs in 30d
Description
Description
The WSL runner currently refuses to open browsers unconditionally, but this is outdated given modern WSLg (WSL GUI) support which provides native GUI capabilities with DISPLAY environment variable automatically configured.
Current Behavior
The WSL runner (wsl.mjs) always shows this warning and refuses to open browsers:
WARN Cannot open browser when using WSL. Load ".output/chrome-mv3-dev" as an unpacked extension manually
This happens even when DISPLAY is set and GUI applications work perfectly.
Expected Behavior
When DISPLAY environment variable is set (indicating WSLg or X11 forwarding), WXT should attempt to open the browser normally instead of refusing.
Environment
- OS: WSL2 with WSLg on Windows 11
- DISPLAY:
:10.0(automatically set by WSLg) - WXT Version: 0.20.11
- Browser: Google Chrome in WSL2
Reproduction
- Run WXT in WSL2 with WSLg enabled (Windows 11 default)
- Run
wxtorwxt build - Browser fails to open despite DISPLAY being set and GUI support working
Manual Workaround
Browser opens successfully when launched manually with DISPLAY set:
DISPLAY=:10.0 /usr/bin/google-chrome --load-extension=.output/chrome-mv3-dev
Proposed Solution
Update the WSL runner to check for DISPLAY before refusing:
export function createWslRunner() {
return {
async openBrowser() {
// Check if DISPLAY is set (WSLg/X11 support)
if (!process.env.DISPLAY) {
wxt.logger.warn(
\`Cannot open browser when using WSL without GUI support. Load "\${relative(
process.cwd(),
wxt.config.outDir
)}" as an unpacked extension manually\`
);
return;
}
// DISPLAY is set, delegate to default browser runner
// (let the normal browser opening logic handle it)
},
async closeBrowser() {
}
};
}
Related Issues
- #55 - Original WSL support issue that disabled browser opening entirely
- This was appropriate at the time, but WSLg (released 2021) changes the situation
Impact
This affects all WSL2 users on Windows 11+ who have WSLg enabled by default. The warning is misleading and forces manual browser loading despite GUI support being fully functional.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in packages/wxt/src/core/runners/wsl.ts and inspect createWslRunner, then compare its browser-opening behavior with the default browser runner. Verify that WSL without DISPLAY still warns, while WSLg or X11 environments with DISPLAY set attempt normal browser opening; confirm both cases with the existing WXT run or build flow.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100