CodeVetter · Repo Unpack · Contributor handoff
evanw/esbuild
Start with the architecture doc, the Makefile, and the three public edges (CLI, pkg/api, lib service protocol). Keep Go 1.13, the single dependency pin, and the path/filepath ban. Do not hand-edit published npm trees. Version changes are a release. Parser and linker edits need snapshot and JS API tests, and cached ASTs must stay immutable.
- Read order for a pipeline change is docs/architecture.md, docs/development.md, internal/bundler/bundler.go (ScanBundle, parseFile, Compile), internal/linker/linker.go (Link), internal/js_parser/js_parser.go (Parse and appendPart), and pkg/api/api_impl.go (contextImpl, rebuildImpl, transformImpl).
- Safe local checks are make or go build ./cmd/esbuild, then make test-go or go test ./internal/... ./pkg/.... Snapshot updates are UPDATE_SNAPSHOTS=1 and must be reviewed. JS API changes also need node scripts/js-api-tests.js and node scripts/plugin-tests.js after scripts/esbuild.js has built the package under test.
- Do not change the go version line or the golang.org/x/sys pin in go.mod. Do not import path/filepath. Do not enable cgo. Release binaries are built with the go.version compiler via the Makefile GO_COMPILER wrapper, not whatever go is first on PATH.
- A release is version.txt (number only), a matching ## header in CHANGELOG.md, then make platform-all committed so every package.json matches, then a push to main. publish.yml fails if git status is dirty after its own platform-all, and it refuses an empty changelog section.
- The JS service and the Go service are one protocol. Changing a command, flag name, or packet field requires edits in lib/shared/stdio_protocol.ts, lib/shared/common.ts, and cmd/esbuild/service.go together. The first stdout bytes of the service are the version string, and the host passes that same version as --service=.
- Cache and linker invariants are unchecked by the type system. cache.go says ASTs are shared across builds and must be immutable, and options that affect parsing must be in the cache key. Architecture docs say cross-build data must stay immutable for watch mode.
- Symbol identity is a ref into a per-file symbol array, merged across files by Link chains. FollowSymbols or FollowAllSymbols must be used before printing. Renaming or cloning symbols without following links will emit the wrong identifier.
- Code splitting only works for the esm format. Moving an assignment to a module-local binding into a different chunk than its declaration is a known correctness hazard documented in architecture.md.
- Watch mode stops when stdin closes unless --watch=forever. The dev server also stops when stdin closes. WASM cannot serve. Do not replace the poller with a cgo file watcher; watcher.go explains why cgo is rejected.
- Large files an agent will fight: internal/js_parser/js_parser.go, internal/linker/linker.go, internal/bundler/bundler.go, and the css_parser declaration files. Prefer a new test in internal/bundler_tests or scripts/js-api-tests.js over a drive-by refactor. (inferred)
- npm/esbuild/lib and the platform bin/ directories are build outputs of scripts/esbuild.js. make publish-all deletes and restores npm/ from git before publishing. Editing generated install.js in the published tree without changing lib/npm/node-install.ts will be overwritten.
- There is no product web UI in this repo. scripts/try.html is a manual WASM playground served by esbuild --servedir=.. Do not treat the React dependency in scripts/package.json as application code.