babel/babel
github.com/babel/babel ↗ · 3997 files · 6.3 MB · scan capped
The compiler for writing next generation JavaScript.
Overview
Babel is a JavaScript compiler toolkit for application developers, build-tool authors, and language-tooling maintainers. Its core resolves layered configuration, parses source into an AST, runs extensible transformation passes, and generates code with source maps. This Babel 8 checkout also supplies command-line compilation, browser compilation, Node require hooks, target-aware presets, and ESLint integration.
System map
The repository is a Yarn workspace monorepo organized around independently published compiler packages. Core coordinates parser, traversal, types, helpers, and generator packages, while CLI, register, standalone, and ESLint packages adapt it to different runtimes. Configuration and compilation state live primarily in memory; register additionally persists compiled results. Distribution consists of npm packages and browser artifacts produced by repository build tooling.
- The private ESM root pins Yarn 4.17.0 and groups packages, codemods, ESLint integrations, runtime integration projects, and benchmarks into workspaces.
- @babel/core exports string, file, and AST transformation APIs, parsing APIs, configuration loaders, and AST tooling; its package entrypoint is lib/index.js.
- Core's compiler boundary depends on separate parser, generator, traverse, types, template, helpers, and compilation-target packages.
- The babel executable imports the compiled CLI dispatcher; parseArgv selects directory mode when outDir is set and file/stdin mode otherwise.
- Core package imports select browser-specific configuration, target resolution, file transformation, and source-map readers instead of their Node implementations.
- @babel/register bridges synchronous require hooks to asynchronous Babel processing with a worker thread, MessageChannel, SharedArrayBuffer, and Atomics.wait.
- Core configuration uses separate synchronous/asynchronous memory caches; register owns an additional memory index and compressed cacache storage on disk.
- Root scripts delegate build, lint, and tests to Make targets; release automation builds with make prepublish and publishes npm packages with provenance, while PR automation publishes testing packages.
Feature catalog
The inspected user surfaces cover programmatic compilation, command-line output, runtime loading, browser execution, and linting integration. Compiler configuration controls plugins, presets, file selection, environments, and emitted formatting. Target-aware preset selection and source maps support application build pipelines. This catalog describes inspected feature families and does not claim exhaustive coverage of every transform package.
- Core exposes callback, synchronous, and Promise-based transformations; in Babel 8, transform without a callback throws and directs callers to transformSync.
- CLI accepts plugins, presets, config-file, env-name, root-mode, ignore/only filters, source-map modes, and compact/minified/comment formatting controls.
- CLI supports stdin, concatenated out-file output, directory output, extension replacement or preservation, dotfile inclusion, asset copying, and watch mode.
- BABEL_SHOW_CONFIG_FOR selects a regular file and prints its applicable root, relative, and programmatic configurations in ascending priority.
- preset-env filters transforms using compatibility data, targets, include/exclude options, and caller module capabilities; useBuiltIns adds a core-js 3 polyfill plugin.
- Standalone bundles env, React, TypeScript, Flow, and historical presets; it exposes transform APIs and automatically processes supported script tags on DOMContentLoaded.
- @babel/register installs reversible compilation hooks and source-map support; babel-node installs register and offers transformed eval/print execution, with REPL imports and exports explicitly rejected.
- @babel/eslint-parser provides parse and parseForESLint; the latter returns the parsed AST, analyzed scopeManager, and Babel-derived visitorKeys.
Data flow
Compilation begins with source text or a filename plus validated options. Configuration establishes absolute paths, targets, plugin descriptors, and ordered passes before parsing or transforming. Per-file state owns the AST, normalized options, metadata, and incoming map, then returns code and dependency information. CLI adapters write outputs, while register optionally caches compiled results across processes.
- loadPrivatePartialConfig validates input options, resolves cwd/root/filename, constructs an environment/caller context, builds the root chain, and resolves targets.
- buildRootChain merges root config, relative file config, and programmatic config in that precedence order; ignored files receive empty plugin/preset lists and fileHandling='ignored'.
- loadFullConfig expands preset descriptors into plugin passes, normally reversing preset order; explicit plugin descriptors are inserted first in the initial pass.
- transformFileRunner resolves configuration before reading UTF-8 source; a null configuration returns null without reading or compiling the input file.
- normalizeFile wraps Program roots as File nodes, rejects other roots, optionally clones supplied ASTs, or parses source; incoming maps come from an explicit object or trailing sourceMappingURL.
- run returns FileResult metadata, normalized options, optional AST/code/map, actual sourceType, and a freshly flattened externalDependencies Set after transformation.
- Directory output derives destination paths from input-relative paths and output-extension options, writes optional map sidecars before code, and copies permissions; file mode combines source maps with line offsets.
- Register cache keys hash serialized resolved options, Babel version, and environment; matching source mtime permits reuse, while new code/map values enter memory and compressed disk batches.
Behavior traces
The source was followed through API compilation, CLI startup and output, and register persistence. These traces preserve execution order and important early exits. Additional inspected branches cover stdin, watch dependencies, standalone scripts, and automatic source-map consumption. They are source-derived walkthroughs rather than observed runtime executions.
- API compilation: transformSync/transformAsync → transformRunner → loadConfig/loadFullConfig → loadPrivatePartialConfig → buildRootChain; null config ends the flow, otherwise run performs compilation.
- Compiler execution: run → normalizeOptions, including manipulateOptions → normalizeFile/parser → transformFile; each pass constructs PluginPass objects, invokes pre, merges/traverses visitors, invokes post, then generateCode runs.
- CLI startup: bin/babel.js imports lib/babel/index.js → parseArgv parses, expands/sorts globs, deduplicates inputs, and validates combinations → dispatcher selects dirCommand/fileCommand; validation failure sets exitCode 2.
- Directory compilation: handle enumerates inputs → handleFile → write checks extension and calls util.compile → transformFileAsync resolves config and reads source → write emits map/code and chmod; ignored or non-compilable inputs may instead be copied.
- Stdin compilation: fileCommand → stdin → readStdin collects UTF-8 text until end → transformRepl calls callback-based babel.transform → output/buildResult emits stdout or the requested file.
- Watch updates: enable creates FSWatcher → compile records externalDependencies → updateExternalDependencies updates forward/reverse indexes → startWatcher adds queued paths → add/change events identify affected inputs and directory callbacks invoke handleFile.
- Register persistence: register → hook.register → compile/client.transform → worker handleMessage TRANSFORM → worker transform loads options and checks cache → transformAsync/store; exit or signal handling sends SAVE → saveCache → Cache.flush.
- Browser execution: DOMContentLoaded → transformScriptTags → runScripts filters script tags → loadScripts obtains inline text or loads src by XHR → check runs eligible scripts in order, allowing async tags to bypass waiting → run appends transformed script elements.
Testing signals
Tests and CI were inspected, not executed; their existence establishes intended coverage, not passing results. Jest uses jest-light-runner in a Node environment, and fixture harnesses exercise parser, compiler, and CLI behavior against built artifacts. CI defines coverage, platform matrices, external parser suites, runtime interoperability, and downstream integration checks. Inspection was bounded, so unexamined packages and scenarios remain unassessed.
- The inspected Jest configuration uses jest-light-runner, Node testEnvironment, V8 coverage, and test discovery under packages, codemods, and eslint; no test or CI execution was performed for this brief.
- Parser test/index.js feeds built parse into runFixtureTests, whose generated cases vary starting positions and compare recovered AST/error results with expected fixtures.
- Core async tests assert rejection of async config functions, Promise configs, and async cache handlers even through transformAsync, while accepting an ESM config that configures caching.
- Source-map tests exercise downward resolution, downward package crossings, and rejection of upward package-boundary crossings; dependency tests assert fresh Sets and propagation through cached plugins.
- CLI tests build parallel process fixtures against compiled binaries with default transforms and normalize duration/path output; register tests cover hook setup/revert, source-map support, disk reuse, invalid cache paths, and batching.
- Coverage excludes standalone, generated types, and helper implementations; publish-bundle runs skip .skip-bundled.js tests. The cache-expiry test checks removal after 30 days, so it does not establish the implementation's exact one-day cutoff.
- CI specifies Node 22/24/25 tests, Windows/macOS tests, c8 coverage and ESM checks, and separate build/lint/test jobs with BABEL_9_BREAKING=true.
- CI defines external Test262/Flow/TypeScript parser suites and runtime/bundler checks; E2E uses local Verdaccio packages with Babel, create-react-app, Angular CLI, and Prettier, while several other project entries are commented out.
Risk map
The principal trust boundaries are executable configuration/plugins, filesystem output, browser script execution, and synchronous worker IPC. Source-map loading includes a lexical root/package restriction, while register cache location is configurable outside the checkout. Two potential failure modes below are explicitly labeled hypotheses and were not reproduced. These observations do not establish confirmed vulnerabilities or whole-repository security coverage.
- Loading JavaScript/TypeScript configs and plugins executes modules through require or dynamic import, and config factories are invoked directly; these paths inherit host-process capabilities.
- CLI --delete-dir-on-start reaches recursive force deletion of the requested outDir; normal compilation also creates directories and overwrites code/map files at derived destinations.
- Automatic external source-map loading rejects upward paths outside the nearest package/root using path.relative checks, then reads the accepted path synchronously; this code does not perform realpath-based containment.
- Register cache IO may target BABEL_CACHE_PATH, a discovered package cache, or temporary/home storage; enabling the cache also removes entries older than one day.
- Hypothesis: register can reuse stale compilation if source content changes without changing mtime, because cacheLookup hashes resolved options/version/environment and validates mtime rather than input text. (inferred)
- Hypothesis: worker startup failure or failure before notification could leave a require hook blocked, because WorkerClient calls Atomics.wait without a timeout; normal worker response handling notifies in finally. (inferred)
- Standalone fetches script src URLs with XHR and appends generated script text to the document, preserving nonce; babel-node separately runs transformed eval text through vm.runInThisContext.
- Release automation has npm OIDC and Git write paths and explicitly avoids cached release builds; compiler correctness also assumes built-ins and their standard contracts have not been redefined.
Extension points
Plugins and presets are the main compiler extension contracts. Factories receive versioned APIs and cache controls, while plugin objects supply visitors and lifecycle hooks. Parser mixins, standalone registries, CLI option declarations, and worker action dispatch provide additional integration points. These mechanisms enforce ordering and compatibility constraints that extensions must preserve.
- PluginObject supports name, manipulateOptions, pre/post, inherits, visitor, parserOverride, and generatorOverride; validation rejects unknown properties and catch-all visitor enter/exit handlers.
- Plugin/preset factories receive api, options, and dirname; API construction includes cache, env, caller, targets, addExternalDependency, and plugin assumption access.
- Inherited plugins chain pre/post/manipulateOptions hooks, merge inherited and local visitors, and propagate inherited external dependencies with cache invalidation.
- PluginPass exposes per-pass Map state, file/options/cwd/filename/isAsync context, helper availability/insertion, and code-frame error construction.
- Parser/generator overrides may decline by returning undefined, but multiple returned results or Promise results throw; otherwise Babel uses its default parser/generator.
- Parser extensions compose ordered mixins for ESTree, JSX, Flow, TypeScript, V8 intrinsics, and placeholders; parser classes are cached by mixin names, and Flow/TypeScript cannot be combined.
- Standalone exposes registerPlugin(s) and registerPreset(s); duplicate names warn and replace registry entries, and processOptions resolves user-supplied names against those registries.
- CLI options extend through Commander declarations and babelOptions/cliOptions mapping; register worker functionality extends through the ACTIONS switch dispatching option, transform, ignore, and save requests.
Contributor handoff
Begin changes in the owning package and follow its public API into implementation and fixture runners. The repository expects built lib artifacts for many tests, and its configuration deliberately separates source builds from test compilation. Tests and CI were inspected, not executed; any future checks require execution authorization and must produce their own outcomes. This brief is bounded, and historical comments or documentation should be checked against current manifests and workflows.
- Read package.json, the affected package manifest, CONTRIBUTING.md, and local AGENTS.md first; the latter documents specific disclosure and wording requirements for LLM-generated PR descriptions.
- Use the pinned Yarn version and package engine ranges: core and CLI require Node ^22.18.0 or >=24.11.0, which is more precise than CONTRIBUTING.md's broad minimum.
- Keep implementation edits in owning src files and account for built lib artifacts: parser and CLI runners consume compiled code, and root tsconfig.json declares itself generator-produced.
- Before changing transform semantics, read config/full.ts and transformation/index.ts together: reversed preset expansion, explicit-plugin priority, merged visitors, and lifecycle hooks determine execution order.
- When execution is authorized, begin with a narrow package Jest selector such as yarn jest babel-cli; repository test/lint targets and CI were inspected here, not executed or reported as passing.
- Regression fixtures distinguish input/output snapshots, expected errors, and preferred semantic exec.js assertions; OVERWRITE=true deliberately rewrites fixtures and should be used with reviewed expectations.
- Preserve isolation from the monorepo build config: babel.config.ts rejects ordinary test loading, and ESLint's parser disables babelrc, root config, and browserslist config discovery.
- Check behavior flags against current CI rather than copying historical examples: CONTRIBUTING.md still documents BABEL_8_BREAKING, while CI has BABEL_9_BREAKING variants; formatting uses two spaces, double quotes, and source/test trailing-comma overrides.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 16029 | 90% |
| JSON | 9282 | docs/config |
| TypeScript | 1664 | 9% |
| Markdown | 214 | docs/config |
| Shell | 22 | 0% |
| YAML | 20 | docs/config |
| HTML | 5 | docs/config |
| Vue | 1 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (3589 files) lib/ (5 files)
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 3589 |
eslint/ | 98 |
scripts/ | 65 |
benchmark/ | 61 |
codemods/ | 54 |
test/ | 48 |
.github/ | 25 |
.yarn/ | 5 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.md
Package
package.json — babel v8.0.6, 66 declared dependencies.
$repo-utils@actions/github@babel/cli@babel/core@babel/eslint-parser@babel/eslint-plugin-development@babel/eslint-plugin-development-internal@babel/plugin-transform-dynamic-import@babel/plugin-transform-export-namespace-from@babel/plugin-transform-json-modules@babel/plugin-transform-modules-commonjs@babel/plugin-transform-object-rest-spread
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/agent-scan.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow.github/workflows/e2e-tests.yml— GitHub Actions workflow.github/workflows/issue-triage.yml— GitHub Actions workflow.github/workflows/lock.yml— GitHub Actions workflow.github/workflows/package-manager.yml— GitHub Actions workflow.github/workflows/pkg-pr-new.yml— GitHub Actions workflow.github/workflows/release.yml— GitHub Actions workflow
Structural health signals
Average score 7.7/10 across 96 analyzed source files; 15 hotspots surfaced.
packages/babel-generator/test/index.js— 1696 lines, score 4.7 (Large file, Deep nesting)eslint/babel-eslint-tests/test/integration/eslint/verify.js— 2057 lines, score 5 (Large file, Deep nesting)packages/babel-helper-module-imports/test/index.js— 1272 lines, score 5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
7c1dcfac00372026-09-30 — Make `@babel/preset-typescript` export type `Options` (#18251)c5b07a5b684d2026-09-30 — Evaluate TypeScript expression wrappers in `NodePath#evaluate` (#18151)b6bb5646d6d72026-09-30 — Fix eslint-parser AST definition of AccessorProperty (#18257)41a16f69299e2026-09-29 — chore: use `npm trust` to set up trusted publishing (#18260)d23b2fd8d5612026-09-28 — fix(core): createConfigItem allows cb as 2nd arg (#18254)