Configuration

snpm is configured from three sources, merged in this order (later wins):

1. Built-in defaults.
2. .snpmrc / .npmrc / .pnpmrc from the user's home directory, then each ancestor directory of the current working directory.
3. Environment variables.

Use snpm config to print the resolved configuration at any time.

Environment variables

Directories

Platform defaults:

• macOS: cache ~/Library/Caches/snpm, data ~/Library/Application Support/io.snpm.snpm
• Linux: cache ~/.cache/snpm, data ~/.local/share/snpm
• Windows: cache %LOCALAPPDATA%\snpm\snpm\cache, data %LOCALAPPDATA%\snpm\snpm\data

Derived directories (under the data dir):

• packages/ — shared package store
• metadata/ — registry metadata cache
• virtual-store/ — shared virtual-store entries
• global/ — global installs
• bin/ — global bin shims

Registry and auth

When a token is set via SNPM_AUTH_TOKEN, NODE_AUTH_TOKEN, or NPM_TOKEN, the scheme is Bearer. When set via the _auth variants, it is Basic.

Install behavior

Truthy values: 1, true, yes, y, on. snpm also accepts snpm_config_*, pnpm_config_*, and npm_config_* forms for hoist, link_backend, strict_peer_dependencies, frozen_lockfile, registry_concurrency, and always_auth.

Security

Logging

RC files

snpm reads .snpmrc, .npmrc, and .pnpmrc in this order — home directory first, then ancestor directories of the current working directory. Later files override earlier ones.

# Comments start with # or ;
registry=https://registry.npmjs.org/

# Scoped registries
@myorg:registry=https://npm.myorg.com/

# Auth tokens per host
//npm.myorg.com/:_authToken=${NPM_TOKEN}
//npm.myorg.com/:_auth=dXNlcjpwYXNz

# Default registry auth
_authToken=abc123

# Install behavior
snpm-hoist=single-version
link-backend=hardlink

# Force auth
always-auth=true

# Local virtual store packages
disable-global-virtual-store-for-packages=next,vite

${VAR} / $VAR expansion is supported in .snpmrc and .npmrc style files.

snpm login writes credentials to ~/.snpmrc (falling back to a local .snpmrc if there is no home directory).

Hoisting

export SNPM_HOIST=single-version   # default — only hoist when there is a single version
export SNPM_HOIST=none             # strict isolation, like pnpm's default
export SNPM_HOIST=all              # hoist aggressively, npm-style

Or per workspace:

hoisting: single-version

Link backend

export SNPM_LINK_BACKEND=auto       # default — hardlinks on Unix, copies on Windows
export SNPM_LINK_BACKEND=hardlink   # explicit hardlinks
export SNPM_LINK_BACKEND=symlink    # symlinks (good across filesystems)
export SNPM_LINK_BACKEND=copy       # explicit copy (slowest, most compatible)

Global virtual store compatibility

snpm pools entries across projects in <data_dir>/virtual-store/ so two projects with the same dep closure reuse the same bytes. Some packages must stay project-local — patched packages, packages allowed to run lifecycle scripts, directory-backed file: deps, and tools that walk up parent directories to find configuration.

The default project-local list is next, nuxt, vite, vitepress, parcel. Override it via env var or RC entry:

export SNPM_DISABLE_GLOBAL_VIRTUAL_STORE_FOR_PACKAGES=next,vite,vitepress

disable-global-virtual-store-for-packages=next,vite

Set it to [] to disable the heuristic.

Script policy

Dependency lifecycle scripts (preinstall, install, postinstall) are blocked by default.

export SNPM_ALLOW_SCRIPTS="esbuild,sharp,@swc/core"

Or via the workspace file:

onlyBuiltDependencies:
  - esbuild
  - sharp
ignoredBuiltDependencies:
  - fsevents

Root project and workspace-member lifecycle scripts still run during install. After changing the allow-list, run snpm rebuild to apply the new policy to packages that already extracted.

Minimum package age

Ignore versions published within the last N days. Useful for production CI to dodge zero-day malicious publishes.

export SNPM_MIN_PACKAGE_AGE_DAYS=7

See Security for more.

Catalogs

Workspace-wide dependency versions live in snpm-catalog.yaml and/or the catalog/catalogs blocks in snpm-workspace.yaml. See Catalog.

Overrides

Force specific transitive dependency versions via snpm-overrides.yaml or package.json:

overrides:
  lodash: ^4.17.21
  "@babel/core": ^7.23.0

{
  "snpm": {
    "overrides": { "lodash": "^4.17.21" }
  },
  "pnpm": {
    "overrides": { "axios": "^1.6.0" }
  }
}

snpm reads both snpm.overrides and pnpm.overrides for compatibility.

Bundled dependencies

bundledDependencies (or bundleDependencies) in package.json are honored. snpm respects the bundled versions for that package and prevents store pollution by keeping bundled copies project-local.

{
  "bundledDependencies": ["fsevents", "node-gyp"]
}

Inspecting the resolved config

Run snpm config to print resolved paths, registry/auth, install settings (hoisting, link backend, local virtual store packages, strict peers, frozen lockfile default, min package age, registry concurrency, always-auth), allow-scripts list, and logging configuration.

Common configurations

Development

export SNPM_REGISTRY_CONCURRENCY=128
unset SNPM_MIN_PACKAGE_AGE_DAYS

Production / CI

export SNPM_MIN_PACKAGE_AGE_DAYS=7
export SNPM_FROZEN_LOCKFILE=1
export SNPM_ALLOW_SCRIPTS="esbuild,sharp"
snpm install --frozen-lockfile

Private registry

export SNPM_CONFIG_REGISTRY=https://npm.mycompany.com
export NODE_AUTH_TOKEN=$MY_TOKEN

Or via login:

snpm login --registry https://npm.mycompany.com
snpm login --scope @myorg --registry https://npm.mycompany.com