vlt / docs

    • PricingBenchmarks (opens in new window)Community (opens in new window)Feedback
  • Overview
    • Overview
    • config
    • index
    • Reference
    • view
  • Classes
  • Config
  • Type Aliases
  • ConfigData
  • ConfigDataNoCommand
  • ConfigDefinitions
  • ConfigFileData
  • ConfigFileDataNoCommand
  • ConfigFileLayer
  • ConfigOptions
  • ConfigOptionsNoExtras
  • LoadedConfig
  • OptListKeys<O>
  • PairsAsRecords
  • ParsedConfig
  • RecordPairs
  • RecordString
  • StringListKeys<O>
  • Variables
  • kCustomInspect
  • Functions
  • assertRegistryKeys()
  • configWriteTarget()
  • pairsToRecords()
  • recordsToPairs()
  • References
  • commands
  • Commands
  • definition
  • isRecordField
  • recordFields
  1. Client
  2. /
  3. API Reference
  4. /
  5. @vltpkg/cli-sdk
  6. /
  7. config

config

Module that handles all vlt configuration needs

Project-level configs are set in a vlt.json file in the local project if present, and are layered over the user-level configs in the appropriate XDG config path. See ./merge-layers.ts for the layering rules.

Command-specific configuration can be specified by putting options in a field in the command object. For example:

JSON
{
  "registry": "https://registry.npmjs.org/",
  "command": {
    "publish": {
      "registry": "http://registry.internal"
    }
  }
}

Classes

Config

Defined in: src/cli-sdk/src/config/index.ts:298

Class that handles configuration for vlt.

Call Config.load to get one of these.

Constructors

new Config()
TypeScript
new Config(jack, projectRoot): Config

Defined in: src/cli-sdk/src/config/index.ts:430

Parameters
ParameterTypeDefault value
jackJack<…>definition
projectRootstring...
Returns

Config

Properties

PropertyTypeDefault valueDescription
command?| "version" | "registry" | "cache" | "config" | "query" | "help" | "access" | "bugs" | "build" | "ci" | "create" | "deprecate" | "dist-tag" | "docs" | "exec" | "exec-local" | "init" | "install" | "login" | "logout" | "list" | "pack" | "ping" | "pkg" | "profile" | "publish" | "repo" | "run-exec" | "run" | "setup" | "token" | "uninstall" | "unpublish" | "update" | "exec-cache" | "view" | "whoami"undefinedWhich command name to use for overriding with command-specific values, determined from the argv when parse() is called.
commandsobjectundefinedRecord<alias, canonical name> to dereference command aliases.
commands.?"help"'help'-
commands.access"access"'access'-
commands.add"install"'install'-
commands.b"build"'build'-
commands.bugs"bugs"'bugs'-
commands.build"build"'build'-
commands.cache"cache"'cache'-
commands.ci"ci"'ci'-
commands.config"config"'config'-
commands.create"create"'create'-
commands.deprecate"deprecate"'deprecate'-
commands.dist-tag"dist-tag"'dist-tag'-
commands.docs"docs"'docs'-
commands.exec"exec"'exec'-
commands.exec-cache"exec-cache"'exec-cache'-
commands.exec-local"exec-local"'exec-local'-
commands.h"help"'help'-
commands.help"help"'help'-
commands.i"install"'install'-
commands.info"view"'view'-
commands.init"init"'init'-
commands.install"install"'install'-
commands.list"list"'list'-
commands.login"login"'login'-
commands.logout"logout"'logout'-
commands.ls"list"'list'-
commands.p"pkg"'pkg'-
commands.pack"pack"'pack'-
commands.ping"ping"'ping'-
commands.pkg"pkg"'pkg'-
commands.profile"profile"'profile'-
commands.pub"publish"'publish'-
commands.publish"publish"'publish'-
commands.q"query"'query'-
commands.query"query"'query'-
commands.r"run"'run'-
commands.registry"registry"'registry'-
commands.repo"repo"'repo'-
commands.rm"uninstall"'uninstall'-
commands.run"run"'run'-
commands.run-exec"run-exec"'run-exec'-
commands.run-script"run"'run'-
commands.rx"run-exec"'run-exec'-
commands.setup"setup"'setup'-
commands.show"view"'view'-
commands.token"token"'token'-
commands.u"update"'update'-
commands.uninstall"uninstall"'uninstall'-
commands.unpublish"unpublish"'unpublish'-
commands.update"update"'update'-
commands.version"version"'version'-
commands.view"view"'view'-
commands.whoami"whoami"'whoami'-
commands.x"exec"'exec'-
commands.xc"exec-cache"'exec-cache'-
commands.xl"exec-local"'exec-local'-
commandValuesobject{}Command-specific config values
commandValues.access?ConfigDataundefined-
commandValues.bugs?ConfigDataundefined-
commandValues.build?ConfigDataundefined-
commandValues.cache?ConfigDataundefined-
commandValues.ci?ConfigDataundefined-
commandValues.config?ConfigDataundefined-
commandValues.create?ConfigDataundefined-
commandValues.deprecate?ConfigDataundefined-
commandValues.dist-tag?ConfigDataundefined-
commandValues.docs?ConfigDataundefined-
commandValues.exec?ConfigDataundefined-
commandValues.exec-cache?ConfigDataundefined-
commandValues.exec-local?ConfigDataundefined-
commandValues.help?ConfigDataundefined-
commandValues.init?ConfigDataundefined-
commandValues.install?ConfigDataundefined-
commandValues.list?ConfigDataundefined-
commandValues.login?ConfigDataundefined-
commandValues.logout?ConfigDataundefined-
commandValues.pack?ConfigDataundefined-
commandValues.ping?ConfigDataundefined-
commandValues.pkg?ConfigDataundefined-
commandValues.profile?ConfigDataundefined-
commandValues.publish?ConfigDataundefined-
commandValues.query?ConfigDataundefined-
commandValues.registry?ConfigDataundefined-
commandValues.repo?ConfigDataundefined-
commandValues.run?ConfigDataundefined-
commandValues.run-exec?ConfigDataundefined-
commandValues.setup?ConfigDataundefined-
commandValues.token?ConfigDataundefined-
commandValues.uninstall?ConfigDataundefined-
commandValues.unpublish?ConfigDataundefined-
commandValues.update?ConfigDataundefined-
commandValues.version?ConfigDataundefined-
commandValues.view?ConfigDataundefined-
commandValues.whoami?ConfigDataundefined-
explicitConfigData{}Values set on the command line or via VLT_* env for this run. Record fields hold only those key=value pairs, not the ones from config files. VLT_* env left as a parent vlt process wrote it only counts for what was explicit in that parent.
jackJack<…>undefinedThe JackSpeak object representing vlt's configuration
positionals?string[]undefinedpositional arguments to the vlt process
projectRootstringundefinedThe root of the project where a vlt.json, vlt.json, package.json, or .git was found. Not necessarily the process.cwd(), though that is the default location. Never walks up as far as $HOME. So for example, if a project is in ~/projects/xyz, then the highest dir it will check is ~/projects
values?OptionsResults<…>undefinedParsed values in effect

Accessors

layers
Get Signature
TypeScript
get layers(): Readonly<{
  project: Partial<PairsAsRecords>;
  user: Partial<PairsAsRecords>;
}>

Defined in: src/cli-sdk/src/config/index.ts:733

The raw config data from each vlt.json file, normalized to record form, before the layers are merged together. undefined for a layer with no file, or a file with no config field.

Returns

Readonly<{ project: Partial<PairsAsRecords>; user: Partial<PairsAsRecords>; }>

options
Get Signature
TypeScript
get options(): ConfigOptions

Defined in: src/cli-sdk/src/config/index.ts:320

A flattened object of the parsed configuration

Returns

ConfigOptions

Methods

addConfigToFile()
TypeScript
addConfigToFile(
   this, 
   which, 
values): Promise<void>

Defined in: src/cli-sdk/src/config/index.ts:651

Fold in the provided fields with the existing properties in the config file.

Parameters
ParameterType
thisParsedConfig
whichWhichConfig
valuesNonNullable<ConfigFileData>
Returns

Promise<void>

deleteConfigKeys()
TypeScript
deleteConfigKeys(
   this, 
   which, 
fields): Promise<boolean>

Defined in: src/cli-sdk/src/config/index.ts:794

Deletes the specified config fields from the named file Returns true if anything was changed.

Parameters
ParameterType
thisParsedConfig
whichWhichConfig
fieldsstring[]
Returns

Promise<boolean>

editConfigFile()
TypeScript
editConfigFile(
   this, 
   which, 
edit): Promise<void>

Defined in: src/cli-sdk/src/config/index.ts:847

Edit the user or project configuration file.

If the file isn't present, then it starts with {} so the user has something to work with.

If the result is not valid, or no config settings are contained in the file after editing, then it's restored to what it was before, which might mean deleting the file.

Parameters
ParameterType
thisParsedConfig
whichWhichConfig
edit(file) => void | Promise<void>
Returns

Promise<void>

get()
TypeScript
get<K>(k): OptionsResults<…>[K]

Defined in: src/cli-sdk/src/config/index.ts:628

Get a configuration value.

Note: key=value pair configs are returned as a string array. To get them as an object, use Config#getRecord.

Type Parameters
Type Parameter
K extends | "version" | "color" | "no-color" | "registry" | "default-registry-alias" | "registries" | "scoped-registries" | "jsr-registries" | "git-hosts" | "git-host-archives" | "cache" | "config" | "store-linker" | "tag" | "before" | "os" | "arch" | "libc" | "node-version" | "git-shallow" | "fetch-retries" | "fetch-retry-factor" | "fetch-retry-mintimeout" | "fetch-retry-maxtimeout" | "stale-while-revalidate-factor" | "identity" | "workspace" | "workspace-group" | "scope" | "target" | "if-present" | "recursive" | "bail" | "no-bail" | "all" | "editor" | "script-shell" | "fallback-command" | "help" | "access" | "view" | "package" | "call" | "loglevel" | "verbose" | "dashboard-root" | "save-dev" | "save-exact" | "save-optional" | "save-peer" | "save-prod" | "save-config" | "save-prefix" | "expect-results" | "dry-run" | "force" | "expect-lockfile" | "frozen-lockfile" | "lockfile-only" | "allow-scripts" | "git-tag-version" | "commit" | "otp" | "publish-directory" | "telemetry" | "yes"
Parameters
ParameterType
kK
Returns

OptionsResults<…>[K]

getRecord()
TypeScript
getRecord(k): RecordString

Defined in: src/cli-sdk/src/config/index.ts:604

Get a key=value list option value as an object.

For example, a list option with a vlaue of ['key=value', 'xyz=as=df' ] would be returned as {key: 'value', xyz: 'as=df'}

Results are memoized, so subsequent calls for the same key will return the same object. If new strings are added to the list, then the memoized value is not updated, so only use once configurations have been fully loaded.

If the config value is not set at all, an empty object is returned.

Parameters
ParameterType
k| "registries" | "scoped-registries" | "jsr-registries" | "git-hosts" | "git-host-archives" | "workspace" | "workspace-group" | "dashboard-root"
Returns

RecordString

loadConfigFile()
TypeScript
loadConfigFile(): Promise<Config>

Defined in: src/cli-sdk/src/config/index.ts:889

Find the local config file and load both it and the user-level config in the XDG config home.

Returns

Promise<Config>

parse()
TypeScript
parse(args): Config & object

Defined in: src/cli-sdk/src/config/index.ts:442

Parse the arguments and set configuration and positionals accordingly.

Parameters
ParameterTypeDefault value
argsstring[]process.argv
Returns

Config & object

reloadFromDisk()
TypeScript
reloadFromDisk(): Promise<void>

Defined in: src/cli-sdk/src/config/index.ts:910

Force a complete reload of config files from disk. This clears all caches and re-reads config files. Useful for long-running processes that need to pick up config changes.

Returns

Promise<void>

resetOptions()
TypeScript
resetOptions(projectRoot): void

Defined in: src/cli-sdk/src/config/index.ts:389

Reset the options value, optionally setting a new project root to recalculate the options.

Parameters
ParameterType
projectRootstring
Returns

void

writeConfigFile()
TypeScript
writeConfigFile(
   this, 
   which, 
values): Promise<void>

Defined in: src/cli-sdk/src/config/index.ts:638

Write the config values to the user or project config file.

Parameters
ParameterType
thisParsedConfig
whichWhichConfig
valuesNonNullable<ConfigFileData>
Returns

Promise<void>

load()
TypeScript
static load(projectRoot, argv): Promise<ParsedConfig>

Defined in: src/cli-sdk/src/config/index.ts:944

Load the configuration and return a Promise to a Config object

Parameters
ParameterTypeDefault value
projectRootstring...
argvstring[]process.argv
Returns

Promise<ParsedConfig>

Type Aliases

ConfigData

TypeScript
type ConfigData = ConfigDataNoCommand & object;

Defined in: src/cli-sdk/src/config/index.ts:236

Config data can be any options, and also a 'command' field which contains command names and override options for that command.

Type declaration

NameType
command?{ [k in keyof Commands]?: ConfigDataNoCommand }

ConfigDataNoCommand

TypeScript
type ConfigDataNoCommand = { [k in keyof OptionsResults<ConfigDefinitions>]?: OptionsResults<ConfigDefinitions>[k] };

Defined in: src/cli-sdk/src/config/index.ts:226

ConfigDefinitions

TypeScript
type ConfigDefinitions = Unwrap<typeof definition>;

Defined in: src/cli-sdk/src/config/index.ts:283

The base config definition set as a type

ConfigFileData

TypeScript
type ConfigFileData = ConfigFileDataNoCommand & object;

Defined in: src/cli-sdk/src/config/index.ts:254

Config data as it appears in the config field of the vlt.json, with kv pair lists stored as Record<string, string> and

Type declaration

NameType
command?{ [k in keyof Commands]?: ConfigFileDataNoCommand }

ConfigFileDataNoCommand

TypeScript
type ConfigFileDataNoCommand = { [k in keyof ConfigDataNoCommand]: k extends OptListKeys<ConfigDataNoCommand> ? RecordString | string[] : ConfigDataNoCommand[k] };

Defined in: src/cli-sdk/src/config/index.ts:242

ConfigFileLayer

TypeScript
type ConfigFileLayer = Partial<PairsAsRecords>;

Defined in: src/cli-sdk/src/config/index.ts:101

One vlt.json file's config object, in record form. Every field is optional, since a config file only sets what it sets.

ConfigOptions

TypeScript
type ConfigOptions = ConfigOptionsNoExtras & Pick<SpecOptions, "catalog" | "catalogs"> & object;

Defined in: src/cli-sdk/src/config/index.ts:269

Type declaration

NameTypeDescription
monorepo?Monorepo-
packageInfoPackageInfoClient-
packageJsonPackageJson-
projectRootstring-
scurryPathScurry-
storeRootstringglobal store root, under cache

ConfigOptionsNoExtras

TypeScript
type ConfigOptionsNoExtras = { [k in keyof OptionsResults<ConfigDefinitions>]: k extends RecordField ? RecordString : k extends "command" ? never : OptionsResults<ConfigDefinitions>[k] };

Defined in: src/cli-sdk/src/config/index.ts:260

LoadedConfig

TypeScript
type LoadedConfig = ParsedConfig;

Defined in: src/cli-sdk/src/config/index.ts:973

A fully loaded Config object

OptListKeys<O>

TypeScript
type OptListKeys<O> = Exclude<StringListKeys<O>[keyof StringListKeys<O>], undefined>;

Defined in: src/cli-sdk/src/config/index.ts:288

Type Parameters

Type Parameter
O

PairsAsRecords

TypeScript
type PairsAsRecords = ConfigOptionsNoExtras & object;

Defined in: src/cli-sdk/src/config/index.ts:91

Type declaration

NameType
command?{ [k in keyof Commands]?: ConfigOptionsNoExtras }

ParsedConfig

TypeScript
type ParsedConfig = Config & object;

Defined in: src/cli-sdk/src/config/index.ts:964

Type declaration

NameType
commandNonNullable<Config["command"]>
positionalsstring[]
valuesOptionsResults<ConfigDefinitions>

RecordPairs

TypeScript
type RecordPairs = Record<string, unknown>;

Defined in: src/cli-sdk/src/config/index.ts:66

RecordString

TypeScript
type RecordString = Record<string, string>;

Defined in: src/cli-sdk/src/config/index.ts:67

StringListKeys<O>

TypeScript
type StringListKeys<O> = { [k in keyof O]: O[k] extends string[] | undefined ? k : never };

Defined in: src/cli-sdk/src/config/index.ts:285

Type Parameters

Type Parameter
O

Variables

kCustomInspect

TypeScript
const kCustomInspect: typeof kCustomInspect;

Defined in: src/cli-sdk/src/config/index.ts:64

Functions

assertRegistryKeys()

TypeScript
function assertRegistryKeys(registries, file): void

Defined in: src/cli-sdk/src/config/index.ts:107

registries alias names are used as spec prefixes, where ~ is reserved, and an empty name has nothing to prefix with.

Parameters

ParameterType
registriesunknown
filestring

Returns

void

configWriteTarget()

TypeScript
function configWriteTarget(conf, fallback): WhichConfig

Defined in: src/cli-sdk/src/config/index.ts:982

Which vlt.json a command that persists settings should write to.

--config=user and --config=project are explicit. Anything else means the caller's own default, since --config also takes all (its default, meaningful only for vlt config reads).

Parameters

ParameterType
confPick<ParsedConfig, "get">
fallbackWhichConfig

Returns

WhichConfig

pairsToRecords()

TypeScript
function pairsToRecords(obj): PairsAsRecords

Defined in: src/cli-sdk/src/config/index.ts:127

Parameters

ParameterType
obj| OptionsResults<…> | NonNullable<ConfigFileData>

Returns

PairsAsRecords

recordsToPairs()

TypeScript
function recordsToPairs(obj): RecordPairs

Defined in: src/cli-sdk/src/config/index.ts:148

Parameters

ParameterType
objRecordPairs

Returns

RecordPairs

References

commands

Re-exports commands

Commands

Re-exports Commands

definition

Re-exports definition

isRecordField

Re-exports isRecordField

recordFields

Re-exports recordFields

Previous@vltpkg/cli-sdkNextindex

On this page

  • Classes
  • Config
  • Type Aliases
  • ConfigData
  • ConfigDataNoCommand
  • ConfigDefinitions
  • ConfigFileData
  • ConfigFileDataNoCommand
  • ConfigFileLayer
  • ConfigOptions
  • ConfigOptionsNoExtras
  • LoadedConfig
  • OptListKeys<O>
  • PairsAsRecords
  • ParsedConfig
  • RecordPairs
  • RecordString
  • StringListKeys<O>
  • Variables
  • kCustomInspect
  • Functions
  • assertRegistryKeys()
  • configWriteTarget()
  • pairsToRecords()
  • recordsToPairs()
  • References
  • commands
  • Commands
  • definition
  • isRecordField
  • recordFields

Deploy your package on vlt.io

Publish scoped and private packages, manage organizations and access, and give every developer and CI environment a consistent source for public and private JavaScript dependencies.

Publish now