Parcel Web Build Tool

Parcel can omit unused assets from the final bundle using two methods:

Subgraph Skipping

If a re-export is unused, the entire dependency subgraph can be ignored. This happens via:

• Deferring: During the graph visit, if a re-export (e.g., export {x} from './y') has no incoming dependencies requesting x, the asset is skipped. This prevents unnecessary transformations of the dependency.
• Unused Dependency: If bundleGraph.getUsedSymbols(dep).size === 0, the dependency is skipped. This is enabled by symbol propagation during scope hoisting and supports export * syntax.

Single Asset Skipping

A side-effect-free asset that only contains re-exports (and is not imported by other bundles) can be skipped entirely by the JS packager, as its re-exports are resolved directly to the original assets.

Example of skipping:

import {a} from './lib.js'; // 'a' is used
console.log(a);

// lib.js
export * from './exports-a.js'; // 'exports-a.js' is used
export * from './exports-b.js'; // 'exports-b.js' is skipped (symbol propagation)
export {c} from './exports-c.js'; // 'exports-c.js' is skipped (deferring)

import {a} from './lib.js';
console.log(a);

// lib.js, asset gets skipped
export * from './exports-a.js'; // dep used, not skipped
export * from './exports-b.js'; // dep skipped with symbol propagation
export {c} from './exports-c.js'; // dep skipped with deferring

Symbol resolution determines the exact code used to access an exported value. The getSymbolResolution() method (and the underlying bundleGraph.getSymbolResolution()) returns the resolved expression for a symbol.

Possible resolution results include:

• $id$export$bar: A same-bundle ESM import.
• $id$exports: A same-bundle ESM import (namespace).
• id$exports.bar: A non-statically analyzable export.
• parcelRequire("id").bar: A wrapped asset or an asset in a different bundle.
• $parcel$interopDefault: Used when an ESM default import resolves to a non-statically analyzable CJS asset.

Key Behaviors:

• Interop Handling: It automatically handles CJS/ESM interop (e.g., using the namespace if a default import resolves to a CJS asset).
• Hoisted Requires: It tracks imports of wrapped assets by mutating a hoistedRequires list, ensuring necessary parcelRequire calls are prepended.
• Transitive Re-exports: The underlying bundleGraph.getSymbolResolution() recursively traverses re-exports to find the actual value, allowing imports to point to the original source rather than just a re-exporting binding.

Parcel uses two primary mechanisms to reduce bundle size and improve performance:

1. Tree Shaking: Removes unused code by identifying unused exports. Parcel achieves this through symbol propagation and conditional generation of $parcel$export() calls. To ensure minifiers can safely remove unused functions, use the /*#__PURE__*/ comment on side-effect-free calls (e.g., React.createContext()).

2. Scope Hoisting: Instead of using a module registry (the "prelude") where imports are function calls like parcelRequire("id").foo, Parcel concatenates assets into a single scope. This replaces module lookups with direct variable access (e.g., $id$export$foo), which improves minification (inlining/constant evaluation) and reduces bundle overhead.

Example of Scope Hoisting transformation:

// math.js
export function add(a, b) { return a + b; }
export function square(a) { return a * a; }

// index.js
import {add} from './math';
console.log(add(2, 3));

// Becomes (simplified):
function $fa6943ce8a6b29$export$add(a, b) { return a + b; }
function $fa6943ce8a6b29$export$square(a) { return a * a; } // Dead code
console.log($fa6943ce8a6b29$export$add(2, 3));

Parcel manages the integration of ES Modules (ESM) and CommonJS (CJS) through several mechanisms:

Default Import Interop

When importing a CommonJS module via a synchronous ESM import, the default import typically contains the module.exports object.

To support modules transpiled from ESM to CJS (which use exports.__esModule = true), Parcel uses an interop check. If an asset is statically identified as ESM or ESM-transpiled-to-CJS, Parcel can optimize away the interopRequireDefault helper call.

// Standard interop pattern used by transpilers
function interopRequireDefault(obj) {
  return obj && obj.__esModule ? obj : {default: obj};
}

Handling Conditional Requires and Multiple Bundles

Parcel uses the parcelRequire registry in two specific scenarios where pure ESM concatenation is impossible:

1. Conditional Requires: If an asset has a conditional incoming dependency (e.g., require() inside an if block), the asset is wrapped in parcelRequire.register. Inside these subgraphs, imports are replaced with parcelRequire calls rather than top-level variables to ensure side effects run correctly.
2. Runtime Deduplication: When an asset is shared across multiple bundles (e.g., via dynamic import()), the registry ensures the asset is evaluated only once, preserving identity (e.g., instanceof checks) and preventing duplicate side effects.

// Example of CJS interop
import v from './other';
// v == { x: 2, y: 3 }

// other.js
module.exports.x = 2;
module.exports.y = 3;

Identifiers (JsWord)

Identifiers in swc use the JsWord type rather than String.

• To create a JsWord from an arbitrary string, use .into(): let x: JsWord = "something".into();.
• For hard-coded, interned words (like require, URL, default, eval), use the js_word! macro for better efficiency: let y = js_word!("require");.

Scopes and Hygiene

swc uses SyntaxContext (a unique number) to handle variable hygiene. A unique variable binding is defined by the pair (JsWord, SyntaxContext).

• To store a unique binding, use the Id type, which represents this pair.
• Use the helper method ident.to_id() to convert an identifier to its unique Id.

Caution with visit_ident

The visit_ident (or fold_ident) functions target all Ident nodes. This includes not just variable bindings, but also names used in destructuring, member access, and private class variables. Modifying all Ident nodes globally can have unintended side effects across different contexts.

  let x: JsWord = "something".into();
  let y: JsWord = js_word!("require") // or "URL", "default", "eval", ...

  let ident: Ident; // the ast node
  ident.sym // the JsWord "string"
  ident.span.ctxt // the syntax context

  // Using Id for unique bindings
  let id = ident.to_id();