Configuration

Configure snpm's behavior through environment variables and configuration files.

Environment Variables

snpm can be configured using environment variables:

Variable	Description	Default
`SNPM_HOME`	Custom home directory for cache and data	Platform-specific
`SNPM_REGISTRY`	Default registry URL	`https://registry.npmjs.org`
`NPM_CONFIG_REGISTRY`, `npm_config_registry`	Alternative registry URL (npm compatibility)	-
`SNPM_MIN_PACKAGE_AGE_DAYS`	Minimum package age in days (security)	`0`
`SNPM_MIN_PACKAGE_CACHE_AGE_DAYS`	Metadata cache age in days	`7`
`SNPM_HOIST`	Hoisting mode: `none`, `single-version`, `all`	`single-version`
`SNPM_LINK_BACKEND`	Link strategy: `auto`, `hardlink`, `symlink`, `copy`	`auto`
`SNPM_STRICT_PEERS`	Fail on peer dependency conflicts	`false`
`SNPM_FROZEN_LOCKFILE`	Default frozen lockfile mode	`false`
`SNPM_REGISTRY_CONCURRENCY`	Max concurrent registry requests	`64`
`SNPM_ALLOW_SCRIPTS`	Comma-separated list of packages allowed to run install scripts	-
`SNPM_VERBOSE`	Enable verbose logging	`false`
`SNPM_LOG_FILE`	Custom log file path	`.snpm.log`
`NPM_TOKEN`, `SNPM_AUTH_TOKEN`, `NODE_AUTH_TOKEN`	Registry authentication token (Bearer scheme)	-

Examples:

# Use custom home directory
export SNPM_HOME=/custom/snpm

# Use custom registry
export SNPM_REGISTRY=https://npm.mycompany.com

# Set minimum package age (security feature)
export SNPM_MIN_PACKAGE_AGE_DAYS=7

# Set metadata cache age
export SNPM_MIN_PACKAGE_CACHE_AGE_DAYS=14

# Configure hoisting
export SNPM_HOIST=single-version  # or 'none', 'all'

# Set link backend
export SNPM_LINK_BACKEND=hardlink  # or 'symlink', 'copy', 'auto'

# Enable strict peer dependencies
export SNPM_STRICT_PEERS=true

# Set default frozen lockfile mode
export SNPM_FROZEN_LOCKFILE=true

# Increase registry concurrency
export SNPM_REGISTRY_CONCURRENCY=128

# Allow specific packages to run install scripts
export SNPM_ALLOW_SCRIPTS="puppeteer,esbuild,@swc/core"

# Enable verbose logging
export SNPM_VERBOSE=true

# Custom log file location
export SNPM_LOG_FILE=/var/log/snpm/install.log

Registry Configuration

Default Registry

export SNPM_REGISTRY=https://registry.npmjs.org

Private Registry

export SNPM_REGISTRY=https://npm.mycompany.com  # URL must include protocol; trailing slashes are normalized
export NPM_TOKEN=your-token-here                # Auth tokens use Bearer scheme

Or use the login command:

snpm login --registry https://npm.mycompany.com  # Web/basic credentials are exchanged for a Bearer token; URL normalization applied

Scoped Registries

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

Store Configuration

The global store caches downloaded packages for reuse across projects.

Default Location:

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

Custom Location:

# Set custom home directory (contains both cache and data)
export SNPM_HOME=/custom/snpm
# This creates /custom/snpm/cache and /custom/snpm/data

Security Configuration

Minimum Version Age

Protect against zero-day malicious packages by ignoring recently published versions:

export SNPM_MIN_PACKAGE_AGE_DAYS=7

This makes snpm ignore any package version published within the last 7 days.

This is a unique security feature that helps protect against supply chain attacks.

Network Configuration

Registry Concurrency

Control how many concurrent registry requests are made:

export SNPM_REGISTRY_CONCURRENCY=128

