Skip to content

fix: eliminate Node.js path dependencies in client-side code#30

Closed
rsp2k wants to merge 1 commit intoFevol:mainfrom
rsp2k:fix/browser-compat-clean
Closed

fix: eliminate Node.js path dependencies in client-side code#30
rsp2k wants to merge 1 commit intoFevol:mainfrom
rsp2k:fix/browser-compat-clean

Conversation

@rsp2k
Copy link
Copy Markdown
Contributor

@rsp2k rsp2k commented Jan 21, 2026

What's the problem?

In dev mode, the console fills up with warnings like:

Module "path" has been externalized for browser compatibility. Cannot access "path.sep" in client code.

The graph renders briefly then disappears. Root cause: preprocess-sitemap.ts imports micromatch, which pulls in picomatchnode:path. Browsers don't have node:path, so Vite stubs it out and things break.

The fix

Created sitemap/browser-utils.ts with pure JS alternatives:

  • isGlobMatch() / firstMatchingPatternBrowser() - regex-based glob matching (replaces micromatch for client code)
  • joinUrlPath() - string-based path joining

Updated all client-side files to import from browser-utils.ts. Server-side Astro frontmatter can still use the full micromatch via util.ts.

Tested

  • Dev mode: clean console, graph works
  • Prod build + preview: works fine

No breaking changes - just swapping out the internals.

…ent code

The plugin was causing Vite warnings about "Module path has been externalized
for browser compatibility" because client-side code was importing micromatch,
which depends on picomatch, which uses node:path.

Changes:
- Create sitemap/browser-utils.ts with pure JavaScript utilities safe for browsers
- Add isGlobMatch() and firstMatchingPatternBrowser() as lightweight alternatives
  to micromatch for client-side glob matching
- Add joinUrlPath() for browser-safe URL path joining (replaces node:path.join)
- Update preprocess-sitemap.ts to use browser-safe glob matching
- Update Astro components to split imports: firstMatchingPattern from util.ts
  (server-side only), other utils from browser-utils.ts
- Update all client-side TypeScript to import from browser-utils.ts

This eliminates the "Cannot access path.sep in client code" warnings and
ensures clean browser console output during development.
@Fevol
Copy link
Copy Markdown
Owner

Fevol commented Apr 7, 2026

node:path can be used in the frontmatter component of .astro files without issue, and while I think it isn't a terrible idea to replace micromatch completely for the client, the current implementation does not fully implement the full syntax that picomatch exposes, creating a breaking change for users. I believe solving the dependency issue is a better solution in the long-term.

EDIT: Sorry, I misread the first part of your message. After some more investigation, it is sensible to split up the functionality into browser-utils. Also, instead of fully replacing micromatch on the client-side, I decided that the easiest solution would be to use picomatch. This does sadly come with a regression with the bracket expansion functionality that micromatch offers. While not ideal, I currently do not see a better solution.

@Fevol Fevol closed this Apr 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants