Repository navigation
Docusaurus opens a running Chromium browser instead of the system default browser on macOS #12599
Description
Have you read the Contributing Guidelines on issues?
- I have read the Contributing Guidelines on issues.
Prerequisites
- I'm using the latest version of Docusaurus.
- I have tried the
npm run clearoryarn clearcommand. - I have tried
rm -rf node_modules yarn.lock package-lock.jsonand re-installing packages. - I have tried creating a repro with https://new.docusaurus.io.
- I have read the console error message carefully (if applicable).
Description
On macOS, Docusaurus prioritizes running Chromium-based browsers
over the system default browser when starting the development server.
For example, when Firefox is configured as the system default browser,
running docusaurus start opens Google Chrome if Chrome is already running.
If no supported Chromium-based browser is running, Firefox opens as expected.
This behavior is unexpected because browser selection depends on which
Chromium-based browsers happen to be running, rather than the user's
system preference.
Root cause
The behavior originates from tryOpenWithAppleScript()
in openBrowser.ts.
When no browser is explicitly specified, Docusaurus attempts to reuse
a running Chromium-based browser through AppleScript before falling
back to the system default browser.
Proposed solution
Docusaurus should respect the system default browser when
DOCUSAURUS_BROWSER is not explicitly set.
Ideally, the existing tab-reuse optimization would be preserved
when it does not conflict with the system default browser.
Additional context
Setting DOCUSAURUS_BROWSER=firefox can be used as a workaround,
but the default behavior should respect the user's OS-level
browser preference.
Reproducible demo
https://github.com/ToB213/docusaurus-browser-repro
Steps to reproduce
- Set Firefox as the default browser on macOS.
- Launch both Firefox and Google Chrome.
- Clone the reproduction repository and install dependencies.
- Run
npm run start. - Observe that the development server opens in Google Chrome instead of Firefox.
- Stop the development server (
Ctrl+C). - Quit Google Chrome and any other running Chromium-based browsers.
- Run
npm run startagain. - Observe that Firefox opens instead.
Expected behavior
Docusaurus should open the development server in the system default
browser unless the user explicitly specifies another browser.
In this case, Firefox should open regardless of whether Google Chrome
is already running.
Actual behavior
Docusaurus opens Google Chrome when Chrome is already running,
even though Firefox is configured as the system default browser.
When no supported Chromium-based browser is running, Docusaurus
opens Firefox as expected.
The browser selection therefore changes depending on which
Chromium-based browsers are running, rather than consistently
following the system default browser.
Your environment
- Public source code: N/A
- Public site URL: N/A
- Docusaurus version used: 3.10.2
- Environment name and version: Node.js v24.16.0, Firefox, Google Chrome
- Operating system and version: macOS 27.0 (Build 26A428, Apple Silicon)
- System default browser: Firefox
Self-service
- I'd be willing to fix this bug myself.
Activity
Josh-Cena commentedon Oct 9, 2026
I can see why always using the default browser would be sensible OS-wise, but I myself—and I expect many others—are already relying on the current behavior of prioritizing the open browser. My default browser is Safari, but I practically never use it for development. It's only used for opening random links. I think having Chrome open but Firefox not is a strong signal that the path of least context switching is to open in Chrome.
ToB213 commentedon Oct 10, 2026
Thanks for sharing your perspective! I understand that prioritizing an already running browser can be useful for development workflows.
My main concern is that the current behavior specifically prioritizes Chromium-based browsers, rather than running browsers in general.
For example, even when Firefox is my default browser and is already running, Docusaurus opens Chrome if Chrome happens to be running as well.
I understand the rationale behind the current behavior, and I appreciate the clarification.
Josh-Cena commentedon Oct 10, 2026
Yeah, not sure why it would prioritize Chrome that way. My guess is that this came all the way when we copied the code over from create-react-app.
ToB213 commentedon Oct 13, 2026
Yeah, that makes sense. I also suspect this behavior was inherited from Create React App.
I agree that prioritizing an already running browser is useful, and I wouldn't want to lose that behavior.
What concerns me is that the tab-reuse implementation specifically targets Chromium-based browsers, which seems to influence browser selection as a side effect.
I'm not sure whether prioritizing Chromium-based browsers was an intentional design decision or simply a consequence of how tab reuse was implemented.
Since
DOCUSAURUS_BROWSERalready provides a workaround, I see this more as a potential developer experience improvement than a critical bug.I'd be interested to hear whether you think this issue is worth addressing, perhaps by improving the browser selection logic or simply documenting the current behavior.
mvanhorn commentedon Oct 16, 2026
On Darwin, tryOpenWithAppleScript took the Chrome tab-reuse path whenever the browser value was not a string, which is what an unset DOCUSAURUS_BROWSER produces, or when it was exactly "google chrome". The URL was handed to AppleScript before the generic opener could follow the system default.
The AppleScript path now runs only when the platform is macOS and the browser is exactly "google chrome", so an explicit Chrome choice still reuses an existing tab.
#12685