Skip to content

docs: clarify Nushell XDG startup requirements and recovery - #2704

Open
naokihaba wants to merge 4 commits into
voidzero-dev:mainfrom
naokihaba:test/nushell-xdg-autoload-mismatch
Open

docs: clarify Nushell XDG startup requirements and recovery#2704
naokihaba wants to merge 4 commits into
voidzero-dev:mainfrom
naokihaba:test/nushell-xdg-autoload-mismatch

Conversation

@naokihaba

@naokihaba naokihaba commented Sep 14, 2026

Copy link
Copy Markdown
Collaborator

resolves: #2491

Context

Nushell sets up its autoload directories before config.nu runs. If config.nu then changes XDG_DATA_HOME to a different location, the Vite+ installer picks up the new path and writes its snippet to a directory that fresh sessions launched from the original parent environment will not load. If XDG_DATA_HOME is never set, this is not an issue.

This setup does not meet Nushell's documented startup requirement, which states that directory-related XDG variables must be set before Nushell launches. While assigning them in config.nu is valid, it only affects child processes and will not update the autoload paths already resolved for the current session.

As described in the investigation results, we reproduced the mismatch on macOS with Nushell 0.115.1. Passing the original autoload path explicitly would require changing how the installer is invoked, switching to user autoload only addresses part of the problem, and warning whenever XDG_DATA_HOME is set would be noisy for correctly configured users.

Based on those findings, this PR updates the Getting Started guide by documenting the startup requirement and outlining a workaround for affected users, who can manually source Vite+'s env.nu in their config.nu. We have left the installer itself untouched.

Integration tests reproduce the mismatch, verify that everything works when XDG_DATA_HOME is set before startup, and confirm that sourcing the file allows a fresh session to load Vite+ and run vp help.

@naokihaba naokihaba self-assigned this Sep 14, 2026
@naokihaba naokihaba changed the title test: reproduce Nushell autoload mismatch with config-time XDG settings docs: clarify Nushell XDG startup requirements and recovery Sep 14, 2026
@naokihaba
naokihaba marked this pull request as ready for review September 14, 2026 18:41
@naokihaba
naokihaba requested a review from fengmk2 September 14, 2026 18:41
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.

Handle Nushell vendor autoload mismatch when XDG variables are set in config.nu

2 participants