[Feature Request]: Follow XDG Base Directory Specification

[jtrv]

What is the problem this feature would solve?

The .bun/ directory unnecessarily pollute users' $HOME directory. Related: #696, #965

What is the feature you are proposing to solve the problem?

The XDGBDS defines where these files should be placed with environment variables to avoid polluting the $HOME directory.

From the XDGBDS:

The XDG Base Directory Specification is based on the following concepts:

• There is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME.

• There is a single base directory relative to which user-specific configuration files should be written. This directory is defined by the environment variable $XDG_CONFIG_HOME.

• There is a single base directory relative to which user-specific state data should be written. This directory is defined by the environment variable $XDG_STATE_HOME.

• There is a single base directory relative to which user-specific executable files may be written.

• There is a single base directory relative to which user-specific non-essential (cached) data should be written. This directory is defined by the environment variable $XDG_CACHE_HOME.

User-specific executable files may be stored in $HOME/.local/bin.

Implementing XDGBDS would work as follows:

IF a corresponding XDG environment variable exists THEN use it's location according to the spec.

ELSE use the current behavior / locations in the .bun/ directory.

What alternatives have you considered?

The alternative is to let all programs arbitrarily use the $HOME directory and create their own structure and organization for cache, data, config, etc. This is not optimal for any system with more than a few programs installed, which is why the XDGBDS exists to keep your system organized and easily navigable.

[ju1ius]

IF a corresponding XDG environment variable exists THEN use it's location according to the spec. ELSE use the current behavior / locations in the .bun/ directory.

FWIW, this is not how this is not exactly how the XDG base-dir spec works. If an XDG_* env var is not defined, the program must fallback to the specified defaults:

env	fallback
XDG_DATA_HOME	~/.local/share
XDG_CONFIG_HOME	~/.config
XDG_STATE_HOME	~/.local/state
XDG_CACHE_HOME	~/.cache

So the directory layout mapping should look like the following:

current	xdg compliant
~/.bun/bin/bun	~/.local/bin/bun
~/.bun/install/cache	~/.cache/bun
~/.bun/install/global/node_modules	~/.local/lib/node_modules
~/.bun/install/global/package.json	~/.config/bun/package.json
~/.bun/install/global/bun.lockb	~/.config/bun/bun.lockb

In addition, globally installed modules should go in ~/.local/lib/node_modules, with binaries symlinked under ~/.local/bin (which is what npm does atm).

[jtrv]

Good catch! I would also add that since the project is not yet 1.0, it's important to implement these breaking changes sooner or schedule them before 1.0 to mitigate the impact to the early adopters who can expect to see these sorts of breaking changes.

[jtrv]

I noticed the banner for 1.0 launching September 7th, very cool! However I wanted to re-emphasize that adherence to XDGBDS should probably happen before or in 1.0 to avoid delaying the breaking changes to a future X.0 release and impacting a larger audience or other projects that might use the .bun directory. It will also likely grow in complexity to replace the .bun directory as more code relying on it gets merged.

[lgarron]

FWIW, this is not how this is not exactly how the XDG base-dir spec works. If an XDG_* env var is not defined, the program must fallback to the specified defaults:

Just another note on this: bun currently uses a folder with a dot prefix even when placing it inside an XDG var folder.

For example, https://github.com/oven-sh/bun/blob/b93f304c063698ada698eddc4321c5c7010e5e5d/src/install/install.zig uses $XDG_CACHE_HOME/.bun instead of $XDG_CACHE_HOME/bun.

This is unusual, in that I have yet to see see any other program use a . prefix for folders inside the XDG convention folders. This may cause the folder to be unexpectedly hidden when viewing it in a file explorer app or running ls without -a. (That is, someone may expect ~/.cache to be hidden — but that all folders are visible once they are viewing that hidden folder.)

I personally show all hidden files and folder, so this is not really an issue for me, but I think it's an opportunity to reduce the potential for surprise if these paths are revisited.

[booniepepper]

I incorporated a change by @lgarron and also added to it in my PR. There was another place $HOME was being referenced, and some deviation from falling back to .cache if $XDG_CACHE_HOME is unset

Edit: After catching up a bit, I think my proposed change is not a hard breaking change. It would invalidate some peoples' cache (because the cache would move) but I think it doesn't break anything critical. It's definitely looking like the kinda thing that's better to do sooner than later

[booniepepper]

Based on some comments from @lgarron it seems like:

1. My change may not be the only place to update; the Zig layer might not be the only layer of implementation that might need to know about directory locations
2. We should also consider following other OS standards when on a non-Linux OS. Mac/Windows have different conventions for where to put stuff.
   • There's a pretty fantastic Rust library called directories that documents recommended locations in its README and has a good model for where things should go

[ZerdoX-x]

Workaround for anyone trying to defend their $HOME:

1. set env BUN_INSTALL to ${XDG_STATE_HOME}/bun (replace with ${HOME}/.local/share if it is not set)
2. source new profile, login again, etc, depending on how you set your env variables
3. install bun via script as usual
4. do not forget to add ${BUN_INSTALL}/bin to your PATH env variable

Result:

$ curl -fsSL https://bun.sh/install | bash
bun was installed successfully to ~/.local/share/bun/bin/bun

[ZerdoX-x]

@jtrv (OP)

Implementing XDGBDS would work as follows:

IF a corresponding XDG environment variable exists THEN use it's location according to the spec. ELSE use the current behavior / locations in the .bun/ directory.

Disagree with you as this behavior is still not specs compliant. Programs should use user's XDG envs if they are set and fall back to default values when they are not set. Program can still use user's $HOME dot dir if it exists, but only for backwards compatibility and this is not about spec itself at all.

This behavior I am talking about is described in document you are sourcing:

$XDG_DATA_HOME defines the base directory relative to which user-specific data files should be stored. If $XDG_DATA_HOME is either not set or empty, a default equal to $HOME/.local/share should be used.

Could you please update description of the issue according to the spec?

Software must not force users to define environment variables in order to keep their $HOME clean. And AFAIK these env variables are not even set in most distributions, so if it's going to be implemented this way, it will affect only really small percentage of Linux/BSD users, and only users who care and know about spec, and try to force apps to follow it. This is very important.

---

It's sad bun did not included this in 1.0 as now it's not as easy to implement with backward compatibility support. There are a lot of examples projects adopting XDG specs with backwards compatibility, you can see "Supported" tables on this page: https://wiki.archlinux.org/title/XDG_Base_Directory#Supported There are also links with discussions and version/commit which implemented spec, it may be useful for anyone who decides to contribute on this.

[jtrv]

@ZerdoX-x thank you, I've updated the issue per ju1ius's comment as well

[M4rti21]

I'm trying to shed light on this issue! Has there been any work towards this?