CodeVetter · Repo Unpack · Extension points
evanw/esbuild
The supported plug-in surface is the plugin object with onStart, onResolve, onLoad, onEnd, and onDispose, available from Go, the CLI via RunWithPlugins, and the JS service. Loaders, defines, inject files, and the runtime helper string are the other intended extension points. New OS targets are new directories under npm/@esbuild plus installer tables, not a plugin.
- api.Plugin is Name plus Setup(PluginBuild). PluginBuild registers OnStart, OnEnd, OnResolve(filter, namespace), OnLoad(filter, namespace), OnDispose, and a Resolve helper. SideEffects is a bool-like enum on results.
- cli.RunWithPlugins appends caller plugins after parse, and --analyze is itself added as a plugin that forces Metafile true. Native Go embedding is the supported way to add plugins without the JS service.
- JS plugins are declared as BuildPlugin records (name, onStart, onEnd, onResolve/onLoad id+filter+namespace) and sent in the build packet. Callbacks round-trip as resolve and on-end requests.
- config.CompileFilterForPlugin compiles each OnResolve and OnLoad filter regex and tags errors with the plugin name and hook kind. That is the validation gate for new plugin filters.
- parseFile's switch on config.Loader is the dispatch table for new content types. Adding a loader means a Loader constant, an extension map entry, a CLI name, and a branch that produces either a JSRepr or CSSRepr.
- Architecture docs say new helper functions belong in the string inside internal/runtime/runtime.go so they are parsed as the runtime file and tree-shaken. Names must not collide with tslib helpers such as __decorate and __extends; esbuild uses its own __create, __defProp, and similar names.
- Compile-time substitution is --define:K=V and the Define map. Dead-code elimination of require() inside folded branches is documented with the React process.env.NODE_ENV pattern. --inject:F and --pure:N are the other per-build hooks that do not require a plugin.
- Resolver namespaces are part of logger.Path. The file namespace is special-cased for canonical Windows paths, relative rewriting, and overwrite checks. dataurl is a namespace handled by resolver.ParseDataURL. Plugins can return other namespaces from OnResolve.
- Engine support is data, not code: internal/compat feature bits plus tables generated from compat-table (MDN, caniuse, compat-table). --target and --supported:F=true|false are the user-facing overrides.
- A new platform package is a directory under npm/@esbuild, plus entries in node-platform.ts maps and esbuild.binaryHashes. RUNBOOK.md says to publish an empty 0.0.1 package, set the esbuild npm user as sole maintainer, and add this repo's publish.yml as the trusted publisher.
- ESBUILD_BINARY_PATH is a documented external extension point. Comments in node-platform.ts and node-install.ts say not to remove it because outside code and the test suite depend on it.
- Banner and footer are per output type (css or js). Injected files are turned into generated import statements in the parser before the visit pass. Both are extension points that do not add a new loader.