esgun

command module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 24 Imported by: 0

README

esgun

esgun is a Go-native, npm-compatible package manager and esbuild bundler: it resolves npm dependencies straight from the registry, manages them (add/remove/update/outdated), audits them against OSV, and bundles your frontend, all in a single static Go binary. No node, no npm, no bun.

go install github.com/oddship/esgun@latest
cd my-frontend
esgun deps && esgun build

package.json stays fully standard (dependencies + a conventional scripts block); the lockfile is standard package-lock.json (lockfileVersion 3, which npm and Dependabot both accept); the build choreography lives in a tool-named esgun.config.json next to it (the vite.config / eslint.config convention).

Why

The JavaScript toolchain is the odd dependency of most Go web projects: a Go binary that ships a frontend still needs node/npm/bun installed everywhere it's built, for what is usually a handful of leaf dependencies copied verbatim into the binary. esgun replaces that with Go: the registry protocol, semver resolution, lockfile management, security auditing, and bundling all run as Go (esbuild as a library), so Go 1.25.10 or newer is the only toolchain requirement.

As a deliberate security posture, esgun never runs lifecycle scripts: nothing in the dependency tree ever executes during install, and it verifies every tarball's SHA-512 against the registry's dist.integrity before anything touches disk.

Install

Prebuilt binaries for Linux, macOS, and Windows (amd64 and arm64) are available on the Releases page. Extract the archive for your platform and place esgun (or esgun.exe) on your PATH. Each release includes SHA256SUMS for verifying the downloaded archives.

To install from source, choose one of these options:

1. PATH binary (for ad-hoc use anywhere):

go install github.com/oddship/esgun@latest

2. Run without installing:

go run github.com/oddship/esgun@latest <cmd>

3. Go tool dependency (recommended for projects): pin esgun in the project's go.mod so the version is locked with the rest of the toolchain and contributors get it automatically:

go get -tool github.com/oddship/esgun@latest

This adds tool github.com/oddship/esgun to go.mod (with the resolved version in require + go.sum). The project then invokes the pinned build from anywhere:

go tool esgun deps

Bumping the tool is a normal go get -tool github.com/oddship/esgun@vX.Y.Z, same as any other Go dependency. The first go tool esgun run compiles it; subsequent runs use the build cache.

Commands

esgun deps          [--dir DIR] [--frozen] [-u]   # install from lockfile
esgun ci            [--dir DIR]                   # frozen install (fails on lockfile drift)
esgun install       [--dir DIR]                   # alias of deps
esgun add <pkg>[@range] [--dev] [--dir DIR]       # add/upgrade a dependency
esgun remove <pkg>  [--dir DIR]                   # remove a dependency
esgun update [pkg]  [--dir DIR]                   # re-resolve within declared ranges
esgun outdated      [--dir DIR]                   # newer versions available
esgun audit         [--dir DIR]                   # OSV vulnerability report (exit 1 on findings)
esgun build         [--dir DIR] [--profile NAME]  # bundle + assemble the output
esgun watch         [--dir DIR] [--profile NAME]  # rebuild on change

Flags: --dir DIR (default "."), --profile NAME (build/watch only),
--registry URL (or ESGUN_REGISTRY), --frozen, --dev, -u

Getting started

mkdir my-frontend && cd my-frontend
esgun add dayjs            # writes "dayjs": "^1.11.x" to package.json, installs
esgun add @codemirror/state --dev
esgun build                # needs an esgun.config.json (see below)

deps

  • Reads package.json as a manifest (name/version list only; nothing executes it).
  • Resolves the full dependency graph against the registry (abbreviated packuments, exactly like npm itself), honoring npm-style semver ranges (^, ~, >=, ||, …).
  • Reuses the existing package-lock.json when a pinned version still satisfies its range (installs are reproducible). -u re-resolves everything.
  • Verifies every tarball's SHA-512 against the registry's dist.integrity before extracting.
  • Writes a package-lock.json (lockfileVersion 3) that npm and Dependabot can consume (npm ci --dry-run passes on it).
  • Extracts packages into vendor/node_modules/<name>; no node_modules directory, no lifecycle scripts.

package management

