usher-xdg

Suggest paths for where to save what, trying to follow OS-specific conventions.

Usage no npm install needed!

<script type="module">
  import usherXdg from 'https://cdn.skypack.dev/usher-xdg';
</script>

README



usher-xdg

Suggest paths for where to save what, trying to follow OS-specific conventions.

Usher suggests directories where to put stuff, to help you house-train your programs.

There were previous attempts like mwilliamson's xdg module or leedm777's appdirs.js (based on Python appdirs), but none supported all the directory roles that I'd want to use.

Features

Basic self-awareness:

  • ☑ Expose appMainFile
  • ☑ Expose binDir
  • ☑ Guess appDir (what people often mean when they write __dirname)
  • ☑ Guess userHome
  • ☑ Guess appName
  • ☑ Guess safeAppName (hyphenize unusual characters)

The usual suspects:

Scope → user… roam… site…
…DataDir ☑ ◪ ☑
…ConfigDir ☑ ◪ ☑
…CacheDir ☑ – ◪
…StateDir ◪ – ◪
…LogsDir ☑ ◪ ◪

Standards awareness:

Reliability:

  • ☐ Fallbacks for environments where usher has no clue

Sugar:

  • ☑ Join XDG path lists with colons when used as strings
  • ☐ Function to auto-create the suggested directory

Clues

Good to know

  • Why should I use appDir instead of __dirname?

    The latter is defined as the directory of the "currently executing script", which is no difference as long as your application is just some single JavaScript file in the base directory.

    However, as soon as you divide it into subdirectories like /bin and /lib, that

    webPub = __dirname + '/static';

    will probably break. It gets worse when you try to extract that code into a plugin and suddenly some of those __dirname relate to the plugin's hierarchy while others are meant to relate to the application that uses the plugin.

    Therefor, do future refactorers (probably: you yourself in a few months) a favor and use an expression that works independent of the call site and clearly conveys the real intention, so readers don't have to guess whether it was an accident and instead see that you knew what you were doing.

 

License

ISC