docs: clarify Nushell XDG startup requirements and recovery - #2704
Open
naokihaba wants to merge 4 commits into
Open
docs: clarify Nushell XDG startup requirements and recovery#2704naokihaba wants to merge 4 commits into
naokihaba wants to merge 4 commits into
Conversation
naokihaba
marked this pull request as ready for review
September 14, 2026 18:41
fengmk2
approved these changes
Sep 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
resolves: #2491
Context
Nushell sets up its autoload directories before
config.nuruns. Ifconfig.nuthen changesXDG_DATA_HOMEto 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. IfXDG_DATA_HOMEis 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.nuis 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_HOMEis 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.nuin theirconfig.nu. We have left the installer itself untouched.Integration tests reproduce the mismatch, verify that everything works when
XDG_DATA_HOMEis set before startup, and confirm that sourcing the file allows a fresh session to load Vite+ and runvp help.