npmgo

README

npmgo — pure Go npm package installer

Reads package-lock.json, downloads the pinned tarballs from the npm registry, verifies their integrity, and extracts them into node_modules/. No Node.js, no npm, no JavaScript runtime — pure Go with zero external dependencies.

Why

Go projects that embed a web frontend still need npm packages (react, etc.) to build that frontend. npmgo installs them directly from the lock file, removing Node.js and npm from the build chain — one static binary does the job.

Install

go install github.com/sopranoworks/npmgo/cmd/npmgo@latest

CLI usage

Run in a directory containing package-lock.json:

npmgo install                          # install everything into ./node_modules
npmgo install --production             # skip devDependencies
npmgo install --cache-dir /tmp/cache   # use a specific tarball cache

Other flags: --registry URL, --token TOKEN (private registries), --concurrency N (default 8), --lockfile PATH, --target DIR, --timeout DURATION (default 30s).

Tarballs are cached (content-addressed) under <user cache>/npmgo by default, so repeated installs are near-instant: cached packages are reused and packages already present at the locked version are skipped.

Library usage

import "github.com/sopranoworks/npmgo"

err := npmgo.Install(npmgo.Options{
    LockfilePath: "package-lock.json",
    TargetDir:    "node_modules",
})

All fields are optional; Options{} uses sensible defaults (registry https://registry.npmjs.org, cache <user cache>/npmgo, concurrency 8).

Features

• Lock file parsing: lockfileVersion 1, 2 and 3
• Integrity verification: SHA-512 (also SHA-256 / SHA-1)
• Content-addressed tarball cache, keyed by integrity hash
• Skips packages already installed at the locked version
• Scoped packages (@scope/name) and nested node_modules
• Concurrent downloads
• Private registry support via Bearer token

Limitations

• Requires a package-lock.json; it does not resolve dependencies from package.json or generate a lock file.
• Does not run lifecycle scripts (preinstall, postinstall, etc.).

License

MIT — see LICENSE.

Documentation

Overview

Package npmgo installs npm dependencies from a package-lock.json into a node_modules directory. It is pure Go with no external dependencies: parse the lock file, download tarballs from the registry (or a local content-addressed cache), verify their SHA-512 integrity, and extract them to disk.

Index

• func Install(opts Options) error
• type Options
• type Package
  • func ParseLockfile(data []byte) ([]Package, error)
  • func ParseLockfileFile(path string) ([]Package, error)
• type RegistryConfig

Functions

func Install

func Install(opts Options) error

Install reads the lock file referenced by opts, then resolves every (non-skipped) package: packages already installed at the correct version are skipped, otherwise the tarball is taken from the cache or downloaded, verified, cached, and extracted into opts.TargetDir.

Optional-dependency failures are logged and tolerated; any other package failure aborts the install and is returned.

Types

type Options

type Options struct {
	LockfilePath string // default: "package-lock.json"
	TargetDir    string // default: "node_modules"
	CacheDir     string // default: "<user cache>/npmgo"; cache is keyed by integrity hash
	Registry     string // default: "https://registry.npmjs.org"
	Token        string // optional Bearer token for private registries
	Concurrency  int    // default: 8
	Production   bool   // skip devDependencies when true
	Timeout      time.Duration

	// Logf, when set, receives human-readable progress lines, including
	// per-package cache/download/skip status. It may be called
	// concurrently and must be safe for concurrent use.
	Logf func(format string, args ...any)
}

Options configures an Install.

type Package

type Package struct {
	Path         string            // install path, e.g. "node_modules/react"
	Version      string            // resolved version
	Resolved     string            // tarball URL
	Integrity    string            // subresource integrity, e.g. "sha512-..."
	Dependencies map[string]string // declared dependencies (informational)
	Dev          bool              // development-only dependency
	Optional     bool              // optional dependency (failure is non-fatal)
}

Package is a single resolved dependency that must be downloaded and extracted. Path is the install location relative to the project root, e.g. "node_modules/react" or "node_modules/a/node_modules/b".

func ParseLockfile

func ParseLockfile(data []byte) ([]Package, error)

ParseLockfile parses package-lock.json bytes into the set of packages that must be downloaded. It supports lockfileVersion 1, 2 and 3.

The v2/v3 "packages" map is preferred when present; otherwise the legacy v1 "dependencies" tree is walked. The root entry, and any file:/link: local references, are skipped.

func ParseLockfileFile

func ParseLockfileFile(path string) ([]Package, error)

ParseLockfileFile reads and parses a package-lock.json from disk.

type RegistryConfig

type RegistryConfig struct {
	URL   string // base registry URL (used for relative-path fallbacks)
	Token string // optional Bearer token for private registries
}

RegistryConfig describes how to reach a package registry. Token, when set, is sent as a Bearer credential for private-registry access.