Higher values speed up installs but use more network bandwidth. Default is 64.

Common Configurations

Development

Fast installs, no restrictions:

export SNPM_MIN_PACKAGE_AGE_DAYS=0
export SNPM_REGISTRY_CONCURRENCY=128

Production

Secure and deterministic:

export SNPM_MIN_PACKAGE_AGE_DAYS=7

Use --frozen-lockfile in CI:

snpm install --frozen-lockfile

CI/CD

Fast and reproducible:

export SNPM_REGISTRY_CONCURRENCY=128
snpm install --frozen-lockfile

Hoisting Configuration

Control how packages are hoisted to node_modules:

# No hoisting - strict isolation (like pnpm default)
export SNPM_HOIST=none

# Hoist single versions only (safe, default)
export SNPM_HOIST=single-version

# Hoist all packages (like npm/yarn)
export SNPM_HOIST=all

Or configure via .snpmrc:

.snpmrc

snpm-hoist=single-version

Link Backend Configuration

Choose how packages are linked from the global store:

# Auto-detect best method (default)
export SNPM_LINK_BACKEND=auto

# Use hardlinks (fastest, saves space)
export SNPM_LINK_BACKEND=hardlink

# Use symlinks (works across filesystems)
export SNPM_LINK_BACKEND=symlink

# Copy files (slowest, most compatible)
export SNPM_LINK_BACKEND=copy

Install Scripts Configuration

Control which packages can run install scripts for security:

# Allow specific packages to run install scripts
export SNPM_ALLOW_SCRIPTS="puppeteer,esbuild,@swc/core,canvas"

By default, all install scripts are blocked. This protects against malicious packages.

Verbose Logging

Enable detailed logging for debugging:

# Enable verbose mode
export SNPM_VERBOSE=true

# Or use CLI flag
snpm install --verbose

# Custom log file
export SNPM_LOG_FILE=/path/to/snpm.log

Verbose logs include:

Resolution details
Store operations
Linking progress
Script execution
Performance metrics

Workspace Configuration

Workspaces are configured via snpm-workspace.yaml:

snpm-workspace.yaml

packages:
  - 'packages/*'
  - 'apps/*'

# Optional: configure hoisting for workspace
hoisting: 'single-version'

# Optional: control which packages can run install scripts
onlyBuiltDependencies:
  - 'puppeteer'
  - 'esbuild'

ignoredBuiltDependencies:
  - 'node-sass'

Bundled Dependencies

snpm supports bundledDependencies (or bundleDependencies) in package.json.

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

Dependencies listed here are bundled with the package when published. When installing a package with bundled dependencies:

snpm respects the bundled versions for that package.
It prevents "store pollution" by ensuring these specific bundled versions don't leak into the global store or other parts of the dependency graph inappropriately.

Catalog Configuration

Dependency versions are managed via snpm-catalog.yaml:

snpm-catalog.yaml

# Default catalog
catalog:
  react: ^18.2.0
  typescript: ^5.0.0

# Named catalogs
catalogs:
  build:
    vite: ^5.0.0
    rollup: ^4.0.0
  
  testing:
    jest: ^29.0.0
    vitest: ^1.0.0

Use in package.json:

{
  "dependencies": {
    "react": "catalog:",
    "vite": "catalog:build"
  }
}

See the Catalog documentation for details.

Overrides Configuration

Force specific versions of dependencies:

Via `snpm-overrides.yaml`

snpm-overrides.yaml

overrides:
  # Simple overrides
  lodash: ^4.17.21
  
  # Scope-specific overrides  
  "@babel/core": ^7.23.0

Via `package.json`

package.json

{
  "snpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "@babel/core": "^7.23.0"
    }
  },
  "pnpm": {
    "overrides": {
      "axios": "^1.6.0"
    }
  }
}

Both snpm.overrides and pnpm.overrides are supported for pnpm compatibility.

Configuration

On this page