add/remove/update edit package.json (dependency maps stay alphabetically sorted; every other field is preserved byte-for-byte) and then re-resolve the graph, rewrite the lockfile, and refresh the vendor tree (stale packages pruned):

  • esgun add dayjs : resolve latest stable (via the registry dist-tags), save ^<version>, install. esgun add pkg@1.2.3 saves the exact range; esgun add pkg@~0.7 saves it verbatim; esgun add pkg@next resolves a dist-tag.
  • esgun remove dayjs : drop from package.json, lockfile, and vendor tree.
  • esgun update : re-resolve everything within declared ranges (npm update semantics; package.json unchanged).
  • esgun update dayjs : same, for one package.

devDependencies are resolved too (marked "dev": true in the lockfile); unsatisfied peer dependencies and unavailable optional dependencies degrade to warnings instead of errors.

build

  • Bundles the configured entry points with esbuild as a Go library (github.com/evanw/esbuild): ESM output, code splitting into chunks/[name]-[hash].js, minified, browser target. Package imports resolve through the resolve dirs (e.g. vendor/node_modules) via esbuild NodePaths.
  • The assembly choreography is project data, not tool code: an esgun.config.json next to package.json declares the output root, entry set (explicit paths or * globs), extra resolve roots, verbatim file/directory copies, curated tree copies, and watch dirs.
// esgun.config.json
{
  "root": "dist",
  "target": "esnext",
  "outdir": "dist/js",
  "entry": ["src/main.js", "src/views/*.js"],
  "resolve": ["vendor/node_modules"],
  "copies": [
    { "from": "src/static", "to": "dist" },
    { "from": "vendor/node_modules/chart.js/dist/chart.umd.js", "to": "dist/vendor/chart.min.js" }
  ],
  "treeCopies": [
    { "from": "vendor/node_modules/tinymce", "to": "dist/tinymce",
      "include": ["tinymce.min.js", "plugins/image/plugin.min.js"] }
  ]
}

package.json stays fully standard: deps plus a conventional scripts block ("build": "esgun build", "watch": "esgun watch").

Compressed output in a development volume

This complete example combines copies, compression, config-aware watch mode, and a stable output directory for Docker volumes:

{
  "root": "dist",
  "outdir": "dist/js",
  "entry": ["src/main.js"],
  "copies": [{ "from": "assets", "to": "dist/assets" }],
  "watch": ["src", "assets"],
  "gzip": {
    "extensions": [".js", ".css", ".svg"],
    "level": 9,
    "removeOriginal": true
  },
  "preserveRoot": true
}

Run esgun build for a one-shot build or esgun watch while developing. Bundles and copies are compressed in staging before publication. The server must map requests for assets to their .gz variants and send the original content type with Content-Encoding: gzip; esgun does not rewrite asset URLs.

All configured paths must stay within the project directory after resolving symlinks. Copy destinations must also stay inside root. Use a dedicated output directory: esgun owns its contents and removes stale files on successful builds. Watch directories must not overlap the output root. gzip is disabled and preserveRoot is false unless explicitly configured, preserving the default uncompressed, rename-based publishing behavior.

Named build profiles

Libraries that publish several formats can replace the legacy entry and outdir fields with named entry sets and profiles. Legacy manifests keep their original minified, split ESM behavior unchanged.

{
  "root": "dist",
  "resolve": ["vendor/node_modules"],
  "entrySets": {
    "library": [
      { "input": "src/index.js", "output": "library" }
    ],
    "components": [
      { "input": "src/components/*.js", "output": "components/[name]" },
      { "input": "src/components/*.css", "output": "components/[name]" }
    ]
  },
  "profiles": {
    "esm-readable": {
      "entrySets": ["library", "components"],
      "outdir": "dist",
      "format": "esm",
      "suffix": ".esm"
    },
    "iife-readable": {
      "entrySets": ["library"],
      "outdir": "dist",
      "format": "iife"
    },
    "iife-minified": {
      "entrySets": ["library"],
      "outdir": "dist",
      "format": "iife",
      "minify": true,
      "suffix": ".min"
    }
  },
  "copies": [
    { "from": "src/themes", "to": "dist/themes" }
  ]
}

Entry output values are stable paths relative to a profile's outdir and omit the generated extension. A glob input must use exactly one [name] placeholder. suffix is inserted before both .js and .css, so library with "suffix": ".min" becomes library.min.js.

format is either esm or iife; minify and splitting default to false. IIFE profiles cannot use splitting. Self-contained component entry points should also leave splitting disabled. target defaults to the legacy es2020 behavior and may be set to esnext globally or overridden by one profile when a library should preserve modern syntax for smaller published artifacts.

