$ npm install @vltpkg/specThis is a library for parsing package specifiers.
Namings · Specifiers · Usage · Properties
Specifiers are primarily used in the following cases:
vlt add foo@1.xpackage.json) where dependencies are listed,
like "dependencies": { "foo": "1.x" }A "named" specifier is one with the full name included, separated from
the specifier by a @ character, such as foo@1.x or
@vltpkg/spec@1.0.0. The name in these cases would be foo and
@vltpkg/spec, respectively.
Note that it does not always correspond to the "name" in the
manifest of the resolved package! For example, foo@npm:react@latest
would resolve to the latest version of react, but would be named
foo in the dependency graph, and loaded as import('foo').
The following specifier types are supported:
workspace:... - Provide a semver range, or one of ~, *, or ^
to match against a dependency that exists in a workspace project of
a monorepo. The package name must exist as a workspace project in
the monorepo. If a semver range is provided, then it must match the
referenced workspace package version. Otherwise:
* - Fill in whatever version is in the workspace, without any
prefix. So, if ./packages/foo depends on bar@workspace*, and
bar is version 1.2.3, then foo will be published with
{ "dependencies": { "bar": "1.2.3" }}~ or ^ - Publish with the version found in the monorepo,
prefixed by the character. So in the example above, it'd be
bar@~1.2.3 or bar@^1.2.3, respectively.semver range - A valid semver range (including the empty string or
a single semver version). This is resolved against the default
registry. If the spec is a valid semver range, then no further
parsing is done.
git+ssh://<url>[selector] or git+https://<url>[selector] - A
git+ssh or git+https url will be checked out by git. If no 'git
selector' is provided, then it will attempt to install from the
default version. The git selector can be:
#committish Any valid committish value will be checked out.
So, shasum, branch, tag, etc., would all work.#semver:<range> If a semver range is provided, it will select
over all the tags that are valid semver versions, and pick the
highest version number that satisfies the range.::-separated series of
key:value pairs. Currently only path:<path in repo> is
supported, for referencing packages living below the root of the
repository, as in a monorepo. For example,
tcompare@github:tapjs/tapjs#bf457f24::path:src/tcomparehttps://some-host.com/path/to/file.tgz - An https or http URL to a
tarball will resolve to itself.
file:///path/to/file - A file URL will resolve to itself. If it is
a directory, it will be reified as a symbolic link to the folder
specified. If it is a file, it will be treated as a tarball that
gets unpacked into place. Relative paths are resolved from the
package with the dependency.
registry:<registry url>#<name>[@version range or dist-tag] - This
will use the specified registry url, and look up the name and
version on that registry.
If a registry shorthand is defined in the options, then you can use
it as an alias for that registry. Currently, the only shorthand that
is enabled by default is npm:<name>[@version-range] as a shorthand
for registry:https://registry.npmjs.org/#<name>[@version-range].
If a git repository shorthand is defined in the options, then you
can use that shorthand prefix as an alias for that git host.
Currently, github:, bitbucket:, gitlab:, and gist: are
supported by default.
Anything else will be treated as a dist-tag in the registry
packument. For example, foo@latest or blah@legacy-v2
import { Spec, type SpecOptions } from '@vltpkg/spec'
// optional: create some registry shorthands
const opts: SpecOptions = {
registries: {
// internal company registry or something
acmereg: 'https://dev.acme.internal/npm',
},
gitHosts: {
github: 'git+ssh://git@github.com:$1/$2',
// the $# pieces here are replaced by the path-separated
// portions, so eg `github:user/project#whatever
acmegit: 'git+ssh://git@dev.acme.internal/git/$1/$2/$3',
}
}
const lodash = Spec.parse('lodash@latest')
// which is the same as:
const lodash = Spec.parse('lodash@npm:lodash@latest')
// which is the same as:
const lodash = Spec.parse(
'lodash@registry:https://registry.npmjs.org/#lodash@latest'
)
// pull from github
const ghProject = Spec.parse('abbrev@github:npm/abbrev-js#main', opts)
// pull from GitHub package registry
const ghPackage = Spec.parse(
'@octocat/hello-world',
'gh:@octocat/hello-world@1.0.0',
opts,
)
// pull from our internal hosts using the acme shorthand names
const fooFromAcmeReg = Spec.parse('foo@acmereg:foo@1.2', opts)
const fooFromAcmeReg = Spec.parse(
'foo@acmegit:department/team/monorepo#main;directory:packages/foo',
opts,
)
'registry', 'git',
'file', 'remote', catalog or workspace.foo in foo@1.x1.x in foo@1.xtype === 'git':
::-separated set of key:value fieldsgitSelector parsed into a Record objectgithub, gitlab, bitbucket, etc.type === 'registry':
npm:x@2.x or
an explicit registry url like
registry:https://registry.npmjs.org#x@2.x.type === 'file':
type === 'remote':