@bobfrankston/userconfig

Single source of truth for user-level npm/dev configuration at %USERPROFILE%\.userconfig\npm.json5.

Critical Path Rule

Do not duplicate, infer, or reconstruct the user config directory path in consuming tools. The only supported way for code outside this package to get the user config directory or config file path is through the @bobfrankston/userconfig API (configDir, configPath, or a future exported helper).

The physical path shown in this README describes the current implementation. It is not permission for applications to hardcode %USERPROFILE%\.userconfig, os.homedir(), $HOME, or any equivalent. Path policy belongs here so it can be changed in one place.

Used by @bobfrankston/npmglobalize, @bobfrankston/reloc, and other tools.

Planned changes are listed in TODO.md.

Install

npm install @bobfrankston/userconfig

Config file

npm.json5 has two kinds of entries:

• Common fields — shared across tools (scope, npmVisibility)
• App sections — tool-specific settings (reloc, etc.)

{
  // ─── Common fields ───
  scope: "@bobfrankston",       // npm scope for publishing
  npmVisibility: "public",      // default publish visibility: "public" or "private"

  // ─── App-specific sections ───
  reloc: {
    dirs: ["y:\\dev\\homecontrol", "y:\\dev\\projects"],
  },
}

Common fields

| Field | Type | Description | |---|---|---| | scope | string | npm scope, e.g. "@bobfrankston" | | npmVisibility | "public" | "private" | Default publish visibility |

App sections

| Section | Tool | Fields | |---|---|---| | reloc | @bobfrankston/reloc | dirs — default scan directories |

New tools can add their own sections without conflicting.

Usage

import { readConfig, getSection, setSection, configPath } from '@bobfrankston/userconfig';

// Read common fields
const config = readConfig();
console.log(config.scope);          // "@bobfrankston"
console.log(config.npmVisibility);  // "public"

// Read an app section
const reloc = getSection('reloc');
console.log(reloc?.dirs);

// Write an app section (preserves everything else)
setSection('reloc', { dirs: ['y:\\dev\\homecontrol'] });

// Low-level: read any JSON5-ish file
import { readJson5, writeJson5 } from '@bobfrankston/userconfig';
const data = readJson5('/path/to/file.json5');

API

| Export | Description | |---|---| | configDir | %USERPROFILE%\.userconfig | | configPath | %USERPROFILE%\.userconfig\npm.json5 | | readConfig() | Read the full config (typed as NpmConfig) | | writeConfig(data) | Write the full config | | getSection(name) | Get a top-level key | | setSection(name, value) | Set a top-level key (preserves others) | | readJson5(file) | Parse any JSON5-ish file | | writeJson5(file, data) | Write JSON to a file (creates dirs) |

Types

interface NpmCommonConfig {
    scope?: string;
    npmVisibility?: 'public' | 'private';
}

interface RelocConfig {
    dirs?: string[];
}

interface NpmConfig extends NpmCommonConfig {
    reloc?: RelocConfig;
    [key: string]: any;  // other app sections
}