esgun build executes every profile serially in lexical name order. Use esgun build --profile esm-readable to build only one. A selected build still replaces the complete root and runs the shared copies once, so it never leaves stale outputs from other profiles. Builds are assembled in a sibling staging directory and replace the previous output only after every bundle and copy succeeds (including optional compression). Output aliases and copy destinations are collision checked.

Precompressed assets

Set gzip to precompress selected extensions after bundling and copying, before staged output is published. This applies to both legacy and profile builds, and to every rebuild in watch mode:

{
  "entry": ["src/main.js"],
  "gzip": {
    "extensions": [".js", ".css", ".svg"],
    "level": 9,
    "removeOriginal": true
  }
}

level defaults to 9 and accepts 0–9. Extensions must be non-empty suffixes such as .js (not paths or globs); .gz is rejected. Originals are retained by default. Compression is disabled when gzip is absent. Existing .gz destinations, including case-insensitive collisions, fail the build without replacing the previous output. Gzip headers omit filenames and timestamps for reproducible output. Servers must serve .gz files with the original content type and the appropriate Content-Encoding header.

Output directories mounted as volumes

By default esgun publishes a completed stage by renaming the output root. If root is a Docker volume or another mount point, enable preserveRoot:

{
  "root": "dist",
  "preserveRoot": true,
  "entry": ["src/main.js"]
}

This preserves the root directory's identity, replaces its contents, and removes stale files. Legacy and profile builds (including watch rebuilds) use the same publishing mode. Compilation and copy failures leave the live output untouched. Existing files are backed up before publication; publication errors restore them. If restoration also fails, the error reports the retained backup directory for manual recovery. Symlinks and special files in staged or previous output are rejected before publication. A process crash or interruption during this non-atomic publication can also leave partial output and a backup; the next successful build replaces the output contents.

This mode copies files so it also works across a mount's filesystem boundary. It needs space for a backup and does not provide an atomic directory swap: readers can see a partially populated directory during publication. The default remains the rename-based publisher; preserveRoot is opt-in.

watch

Rebuilds on changes to esgun.config.json (including atomic editor saves) or the configured watch dirs (default src, 100 ms debounce). Uses inotify via fsnotify plus a 300 ms mtime poll as a fallback, because host-mounted workspaces may not deliver inotify events for host-side editor writes. --profile NAME applies the same selection as build. Changes during a build coalesce into at most one follow-up build. Manifest edits reload and revalidate the watch directories and output root. Invalid watch settings keep the previous output and subscriptions so a corrected manifest can recover without restarting the watcher. The manifest must parse, and its selected profile and watch paths must be valid, when watch mode starts. Source and config changes made during a build are picked up by subsequent rebuilds.

audit

esgun audit queries the free OSV database for every resolved version in the lockfile and exits 1 if any vulnerabilities are found; drop-in npm audit behavior for CI, without a node runtime.

Release history

See CHANGELOG.md for versioned changes and compatibility notes.

Status

MVP: single-package layout, flat resolution (no workspaces/monorepos), no lifecycle scripts, no private-registry auth, no publish command. All by design. Known follow-ups: unit tests for the resolver and review of semver edge cases beyond Masterminds/semver's coverage.

Documentation

Overview

esgun: Go-native frontend build tool. Resolves npm dependencies from a registry and bundles the frontend with esbuild — no node/npm/bun required anywhere.

Project specifics live in package.json (dependencies/devDependencies) and a esgun.config.json (see buildManifest) describing entry points and copy choreography for `build`.

esgun deps   [--dir DIR] [--frozen] [-u]   resolve + materialize from lockfile
esgun ci     [--dir DIR]                    frozen install (CI)
esgun add <pkg>[@range] [--dev] [--dir DIR] add/upgrade a dependency
esgun remove <pkg>       [--dir DIR]        remove a dependency
esgun update [pkg]       [--dir DIR]        re-resolve within declared ranges
esgun outdated           [--dir DIR]        show newer available versions
esgun audit              [--dir DIR]        vulnerability report (OSV)
esgun build  [--dir DIR] [--profile NAME]   bundle entry points with esbuild
esgun watch  [--dir DIR] [--profile NAME]   rebuild on change (fsnotify + poll)

Flags: --dir DIR, --registry URL, --profile NAME, --frozen, --dev, -u

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL