parcel-bundler/parcel
github.com/parcel-bundler/parcel ↗ · 3999 files · 4.5 MB · scan capped
Parcel is a zero configuration build tool for the web.
Overview
Parcel is a web build tool for application and library developers, with CLI commands for production builds, watch mode, and a development server. Its JavaScript orchestration layer tracks build requests and invalidations, delegates compiler work to Rust bindings, and composes configurable transformer, bundler, packager, optimizer, and reporter plugins. The inspected implementation also supports persistent build caches, on-demand development bundles, browser HMR, Node application execution, project templates, and a browser-based REPL.
System map
The primary product runs as a Node CLI or an embedded Parcel instance. JavaScript owns request scheduling, graph state, plugin orchestration, reporting, and filesystem boundaries, while native bindings provide compiler and other Rust functionality. Storage combines an abstract cache API with filesystem snapshots. Distribution includes published JavaScript packages, platform-specific native artifacts, and a separately built browser REPL.
- The CLI entrypoint conditionally loads @parcel/babel-register outside production or during self-build, then requires cli.js; Commander registers serve, watch, build, and help.
- @parcel/core publishes lib/index.js from src/index.js; Parcel.run() initializes, builds, shuts down, and converts a buildFailure result into BuildError.
- Parcel owns resolved options, configuration, RequestTracker, reporters, worker references, and a watch queue limited to one concurrent build.
- AssetGraphRequest resolves entries, targets, dependencies, and transformed asset groups; BundleGraph exposes the resulting internal graph through mutable or public wrappers for different plugin stages.
- Workers retrieve shared options and cached configuration before running Transformation, Validation, or PackagerRunner; native compiler bindings call parcel_js_swc_core, with asynchronous native transforms scheduled through Rayon.
- resolveOptions selects LMDBCache for NodeFS output and FSCache for other filesystems unless a cache is supplied; LMDB stores binary values while streams and large blobs use separate files.
- The monorepo uses packages/*/* workspaces and Yarn 4.9.1; root scripts separate JavaScript builds, native and WASM builds, declaration checks, Mocha tests, Cargo tests, and integration tests.
- Release workflows build macOS, Windows, GNU/Linux, and musl native artifacts before publishing; canary releases are scheduled daily, tagged releases invoke yarn release, and REPL previews are deployed through CI.
Feature catalog
Parcel exposes production bundling and continuous development through both CLI and programmatic interfaces. The default configuration covers web languages, preprocessing tools, images, structured data, and specialized import pipelines. Development features include HTTP serving, HMR, proxy middleware, and execution of Node entry bundles. Separate utilities provide project scaffolding and an interactive browser build environment.
- serve starts development serving and supports lazy async bundles; watch rebuilds continuously; build exposes optimization, scope-hoisting, content-hash, and output-URL controls.
- The default transformer map handles JS/JSX/TypeScript, JSON/JSON5, YAML/TOML, GraphQL/GLSL, Sass/Less/Stylus, CSS, HTML/Pug, Vue, raster images, SVG, XML, and native Node assets; some implementations are installed on demand.
- Named pipelines support declaration generation, bundle-text and data-url imports, worklets, static React output, and URL assets; their packagers and optimizers can differ from ordinary file processing.
- TargetResolver filters package targets by requested names and rejects unknown targets; the default bundler groups entries by target and exposes shared-bundle size, request-count, and manual-bundle settings.
- Development serving includes HTML route fallback, source-file serving, configurable proxy middleware, and HMR updates; NodeRunner starts matching Node entry bundles in worker_threads and restarts them when HMR is disabled.
- CLI diagnostics render messages, code frames, stacks, hints, and documentation; users can add reporters, enable tracing or profiling, and trigger profiling or heap snapshots through terminal shortcuts.
- create-parcel copies a named template into an empty or new directory, initializes Git, installs dependencies with the invoking package manager, and creates an initial commit; the React client template supplies an editable App component.
- The REPL worker exposes bundle, watch, readiness, and service-worker coordination over Comlink; its Parcel instance uses an in-memory filesystem and returns bundle content, timing, optional graphs, and sourcemaps.
Data flow
Inputs enter through CLI arguments or InitialParcelOptions and become normalized project paths, target settings, and shared worker options. Entry and dependency requests expand an asset graph whose transformations return both asset data and invalidation metadata. Bundling converts that graph into named outputs, followed by packaging, optimization, hash replacement, and compression. Request state and watcher snapshots preserve reuse across invocations.
- CLI run() defaults empty entries to '.', resolves them to absolute paths, normalizes flags, and constructs Parcel; resolveOptions derives projectRoot from an upward lockfile/VCS search and converts entries to project paths.
- EntryResolver expands globs recursively and reads package targets for directory entries; AssetGraphRequest then attaches resolved entries, targets, dependency paths, and asset-group results to its graph.
- AssetRequest passes a configuration cache path, shared options reference, and prior dev-dependency information to runTransform; Transformation loads the asset and pipeline, runs transformations, commits results, and returns assets or diagnostics.
- Worker transformation results feed file-update/delete/create, environment, option, startup, and build invalidations into RequestTracker; runRequest reuses valid results and waits for an already-running request before rerunning it.
- After asset traversal, symbol propagation updates graph usage information; BundleGraph.fromAssetGraph removes asset groups and retargets dependencies, and BundlerRunner either updates a previous graph or invokes a fresh bundler pass.
- PackagerRunner.getBundleResult packages each bundle, optimizes each returned result, and generates its sourcemap; optimizer output type changes affect subsequent filename-based plugin selection.
- WriteBundlesRequest computes final name hashes and skips placeholder outputs; WriteBundleRequest reads cached content, replaces hash references, invokes compressors, and streams their results to target files with recorded size statistics.
- Shutdown serializes cacheable request results and the request graph alongside a watcher snapshot; startup deserializes the graph, obtains events since that snapshot, and invalidates startup, build, environment, option, and filesystem changes.
Behavior traces
The source walks establish production startup, asset-to-output processing, watch rebuilds, lazy HTTP requests, and persistence restoration. Each trace names the actual execution order and relevant conditional branches. Builds and serving communicate through reporter events rather than a separate application backend. These are source-derived traces; no runtime behavior was exercised.
- Production startup follows bin.js → cli.runCommand() → run() → normalizeOptions() → new Parcel() → Parcel.run() → _init(); initialization awaits sourcemaps/Rust, resolves options, loads configuration, initializes workers/cache/reporters, then restores RequestTracker.
- The build enters _build() → createParcelBuildRequest() → createBundleGraphRequest() → createAssetGraphRequest(); AssetGraphRequest.build() traverses queued requests, then runAssetRequest() dispatches AssetRequest → worker.runTransform() → Transformation.run().
- For a fresh bundle graph, BundlerRunner.bundle() calls loadConfigs(), gets the bundler, converts AssetGraph, calls bundler.bundle(), conditionally calls bundler.optimize() in production, then names bundles and applies runtimes; an eligible previous graph instead receives changed asset updates.
- Output follows ParcelBuildRequest.run() → WriteBundlesRequest → PackageRequest → PackagerRunner.getBundleResult() → package() → optimize() → WriteBundleRequest; bundles without hash references can begin writing before complex name hashes are assigned.
- Watch startup calls watch() → _getWatcherSubscription() → report(watchStart) → queued _startNextBuild(); later filesystem events call respondToFSEvents(), abort an active build when invalidated, and enqueue one replacement build when none is waiting.
- An HTTP bundle request follows Server.respond() → serveBundle() → event.requestBundle(); a placeholder adds entry asset IDs and queues a rebuild, while a non-placeholder returns immediately, after which serveDist() serves outputFS content.
- Persistence follows Parcel._end() → RequestTracker.writeToCache() → serialized results/graph plus inputFS.writeSnapshot(); the next _init() calls RequestTracker.init() → loadRequestGraph(), with a fresh graph used when caching is disabled, missing, or restoration throws.
- _build() reports buildSuccess before running validation and checking reporter errors; subsequent exceptions become a reported buildFailure, except BuildAbortError is rethrown. Parcel.run() then shuts down before throwing BuildError for a failure result.
Testing signals
Tests and CI were inspected, not executed; test existence does not establish a passing result. The inspected JavaScript suites use Mocha with Node assertions, Sinon, shared filesystem utilities, and WebSocket clients. Rust includes ordinary #[test] cases, and CI configures cross-platform unit and integration runs plus type and formatting checks. This bounded inspection does not establish complete coverage, browser parity, or security-test completeness.
- Root Mocha discovery targets package tests outside integration-tests and loads Babel registration plus shared setup; test:unit chains Mocha with cargo test --workspace --exclude parcel-node-bindings.
- Parcel.test.js checks rejection of an ending worker farm, owned-versus-supplied farm cleanup, shared-reference removal, and unstable transform/resolve APIs; its helper disables caching and uses a configuration without reporters, limiting that suite's persistence/server coverage.
- RequestTracker.test.js explicitly checks valid-result reuse, reruns after invalidation, parent invalidation through subrequests, failed requests, and removal of obsolete subrequests.
- Integration cache tests build, mutate inputs, and rebuild with caching enabled; the inspected cases assert changed execution results after a JS edit or new dependency and check that cache content omits project file paths.
- Server integration tests compare HTTP responses with output files, verify HEAD content length and empty bodies, and exercise source-file and sourcemap serving; HMR tests assert changed JS content and source-map/source-URL annotations over WebSockets.
- The Rust resolver's #[test] relative case exercises explicit extensions, omitted extensions, repeated separators, and tilde paths; its fixture root points into the JavaScript resolver fixture tree.
- CI configures Node 20/22 across Linux, macOS, and Windows for unit and integration tests, builds native bindings first, and additionally builds JavaScript packages before integration tests; separate jobs run lint, Flow, and declaration checks.
- Integration Mocha configuration allows 50-second tests and two retries, and CI disables fail-fast with a flakiness comment; HMR client helpers use a 100-ms sleep, so inspecting these tests does not prove deterministic real-browser behavior.
Risk map
The observed trust boundaries include development HTTP/WebSocket interfaces, executable project configuration and plugins, package-manager subprocesses, and output/cache filesystem writes. Several correctness-sensitive paths depend on graph invalidation, update ordering, and worker cache visibility. Findings below are source observations or explicitly labeled hypotheses, not confirmed vulnerabilities or reproduced defects. The inspection was bounded and does not establish the absence of protections or tests elsewhere.
- The CLI documents listening on all interfaces by default, Server.start() defaults CORS to wildcard headers, and the source endpoint serves inputFS beneath projectRoot; this combination makes development-network exposure a review boundary.
- HMRServer.handle() accepts an editor endpoint file query, preserves absolute paths, joins relative paths to projectRoot, and calls launchEditor(); its shown WebSocket initialization uses new WebSocket.Server({server}) without an origin-verification option.
- Plugins are required through the project package manager, and executable proxy configurations are required and invoked with the Connect app; plugin version and symbol validation are compatibility checks around executable code.
- CLI autoinstall defaults to enabled except disabled flags or production-build CI detection; the npm installer can create package.json and spawns npm install with save flags, making an ordinary build capable of dependency and lockfile mutations.
- WriteBundlesRequest explicitly refreshes LMDB after worker packaging because a stale main-thread read transaction can miss committed values; removing or reordering this refresh would disturb a documented concurrency safeguard.
- BundleGraph documents that direct mutation of its exposed _graph can bypass bundle-hash invalidation, with runtime application relying on BundlerRunner to invalidate hashes; graph edits therefore have cross-stage cache consequences.
- buildSuccess is reported before validation, and built-in-server HMR updates may broadcast at the bundled phase before packaging; Node updates use additional readiness coordination, so consumers must distinguish graph readiness, written output, and final validation.
- Hypothesis: runEntryRequest() computes didEntriesChange using prevEntries.every(entryId === currentEntries[index]), which appears to disable incremental bundling for identical lists and may miss equal-length substitutions; this warrants targeted investigation rather than a confirmed defect claim. (inferred)
Extension points
Parcel's intended extension model is a staged plugin pipeline with public asset and graph wrappers. Configuration selects plugins by file glob and optional named pipeline, while loaders validate the plugin instance contract. Bundling, transformation, packaging, optimization, compression, resolution, and reporting expose different responsibilities. Core also supports substitution of filesystems, cache, package manager, and worker farm for embedding and browser operation.
- @parcel/plugin exports Transformer, Resolver, Bundler, Namer, Runtime, Validator, Packager, Optimizer, Compressor, and Reporter wrappers that store hooks under Symbol.for('parcel-plugin-config'); loadPlugin unwraps that symbol and rejects invalid exports.
- ParcelConfig.getNamedPipelines() derives names from colon-prefixed transformer globs, and getTransformers() matches a file/pipeline before loading its plugins, with an allowEmpty branch for missing pipelines.
- Custom bundlers receive MutableBundleGraph plus configuration, options, logger, and tracer; the default plugin illustrates loadConfig(), bundle(), and optimize() and separates ideal-graph construction from graph decoration.
- Transformer hooks include optional parsing and AST reuse, required transformation through MutableAsset, deferred generation, and optional postProcess; pipeline loading preloads each transformer's configuration.
- Packagers receive named bundles, public BundleGraph, source-map references, and inline-bundle content callbacks; optimizers run sequentially over the prior optimizer's contents, map, and optional changed type.
- Compressor plugins receive cloned output streams and may return a typed stream, append an output suffix, or return null to suppress that output; the default configuration uses @parcel/compressor-raw.
- Rust Resolver exposes Node CJS, Node ESM, and Parcel constructors, feature flags, extension lists, export conditions, include-node-modules policy, and a custom module-directory resolver callback suitable for alternate lookup mechanisms.
- Embedding can supply inputFS, outputFS, cache, packageManager, and workerFarm; the REPL uses these substitutions, while CLI --reporter adds reporter packages resolved from the caller's working directory.
Contributor handoff
Start from the relevant product boundary and follow its requests before changing shared graph or cache machinery. Repository scripts, package ownership, Flow annotations, generated declarations, and native prerequisites shape implementation work. Tests and CI were inspected, not executed, and the inventory and investigation are bounded rather than exhaustive. Future agents should preserve that distinction and obtain runtime evidence only when execution is authorized.
- For lifecycle or CLI work, read cli.js, Parcel.js, and resolveOptions.js first; CONTRIBUTING explicitly points newcomers to Parcel.js, and CLI option defaults are translated before the core instance is constructed.
- Use the repository's Yarn 4.9.1/node-modules setup and existing scripts; source/lib manifest pairs and build-ts scripts distinguish editable sources from built packages and generated TypeScript declarations.
- Follow Flow-oriented source conventions, @parcel/eslint-config, and Prettier's single quotes, omitted bracket spacing, LF endings, and trailing commas; Lerna uses independent package versions, and CONTRIBUTING says not to modify package versioning.
- Graph changes require reading symbol propagation and bundler architecture alongside implementation: docs explain down/up symbol passes and per-target ideal graphs, while BundleGraph.fromAssetGraph retargets dependencies based on symbol data.
- Preserve worker ownership and serialized watch scheduling: Parcel ends a farm it creates but only disposes references for a supplied farm; the corresponding tests assert both behaviors and shared-reference cleanup.
- During authorized plugin development, CONTRIBUTING recommends --no-cache or shouldDisableCache to avoid stale local results; compatibility loading separately checks engines.parcel unless SKIP_PLUGIN_COMPATIBILITY_CHECK is set.
- Tests and CI were inspected, not executed. Once execution is authorized, choose the relevant Mocha suite first, then the existing test:unit or integration workspace scripts as appropriate; CI requires native builds and includes lint, Flow, and declaration checks.
- Treat build and utility execution as potentially mutating: configurable cache/watch/output paths cross filesystem boundaries, CLI autoinstall can spawn package installation, and create-parcel performs Git initialization and an initial commit.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 3018 | 92% |
| JSON | 846 | docs/config |
| HTML | 238 | docs/config |
| CSS | 191 | docs/config |
| TypeScript | 151 | 5% |
| Rust | 61 | 2% |
| Markdown | 41 | docs/config |
| Sass | 35 | 1% |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (3817 files) crates/ (49 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/bundlers/ | 2 |
packages/compressors/ | 3 |
packages/configs/ | 5 |
packages/core/ | 122 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 3817 |
flow-libs/ | 55 |
crates/ | 49 |
flow-typed/ | 14 |
.github/ | 13 |
docs/ | 11 |
scripts/ | 10 |
.husky/ | 2 |
Docs found: CONTRIBUTING.mdREADME.mddocs/AdjacencyList.mddocs/BundlerExamples.mddocs/Continuous Integration/Native Binary Builds.mddocs/DefaultBundler.mddocs/Deferring.mddocs/ManualBundling.mddocs/Scopehoisting Packager.mddocs/Scopehoisting Transformer.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readme.github/workflows/canary-release.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow.github/workflows/dev-release.yml— GitHub Actions workflow.github/workflows/release.yml— GitHub Actions workflow.github/workflows/stale.yml— GitHub Actions workflow.github/workflows/tag-release.yml— GitHub Actions workflowcrates/dev-dep-resolver/src/main.rs— Rust binary entrypointpackages/utils/create-parcel/templates/react-client/src/App.tsx— React rootpackage.json— npm scripts: adjust-versions, build, build-bundles, build-native, build-native-canary, build-native-release, build-native-wasm, build-repl
Structural health signals
Average score 6.1/10 across 96 analyzed source files; 65 hotspots surfaced.
crates/parcel-resolver/src/lib.rs— 2802 lines, score 4.7 (Large file, Deep nesting)crates/parcel-resolver/src/package_json.rs— 1993 lines, score 4.7 (Large file, Deep nesting)packages/core/core/test/TargetRequest.test.js— 1719 lines, score 4.7 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
59484858a1a02026-02-01 — v2.16.49e2f6f1377122026-02-01 — Add --no-cors option (#10268)73f691d67d222025-12-06 — v2.16.3b270626ea4a42025-12-06 — Fix react-dom import44a112137f682025-12-06 — v2.16.2