wxt-dev / wxt-dev/wxt

WSL runner should check DISPLAY env var before refusing to open browser (WSLg support)

Open
#1,931 7 comments 8 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

contribution welcome good first issue
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

  1. Run WXT in WSL2 with WSLg enabled (Windows 11 default)
  2. Run wxt or wxt build
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.