DEV Community: Vahid Ghadiri

Designing a Scalable Release System for Multi-Package TypeScript Monorepos

Vahid Ghadiri — Sun, 26 Jul 2026 11:24:15 +0000

If you maintain more than one npm package in a single repository, you've probably felt the pain of release day. Bumping versions manually, publishing in the right order, hoping you didn't forget a step. Multiply that by four packages and it becomes a real problem.

This article is about solving that problem. I'll walk through a deployment pipeline I built for a multi-package TypeScript monorepo — covering version management, automated publishing, containerized verification, and documentation deployment. The patterns are generic enough to apply to any monorepo that ships multiple packages.

I'll use Nava Icon as a concrete example throughout, but the architecture works for any multi-package setup.

What "Deployment" Means for a Library

Most deployment articles talk about shipping apps to servers. For library authors, deployment means something different:

Version management — Bumping semver across packages correctly
npm publishing — Getting packages to the registry with proper access
Container builds — Creating reproducible verification environments
Documentation — Keeping docs in sync with the latest release
Release automation — Reducing the entire flow to a single human action

The goal: a developer makes a change, and the system handles everything else.

The Architecture

Here's what a production-ready deployment pipeline looks like for a multi-package monorepo:

Code Change
     |
     v
 CI Verification (lint, typecheck, build)
     |
     v
 Docker Validation (reproducible build check)
     |
     v
 Version Bump (automated via Changesets)
     |
     v
 npm Publish (all changed packages)
     |
     v
 Container Image (GHCR)
     |
     v
 Documentation (GitHub Pages)

Every step is automated. The only human action is approving a production deployment.

1. Version Management

Versioning is the hardest part of multi-package deployment. If Package A depends on Package B, and you bump Package B, Package A needs to update its dependency. Do this wrong and you get version mismatches, broken installs, or packages that reference unpublished versions.

The Tool: Changesets

I use Changesets for version management. Here's why it fits multi-package monorepos:

How it works:

# Developer runs this once
pnpm changeset
# Selects: which packages, bump type, description
# Creates: .changeset/lazy-load-icons.md

# The file looks like:
---
"@whydrf/nava-icon-react": minor
"@whydrf/nava-icon-vue": minor
---

Lazy-load dynamic Icon component via per-icon import() chunks

The changeset file is committed with the code. It tells the system what to bump and why.

What Changesets does on CI:

State	Action
Changeset files exist	Creates/updates a version PR with bumped `package.json` versions and changelogs
No changeset files (version PR was merged)	Publishes all bumped packages to npm

Why not semantic-release?

semantic-release is fully automated but all-or-nothing — it decides everything from commit messages. For multi-package monorepos where you sometimes want to bump only specific packages, Changesets gives you that control.

Configuration:

{
  "commit": false,
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@nava-icon/docs", "@whydrf/nava-icon-core"]
}

The ignore list excludes packages that shouldn't be published. The updateInternalDependencies: "patch" ensures that when an internal dependency bumps, its consumers automatically get a patch bump too.

2. CI Verification Pipeline

Before anything gets published, every change goes through verification. The pipeline lives in .github/workflows/ci.yml:

Trigger Strategy

on:
  pull_request:
    branches: [develop, stage, main]
    paths:
      - "assets/**"
      - "packages/**"
      - "scripts/**"
      - ".github/workflows/ci.yml"

  push:
    branches: [main]
    paths:
      - "assets/**"
      - "packages/**"
      - "scripts/**"

Path filtering is a deployment optimization. If someone updates a README, you don't need to rebuild 950 icon components. Only changes to source code, packages, or the CI config itself trigger the pipeline.

Concurrency Control

concurrency:
  group: ci-${{ github.event.pull_request.base.ref || github.ref }}
  cancel-in-progress: true

If a developer pushes twice in quick succession, the first CI run is cancelled. This saves compute and gives faster feedback.

The Verify Job

verify:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 24
        cache: pnpm
    - run: pnpm install --frozen-lockfile
    - run: pnpm generate
    - run: pnpm lint
    - run: pnpm typecheck
    - run: pnpm build

Every PR gets: dependency install → code generation → lint → typecheck → build. If any step fails, the PR can't be merged.

Environment Gating

The pipeline uses GitHub Actions environments to control what runs where:

Environment	Branch	Purpose
`DEV`	`develop`	Development validation
`STAGING`	`stage`	Staging validation
`PRODUCTION`	`main`	Release to npm

The PRODUCTION environment can require manual approval — a human checkpoint before anything gets published.

3. Docker Verification

Docker isn't used for deployment here. It's used for verification — ensuring the project builds correctly in a clean, reproducible environment.

Why Docker for Verification?

Local development environments differ. Different Node versions, different OS behaviors, cached dependencies. Docker eliminates this variable:

FROM node:24-alpine AS base
RUN corepack enable

FROM base AS deps
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ./
RUN pnpm install --frozen-lockfile

FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm generate
RUN pnpm build

FROM base AS verifier
COPY --from=builder /app .
RUN pnpm lint

Layer Caching Strategy

The multi-stage build is designed for Docker layer caching:

deps layer — Only copies manifest files, runs pnpm install. Changes rarely, so this layer is cached.
builder layer — Copies dependencies from deps, runs generation and build. Rebuilds on code changes.
verifier layer — Copies everything from builder, runs lint. Used for CI verification.

Code changes don't invalidate the dependency cache. This makes rebuilds fast.

Local Docker Workflow

pnpm docker:build          # Build the image
pnpm docker:verify         # Run lint in container
pnpm docker:shell          # Interactive shell for debugging
pnpm docker:compose:verify # Full verification via docker-compose

Developers can verify the Docker build locally before pushing. This catches Dockerfile issues early.

4. Automated npm Publishing

This is where the deployment pipeline gets interesting. The flow is:

Release PR Flow

Developer commits changeset file
        |
        v
    Push to main
        |
        v
    changesets/action creates version PR
    (bumps package.json versions, updates CHANGELOGs)
        |
        v
    auto-merge workflow enables squash merge
        |
        v
    CI runs on version PR
        |
        v
    PR merged automatically
        |
        v
    Push to main (from merge)
        |
        v
    changesets/action detects no pending changesets
    → runs `changeset publish`
        |
        v
    Packages published to npm
    GitHub Releases created

The Auto-Merge Step

# .github/workflows/auto-merge-changeset.yml
auto-merge:
  if: github.head_ref == 'changeset-release/main'
  steps:
    - run: gh pr merge ${{ github.event.pull_request.number }} --auto --squash

When the Changesets action creates the version PR, this workflow enables auto-merge. Once CI passes, GitHub merges it without human intervention. The next CI run then publishes.

Publishing Configuration

publish:
  if: github.event_name == 'push' && github.ref_name == 'main'
  environment: PRODUCTION
  permissions:
    contents: write
    pull-requests: write
  steps:
    - uses: changesets/action@v1
      with:
        publish: pnpm publish:ci
        createGithubReleases: true
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

The publish:ci script runs changeset publish, which:

Reads the version bumps from the merged changeset PR
Publishes each changed package to npm
Creates GitHub Releases for each package

5. Container Image Publishing

After npm packages are published, a Docker image is built and pushed to GitHub Container Registry:

docker-publish:
  needs: publish
  steps:
    - uses: docker/login-action@v3
      with:
        registry: ghcr.io
        password: ${{ secrets.GITHUB_TOKEN }}

    - uses: docker/metadata-action@v5
      with:
        images: ghcr.io/${{ github.repository_owner }}/nava-icons
        tags: |
          type=raw,value=latest
          type=sha

    - uses: docker/build-push-action@v6
      with:
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        cache-from: type=gha
        cache-to: type=gha,mode=max

Every release gets two tags: latest and a SHA-based tag. The SHA tag lets you pin to a specific release if needed.

Why Push Docker Images for a Library?

Three reasons:

Reproducible verification — Anyone can pull the image and verify the build
CI cache — Subsequent builds can use the cached image
Future deployment — If you add a playground or demo app, the image is ready

6. Documentation Deployment

The docs site is a Next.js app with static export. It deploys to GitHub Pages:

# .github/workflows/deploy-doc.yml
on:
  push:
    branches: [main]
    paths: ["docs/**"]

The pipeline builds the docs, uploads the artifact, and deploys to GitHub Pages. Only docs/ changes trigger this — icon or package changes don't redeploy docs unless the docs themselves change.

This separation matters for deployment efficiency. Documentation deployment is independent of package deployment.

7. Deployment Timeline

Here's what a typical release looks like end-to-end:

T+0:00   Developer commits changeset, pushes to main
T+2:00   Version PR created by changesets/action
T+2:00   Auto-merge enabled
T+5:00   CI passes, version PR merged
T+5:00   Push to main triggers publish job
T+10:00  Packages published to npm
T+10:00  GitHub Releases created
T+12:00  Docker image pushed to GHCR
T+12:00  Documentation redeployed (if docs changed)

Total time from push to published: ~10 minutes.
Human involvement: zero (after the initial push).

8. Security in Deployment

A deployment pipeline that publishes to npm needs security controls:

Control	Implementation
Token management	`NPM_TOKEN` stored as a GitHub secret, never logged or exposed
Minimal permissions	Each job declares only the permissions it needs
Frozen lockfile	`pnpm install --frozen-lockfile` prevents dependency tampering
Environment protection	`PRODUCTION` environment can require manual approval
Path-based triggers	CI only runs on relevant file changes
Permission scoping	`contents: read` by default, `write` only where needed

What I'd Add for Higher Security

npm provenance — Sign packages with GitHub OIDC to prove they came from your CI
SLSA build provenance — Generate attestations for build artifacts
Dependency scanning — Automated vulnerability checks on dependencies
Branch protection — Require reviews for changes to CI configuration

9. Deployment Patterns Worth Stealing

These patterns work for any multi-package monorepo, not just icon libraries:

Pattern 1: Path-Based Triggers

paths:
  - "packages/**"
  - ".github/workflows/ci.yml"

Don't rebuild everything when documentation changes. Trigger CI only on relevant paths.

Pattern 2: Concurrency Groups

concurrency:
  group: ci-${{ github.event.pull_request.base.ref || github.ref }}
  cancel-in-progress: true

Cancel in-progress runs when new commits push. Save compute, get faster feedback.

Pattern 3: Environment Gating

Use GitHub Actions environments to separate staging from production. Add manual approval gates for production releases.

Pattern 4: Automated Version PRs

Let a tool (Changesets, Lerna, etc.) create the version PR. Human reviews it, CI validates it, auto-merge handles the rest.

Pattern 5: Docker for Verification, Not Deployment

Use Docker to ensure builds work in a clean environment. Don't confuse verification (does it build?) with deployment (does it run?).

Pattern 6: Separate Documentation Deployment

Docs deployment should be independent of package deployment. Different triggers, different pipelines, different failure modes.

10. What I'd Improve

The pipeline works, but there's always room for improvement:

Improvement	Why It Matters
npm provenance	Proves packages came from your CI, prevents supply chain attacks
Bundle size tracking	Catch regressions before they ship to users
Integration tests	Verify published packages install and work correctly
Automated dependency updates	Keep dependencies current without manual effort
Release notifications	Slack/Discord alerts when packages are published
Canary releases	Test changes before a full release

Conclusion

The important part of building a deployment pipeline isn't choosing between pnpm, Turborepo, or Changesets. It's designing a system where every artifact has a predictable path from source to distribution.

For multi-package monorepos, that path looks like:

Code changes → CI verification (lint, typecheck, build)
Version changes → Automated version PR
Merged PR → npm publish + container build
Published → Documentation update

The key principles:

Automate everything that can be automated. Manual steps are where errors happen.
Use path-based triggers. Don't rebuild what hasn't changed.
Gate production releases. A human should approve before anything goes live.
Use Docker for verification. Reproducible builds matter.
Separate concerns. Docs deployment ≠ package deployment ≠ container builds.

The goal is a system where a developer can push a change and trust that the right packages get published to the right places in the right order — every time.

Deployment pipeline built with GitHub Actions, Changesets, Docker, and Turborepo. Source code: github.com/nava-icon/nava-icon

Tree-Shaking : A Deep Dive

Vahid Ghadiri — Fri, 24 Jul 2026 10:40:58 +0000

A comprehensive guide to understanding how modern JavaScript bundlers eliminate unused code, why it matters, and how to write code that enables optimal dead code elimination.

Why Bundle Size Matters
The JavaScript Execution Pipeline
What Is Dead Code?
What Is Tree-Shaking?
Static Analysis: The Engine Behind Tree-Shaking
How the Dependency Graph Is Created
Why ES Modules Are Easier to Tree-Shake
How Rollup, Webpack, and Vite Perform Tree-Shaking
Side Effects: The Silent Tree-Shaking Killer
Sub-path Exports and Package Design
What Breaks Tree-Shaking?
Measuring the Impact
Advanced Techniques and Modern Alternatives
Debugging Tree-Shaking Issues
Common Misconceptions
Best Practices Checklist
Conclusion

Why Bundle Size Matters

Modern web applications often rely on hundreds—or even thousands—of JavaScript modules. Before these applications can run in a browser, a bundler such as Rollup, Webpack, or Vite combines those modules into one or more optimized output files known as bundles.

The size of these bundles has a direct, measurable impact on application performance. A larger bundle is not only slower to download over the network, but it also requires significantly more work from the browser before the application becomes interactive.

Key Insight: Every kilobyte of JavaScript has a cost that extends far beyond network transfer. The true cost includes parsing, compilation, memory allocation, and execution time—costs that scale with code size regardless of whether that code is ever actually used.

Real-World Impact

Consider these performance implications:

Metric	Impact
Time to Interactive (TTI)	Directly correlated with total JavaScript size
First Contentful Paint (FCP)	Delayed by render-blocking JavaScript
Memory Usage	Each function and variable consumes heap space
Battery Drain	More code = more CPU cycles = more energy
Core Web Vitals	LCP, INP, and CLS all degrade with larger bundles

A study by Google found that 53% of mobile users abandon sites that take longer than 3 seconds to load. Every additional 100KB of JavaScript can add 1-2 seconds of load time on slow mobile connections.

The JavaScript Execution Pipeline

When a browser receives a JavaScript bundle, it goes through a multi-stage pipeline. Understanding this pipeline is essential for grasping why bundle size matters at a fundamental level.

┌─────────────────────────────────────────────────────────┐
│                  Browser JS Pipeline                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│  │ Download │───▶│  Parse   │───▶│ Compile  │          │
│  └──────────┘    └──────────┘    └──────────┘          │
│                                       │                  │
│                                       ▼                  │
│                                  ┌──────────┐           │
│                                  │ Execute  │           │
│                                  └──────────┘           │
│                                                          │
└─────────────────────────────────────────────────────────┘

Download — The bundle is transferred over the network. On a fast connection, this takes milliseconds; on 3G, it can take several seconds per megabyte.
Parse — The JavaScript source code is parsed into an internal representation (AST). This is where hidden costs begin. Parsing is CPU-intensive and scales linearly with code size—even for code that will never execute.
Compile — The JavaScript engine (V8, SpiderMonkey, JavaScriptCore) compiles the parsed code into executable bytecode or optimized machine code via JIT compilation. Unused code still gets compiled if it's reachable in the AST.
Execute — The compiled code is finally executed. Only this stage actually runs your logic, but the previous three stages must process all code first.

Critical Point: Even code that is never executed still consumes resources during parsing and compilation. A 500KB bundle where only 100KB is actually used still requires the browser to parse and compile all 500KB.

The Parse/Compile Tax

Modern JavaScript engines use lazy compilation and tiered compilation to mitigate some costs. V8, for example, first interprets code and only compiles hot functions into optimized machine code. However:

Parsing is not lazy for top-level code — all module-level declarations are parsed immediately
Dead code still occupies memory — parsed AST nodes consume heap space
Garbage collection overhead — unused objects increase GC pressure

This is why modern build tools invest heavily in optimization techniques such as minification, code splitting, and tree shaking. Their shared goal is simple: reduce the amount of JavaScript the browser needs to download and process, resulting in faster startup times, lower memory usage, and a more responsive user experience.

What Is Dead Code?

Dead code refers to code that exists in a program but has no impact on its final behavior. In other words, it is code that is never executed, never referenced, or produces no observable effect.

Consider the following example:

function add(a: number, b: number) {
  return a + b;
}

function subtract(a: number, b: number) {
  return a - b; // ← This function is never called
}

console.log(add(2, 3)); // Only `add` is used

In this example, the subtract function is dead code because there is no execution path that uses it.

Forms of Dead Code

Dead code manifests in several distinct forms:

Type	Description	Example
Unused functions	Functions defined but never called	`function unused() {}`
Unused variables	Variables assigned but never read	`const x = 42;` (never used)
Unused exports	Exported symbols never imported elsewhere	`export function helper() {}`
Unreachable code	Code after `return`, `throw`, or `break`	`return; console.log("hi");`
Dead branches	Conditional branches that can never be true	`if (false) { ... }`
Unused classes	Classes instantiated but never used	`class OldComponent {}`

Unused Exports: The Modern Challenge

Unused exports are especially important in modern JavaScript applications because they represent the primary target for tree-shaking:

// utils.ts
export function formatDate(date: Date) {
  return date.toLocaleDateString();
}

export function formatCurrency(amount: number) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD'
  }).format(amount);
}

export function calculateAge(birthDate: Date) {
  const today = new Date();
  return today.getFullYear() - birthDate.getFullYear();
}

If an application only imports formatDate, the remaining exports formatCurrency and calculateAge become candidates for removal during the bundling process. However, the bundler must be certain that removing them won't change the application's behavior.

Why Removing Dead Code Is Non-Trivial

Removing code is not always straightforward. A bundler must guarantee that deleting a piece of code does not change the observable behavior of the application. This guarantee requires understanding:

Whether the code has side effects
Whether the code is reachable through dynamic patterns
Whether the code modifies shared state
Whether the code registers event handlers or observers

This is where concepts such as static analysis and side effects become critical.

Dead code elimination is one of the fundamental optimizations behind modern bundlers and is the foundation of techniques such as tree shaking.

What Is Tree-Shaking?

Tree-shaking is a build-time optimization technique used by modern JavaScript bundlers to remove unused code from the final bundle. The term was coined by Rollup creator Rich Harris, borrowing from the computer science concept of shaking unused leaves from a tree.

At its core, tree-shaking is based on static analysis. Instead of executing the application, the bundler analyzes the structure of the source code—especially module imports and exports—to determine which parts of the application are actually reachable and required.

How Tree-Shaking Works: A Concrete Example

Consider the following module:

// utils.ts

export function add(a: number, b: number) {
  return a + b;
}

export function subtract(a: number, b: number) {
  return a - b;
}

export function multiply(a: number, b: number) {
  return a * b;
}

And the application that imports from it:

// app.ts

import { add } from "./utils";

console.log(add(1, 2));

Without tree-shaking, the final bundle may contain all three functions—add, subtract, and multiply—even though only add is ever used.

With tree-shaking, the bundler can detect that only add is used and remove subtract and multiply from the final output. The result might look like:

// Bundle output (after tree-shaking)
function add(a, b) {
  return a + b;
}

console.log(add(1, 2));

The Metaphor

The term "tree-shaking" comes from the idea of removing dead branches from a tree. In practice, bundlers do not manipulate a literal tree. Instead, they build a dependency graph and eliminate modules or exports that are not reachable from the application's entry points—much like pruning dead branches from a living tree.

The Tree-Shaking Pipeline

Tree-shaking happens during the build process as part of a larger optimization pipeline:

┌──────────────────┐
│   Source Code    │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│     Bundler      │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Static Analysis │ ◄── Parse imports/exports
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Build Dep Graph │ ◄── Map module relationships
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Tree-Shaking   │ ◄── Mark unused exports
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Code Removal    │ ◄── Strip dead code
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Minification     │ ◄── Compress remaining code
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Optimized Bundle │
└──────────────────┘

Tree-shaking is a specific form of dead code elimination focused on modern module systems, especially ES Modules. It relies on the fact that ES Module imports and exports are statically analyzable, allowing bundlers to determine which code can be safely removed before the application reaches the browser.

Important: Tree-shaking is not magic. It is a deterministic process based on static analysis. If a bundler cannot prove that a piece of code is unused, it will not remove it—regardless of whether that code is actually needed.

Static Analysis: The Engine Behind Tree-Shaking

Static analysis is the process of analyzing source code without executing it. Instead of running the application and observing its behavior, tools inspect the structure of the code to gather information and make decisions before runtime.

Modern JavaScript bundlers rely heavily on static analysis to perform optimizations such as tree-shaking. A bundler needs to determine which modules and exports are actually used, and it must do this before generating the final bundle.

How Static Analysis Works in Practice

Consider the following example:

// math.ts

export function add(a: number, b: number) {
  return a + b;
}

export function subtract(a: number, b: number) {
  return a - b;
}

export function multiply(a: number, b: number) {
  return a * b;
}

// main.ts

import { add } from "./math";

add(2, 3);

By analyzing the import and export relationships, the bundler can determine:

Export	Status	Reason
`add`	✓ Reachable	Imported by `main.ts` and called
`subtract`	✗ Unreachable	Never imported by any module
`multiply`	✗ Unreachable	Never imported by any module

This process can be visualized as:

main.ts
   │
   │  imports { add }
   │
   ▼
math.ts
   │
   ├── add         ✓ reachable (used)
   ├── subtract    ✗ unreachable (unused)
   └── multiply    ✗ unreachable (unused)

The AST Pipeline

Under the hood, static analysis works by transforming source code into an Abstract Syntax Tree (AST):

┌──────────────────┐
│   Source Code    │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│    Tokenizer     │  Split code into tokens
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│     Parser       │  Build AST from tokens
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Static Analysis │  Analyze AST structure
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Optimization   │  Apply transformations
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Bundle Output   │
└──────────────────┘

For example, the expression import { add } from "./math" is parsed into an AST node that explicitly declares:

The import specifier ("./math")
The imported binding (add)
The import type (named import)

This structured representation allows the bundler to track exactly which exports are used across the entire application.

Limitations of Static Analysis

However, JavaScript's dynamic nature creates fundamental limitations. Patterns such as:

Dynamic imports: import("./components/" + componentName)
Runtime module resolution: require(dynamicVariable)
Property access through unknown objects: utils[functionName]()
Conditional requires: if (condition) require("module-a")

...can make it difficult or impossible for a bundler to determine what code will be used ahead of time. In these cases, the bundler must err on the side of caution and include the code in the bundle.

Rule of Thumb: The more static and predictable your import patterns are, the better tree-shaking can work. Dynamic patterns force the bundler to make conservative assumptions.

How the Dependency Graph Is Created

A dependency graph is a directed graph that represents the relationships between modules in an application. It describes which modules depend on other modules through their import statements.

Modern bundlers use this graph to understand the structure of an application and determine which parts of the code are required in the final bundle.

Building the Graph: Step by Step

Consider this application:

// main.ts
import App from "./App";

App();

// App.tsx
import Button from "./Button";
import Modal from "./Modal";

Button();
Modal();

// Button.tsx
export default function Button() {
  return "button";
}

// Modal.tsx
export default function Modal() {
  return "modal";
}

// UnusedComponent.tsx
export default function UnusedComponent() {
  return "unused";
}

The bundler analyzes these imports and creates a graph:

┌──────────┐
│ main.ts  │
└────┬─────┘
     │
     ▼
┌──────────┐
│ App.tsx  │
└────┬─────┘
     │
     ├──────────────┐
     ▼              ▼
┌──────────┐  ┌──────────┐
│ Button   │  │  Modal   │
│  .tsx    │  │  .tsx    │
└──────────┘  └──────────┘


┌────────────────────┐
│ UnusedComponent.tsx│  ← Not connected to the graph
└────────────────────┘

The Graph Construction Process

Start from entry points — The bundler begins with the application's entry point(s) (e.g., main.ts).
Parse the entry module — It identifies all import statements in the entry module.
Resolve dependencies — For each import, the bundler resolves the file path and parses that module.
Recurse — Steps 2-3 repeat for each newly discovered dependency.
Build the complete graph — When no new dependencies are found, the full module graph is complete.

Graph Anatomy

Internally, this graph consists of:

Nodes — Individual modules or files (e.g., main.ts, App.tsx, Button.tsx)
Edges — Relationships between modules, created by import statements

Once the dependency graph exists, the bundler can perform reachability analysis:

main.ts ──▶ App.tsx ──▶ Button.tsx
                 └──▶ Modal.tsx

UnusedComponent.tsx (disconnected)

UnusedComponent.tsx is not connected to the application graph, meaning there is no path from the entry point to that module. Therefore, it can be removed during optimization.

Export-Level Analysis

Modern bundlers can also analyze dependencies at the export level, not only the module level. This allows them to remove individual unused exports from a module while keeping the required ones.

For example, if utils.ts exports add, subtract, and multiply, but only add is imported, the bundler can:

Keep utils.ts in the graph (because some exports are used)
Remove subtract and multiply from the final bundle

This granular analysis is what makes tree-shaking significantly more effective than simply removing entire unused files.

Foundation: The dependency graph is the foundation of many modern bundling optimizations, including tree-shaking, code splitting, and module-level optimization.

Why ES Modules Are Easier to Tree-Shake

Tree-shaking relies on static analysis. In order for a bundler to safely remove unused code, it needs to understand the relationships between imports and exports before the application runs.

This is where ES Modules (ESM) have a significant advantage over CommonJS.

ES Modules: Static by Design

Consider the following ES Module:

// math.ts

export function add(a: number, b: number) {
  return a + b;
}

export function subtract(a: number, b: number) {
  return a - b;
}

// app.ts

import { add } from "./math";

add(2, 3);

The bundler can statically determine that add is used while subtract is not. Because ES Module imports and exports are part of the language syntax and their structure is known ahead of time, they can be analyzed during the build process.

Key characteristics of ES Modules that enable tree-shaking:

Feature	Description
Static syntax	`import`/`export` are declared at the top level, not inside functions or conditions
Static bindings	Import bindings are live read-only views of exports
No runtime mutation	You cannot add new exports after declaration
Fixed specifiers	Import paths must be string literals (not computed)

CommonJS: Dynamic by Nature

CommonJS works differently:

const math = require("./math");

math.add(2, 3);

The require function is dynamic. Its argument can be computed at runtime:

const moduleName = getModuleName();

const module = require(moduleName);

At build time, a bundler cannot always determine which module will be loaded or which exports will be accessed.

Another critical difference is that CommonJS modules can modify their exports dynamically:

// Dynamic property addition
module.exports.newFeature = feature;

// Conditional exports
if (process.env.NODE_ENV === "development") {
  module.exports.debug = true;
}

This dynamic behavior makes it much harder for tools to safely remove unused code.

Side-by-Side Comparison

ES Modules (Static)                CommonJS (Dynamic)
─────────────────────              ─────────────────────
import { add }                     const math = require("./math")
       │                                    │
       ▼                                    ▼
┌─────────────┐                   ┌─────────────────┐
│ Static AST  │                   │ Runtime function │
│ Analysis    │                   │ call - opaque   │
└─────────────┘                   └─────────────────┘
       │                                    │
       ▼                                    ▼
  ✓ Analyzable                    ✗ Hard to analyze
  ✓ Tree-shakeable                ✗ Conservative inclusion

The Bottom Line

ES Modules provide a predictable module structure, static import/export declarations, and analyzable dependency relationships. These characteristics make them the ideal foundation for tree-shaking and other build-time optimizations.

Nuance: CommonJS is not completely impossible to optimize—tools like Webpack perform heuristic analysis on CommonJS patterns. However, ES Modules provide the level of static information that modern bundlers need to perform reliable, comprehensive tree-shaking.

How Rollup, Webpack, and Vite Perform Tree-Shaking

Modern bundlers use similar high-level strategies to perform tree-shaking. They analyze the application's module structure, create a dependency graph, determine which exports are reachable, and remove unused code during the build process.

However, each bundler implements this process differently, with distinct trade-offs and capabilities.

Rollup

Rollup is one of the bundlers most closely associated with tree-shaking. It was designed from the ground up around the ES Module ecosystem and performs static analysis directly on module imports and exports.

// utils.ts
export function add(a: number, b: number) {
  return a + b;
}

export function subtract(a: number, b: number) {
  return a - b;
}

export function multiply(a: number, b: number) {
  return a * b;
}

// main.ts
import { add } from "./utils";

add(2, 3);

Rollup's approach:

Creates a dependency graph starting from the entry point
Marks add as a used export
Detects that subtract and multiply are unreachable
Removes unused exports at the export level (not just module level)

Rollup performs tree-shaking at the export level, allowing it to remove unused parts of a module instead of removing only entire files. This makes it exceptionally effective for libraries with many small exports.

Rollup's Strengths:

ESM-first design with excellent static analysis
Export-level tree-shaking (fine-grained)
Clean, predictable output
Plugin ecosystem focused on ESM

Webpack

Webpack also supports tree-shaking through its optimization pipeline. It builds a module graph, analyzes used exports, and marks unused exports during compilation.

Webpack typically performs a two-phase approach:

Mark phase — During the bundling process, Webpack marks unused exports with a special annotation (/* unused harmony export */)
Remove phase — During minification (commonly using Terser), the marked code is stripped from the output

Webpack Pipeline:

Source ──▶ Build Graph ──▶ Mark Unused ──▶ Minify ──▶ Output
                           Exports        (Terser)

Webpack's Complexity:

Because Webpack provides many runtime features and supports a wide range of module patterns (CommonJS, AMD, ESM, mixed), its analysis can sometimes be more complex than Rollup's. Webpack must also handle:

Code splitting and dynamic imports
Module federation
Runtime module loading
Hot module replacement (HMR)

Webpack 5 Improvements:

Improved sideEffects handling
Better export mangling
Module concatenation (scope hoisting) improvements
Inner graph analysis for better dead code detection

Vite

Vite uses a fundamentally different approach during development:

Development: Instead of bundling, Vite relies on native ES Modules and serves modules directly to the browser. This means no tree-shaking during development—each module is served individually.
Production: Vite uses Rollup internally, so production tree-shaking behavior is based on Rollup's implementation.

Vite Architecture:

Development:              Production:
┌──────────────┐         ┌──────────────┐
│    Vite     │         │    Vite     │
└──────┬───────┘         └──────┬───────┘
       │                        │
       ▼                        ▼
┌──────────────┐         ┌──────────────┐
│ Native ESM   │         │   Rollup    │
│ (no bundle)  │         │ (full build)│
└──────────────┘         └──────┬───────┘
                                │
                                ▼
                         ┌──────────────┐
                         │ Tree-Shaking │
                         └──────┬───────┘
                                │
                                ▼
                         ┌──────────────┐
                         │ Optimized   │
                         │ Bundle      │
                         └──────────────┘

Vite's Advantages:

Near-instant development startup (no bundling overhead)
Production builds leverage Rollup's mature tree-shaking
Excellent developer experience with ESM-native development

Comparison Table

Feature	Rollup	Webpack	Vite
Tree-shaking granularity	Export-level	Export-level	Export-level (via Rollup)
Dev mode	Bundled	Bundled	Native ESM (no bundle)
Production engine	Rollup	Webpack	Rollup
ESM support	Native	Good (v5+)	Native
CJS handling	Limited	Comprehensive	Via Rollup
Config complexity	Low	High	Low
Build speed	Fast	Moderate	Fast

Although these tools have different architectures, they all rely on the same fundamental principles: static analysis, dependency graphs, and the ability to understand ES Module relationships before runtime.

Side Effects: The Silent Tree-Shaking Killer

Tree-shaking is based on a simple assumption: if a piece of code is not used, it can be safely removed.

However, this assumption is not always true. Some code can affect the application even when it does not export anything or is never explicitly called. This is known as a side effect.

What Are Side Effects?

A side effect occurs when executing a piece of code changes something outside of its own scope.

Consider a pure function:

function add(a: number, b: number) {
  return a + b;
}

This function is pure—it only depends on its inputs and produces an output. It doesn't modify anything outside itself, so removing it is safe if it's unused.

However, the following code has a side effect:

console.log("Application started");

The code modifies an external environment by writing to the browser console. Even if no function references this code, removing it would change the application's observable behavior.

Common Side Effects

Side effects appear in many forms:

Category	Examples
Global state mutation	`window.myApp = {}`, `globalThis.config = {}`
DOM manipulation	`document.createElement(...)`, custom element registration
Network requests	`fetch(...)`, `XMLHttpRequest`
Storage access	`localStorage.setItem(...)`, `cookie = "..."`
CSS injection	`import "./styles.css"`, `document.head.appendChild(style)`
Analytics/tracking	`gtag(...)`, `analytics.track(...)`
Polyfills	`if (!Array.prototype.flat) { ... }`
Event listeners	`window.addEventListener("load", ...)`

Why Bundlers Can't Simply Remove Everything

Consider this example:

// setup.ts
initializeAnalytics();
loadPolyfills();
registerServiceWorker();

// app.ts
import "./setup"; // Side-effect-only import

Although setup.ts does not export anything, removing it would break the application because initializeAnalytics() and other initialization code would never execute.

This is why bundlers cannot simply remove every module that doesn't export anything. They must determine whether removing a module is safe.

The `sideEffects` Field in package.json

Package authors can provide additional information to bundlers through the sideEffects field in package.json.

Marking a Package as Side-Effect Free

{
  "sideEffects": false
}

This tells bundlers:

All files in this package are free of side effects and can be safely removed when unused.

This configuration is common for libraries that only provide reusable functions, components, or icons. For example, an icon library:

export function HomeIcon() {
  return <svg>...</svg>;
}

export function SettingsIcon() {
  return <svg>...</svg>;
}

Since rendering an icon doesn't modify global state or perform external operations, unused icons can safely be removed.

Preserving Specific Files

Some packages need to preserve specific files that have side effects:

{
  "sideEffects": [
    "*.css",
    "*.scss",
    "./src/polyfills.js",
    "./src/global-setup.ts"
  ]
}

This tells the bundler that:

JavaScript modules may be tree-shaken
CSS files should always be included (they affect styling)
Specific files with initialization logic must be preserved

Granular Side-Effects Declaration

You can also be more specific:

{
  "sideEffects": [
    "./src/polyfills.js",
    "./src/styles/global.css",
    "./src/setup.ts"
  ]
}

This approach is more precise and gives bundlers the maximum information for optimization.

Function Side Effects vs Module Side Effects

It's important to distinguish between two types of side effects:

Function side effects — A function performs an external action when called:

function saveUser(user: User) {
  localStorage.setItem("user", JSON.stringify(user));
  return user;
}

Module side effects — Code executes immediately when the module is imported:

// This code runs at import time
localStorage.setItem("theme", "dark");
document.body.classList.add("theme-dark");

Tree-shaking mainly needs to consider module-level side effects because they happen automatically during module evaluation. A function with side effects is only problematic if it's actually called—module-level side effects run unconditionally.

Best Practice: Keep side effects isolated in dedicated modules (e.g., setup.ts, polyfills.ts) and declare them in your sideEffects configuration. This makes it easier for bundlers to determine what can be safely removed.

Sub-path Exports and Package Design

Another important factor that affects tree-shaking is how a package exposes its modules.

The Barrel File Problem

Consider a library with many components:

my-library/
├── src/
│   ├── Button.tsx
│   ├── Modal.tsx
│   ├── Table.tsx
│   ├── Input.tsx
│   ├── Select.tsx
│   ├── Tabs.tsx
│   └── ... (100+ components)
└── index.ts          ← Barrel file

A common approach is exposing everything through a single entry point via a barrel file:

// index.ts (barrel file)
export * from "./Button";
export * from "./Modal";
export * from "./Table";
export * from "./Input";
export * from "./Select";
export * from "./Tabs";
// ... 100+ re-exports

The consumer imports from the package root:

import { Button, Modal } from "my-library";

While modern bundlers can optimize this pattern, large barrel files create several problems:

Analysis overhead — The bundler must parse and analyze all 100+ re-exports
Transitive dependencies — Each re-export may pull in its own dependencies
Build time — Larger dependency graphs take longer to process
Incorrect tree-shaking — Some bundlers may struggle with deeply nested re-exports

What Are Sub-path Exports?

Sub-path exports allow a package to expose specific entry points instead of forcing consumers to import everything from the package root.

// Instead of this:
import { Button } from "my-library";

// Consumers can do this:
import Button from "my-library/Button";

The package defines these paths using the exports field in package.json:

{
  "exports": {
    ".": "./dist/index.js",
    "./Button": "./dist/components/Button.js",
    "./Modal": "./dist/components/Modal.js",
    "./Table": "./dist/components/Table.js",
    "./Input": "./dist/components/Input.js",
    "./styles": "./dist/styles.css"
  }
}

Why Sub-path Exports Help Tree-Shaking

Sub-path exports dramatically reduce the amount of information the bundler needs to analyze.

Without sub-path exports:

Application
     │
     ▼
  index.js (barrel)
     │
     ├──▶ Button.js
     ├──▶ Modal.js
     ├──▶ Table.js
     ├──▶ Input.js
     ├──▶ Select.js
     └──▶ ... (100+ modules)

The bundler starts from a large entry point and must analyze all exported modules, even if only one is used.

With sub-path exports:

Application
     │
     ▼
  Button.js (direct import)

The dependency graph starts dramatically smaller, and the bundler immediately knows which module is required. There's no barrel file to parse, no re-exports to analyze, and no unnecessary modules to consider.

Path Patterns

Modern exports configuration supports patterns for scalability:

{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./components/*": {
      "import": "./dist/components/*.js"
    },
    "./icons/*": {
      "import": "./dist/icons/*.js"
    },
    "./styles/*": {
      "import": "./dist/styles/*"
    }
  }
}

This allows consumers to import specific components without the package needing to enumerate every possible export.

What Breaks Tree-Shaking?

Tree-shaking is a powerful optimization technique, but it is not guaranteed to work in every situation. Bundlers can only remove unused code when they have enough information about module relationships and when removing code is proven to be safe.

1. Using CommonJS Instead of ES Modules

The Problem:

const utils = require("./utils");

utils.add(2, 3);

Because require() is a runtime function, a bundler cannot always determine which exports will be used before execution.

The Fix:

import { add } from "./utils";

add(2, 3);

ES Modules provide static import and export declarations, making them much easier to analyze.

2. Large Barrel Files

The Problem:

// index.ts - 200+ re-exports
export * from "./Button";
export * from "./Modal";
export * from "./Table";
export * from "./Input";
export * from "./Select";
export * from "./Tabs";
export * from "./Accordion";
export * from "./Alert";
// ... many more

Large chains of re-exports make dependency analysis more complicated and can slow down builds.

The Fix:

Use sub-path exports: import Button from "my-library/Button"
Keep barrel files small and focused
Split large packages into smaller, focused packages

3. Incorrect Side Effects Configuration

The Problem:

{
  "sideEffects": false
}

This is incorrect for a package that imports global CSS or performs initialization during module loading. The bundler will incorrectly remove code that has side effects.

The Fix:

{
  "sideEffects": ["*.css", "./src/polyfills.js"]
}

4. Namespace Imports

The Problem:

import * as utils from "./utils";

utils.add(2, 3);
utils.subtract(5, 3);

Since the entire namespace object is imported, the bundler may have less information about which individual exports are actually required. Some bundlers treat namespace imports conservatively.

The Fix:

import { add, subtract } from "./utils";

add(2, 3);
subtract(5, 3);

Named imports give the bundler explicit information about which exports are used.

5. Dynamic Module Access

The Problem:

const componentName = getComponentName(); // Runtime value
const Component = await import(`./components/${componentName}`);

Because the final module path is only known at runtime, the bundler may need to include all possible modules that could match the pattern.

The Fix:

import { Button } from "./components/Button";
import { Modal } from "./components/Modal";
import { Table } from "./components/Table";

const componentMap = { Button, Modal, Table };
const Component = componentMap[componentName];

Static import maps allow the bundler to analyze all possible components.

6. CommonJS Output From Library Builds

The Problem:

// Source (ESM)
export function Button() {}

// Compiled output (CJS - tree-shaking info lost!)
exports.Button = Button;

If a library compiles to CommonJS, much of the static information required for tree-shaking is lost.

The Fix:

Ensure your build configuration produces ESM output:

{
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

7. Class Side Effects

The Problem:

export class Analytics {
  constructor() {
    // Side effect at instantiation
    window.analytics = this;
  }

  track(event: string) {
    // ...
  }
}

Even if Analytics is imported but never instantiated, some bundlers may not remove it because the class definition itself could have side effects.

The Fix:

// Separate the side effect from the logic
export class Analytics {
  track(event: string) {
    // ...
  }
}

// Explicit initialization module
// setup.ts
import { Analytics } from "./Analytics";
window.analytics = new Analytics();

Measuring the Impact

Tree-shaking isn't just a theoretical optimization—it has measurable, real-world impact on application performance.

Before and After Example

Consider a typical application using a UI library:

Before tree-shaking:

Total bundle size: 450 KB
├── UI Library: 320 KB (all components included)
├── App code: 80 KB
└── Dependencies: 50 KB

After tree-shaking:

Total bundle size: 180 KB
├── UI Library: 60 KB (only used components)
├── App code: 80 KB
└── Dependencies: 40 KB (unused helpers removed)

Result: 60% reduction in bundle size

Performance Metrics

Metric	Before	After	Improvement
Bundle size	450 KB	180 KB	-60%
Parse time (mobile)	800ms	320ms	-60%
Compile time	400ms	160ms	-60%
TTI (3G)	8.2s	3.4s	-59%
Memory usage	45MB	22MB	-51%

How to Measure

You can measure the impact of tree-shaking using these tools:

Bundle Analyzer — Visualize what's in your bundle:

   # For Webpack
   npx webpack-bundle-analyzer stats.json

   # For Vite/Rollup
   npx rollup-plugin-visualizer

Lighthouse — Measure performance impact:

   npx lighthouse https://your-app.com --output json

Chrome DevTools — Analyze parse/compile time:
- Open Performance tab
- Record a page load
- Check "JavaScript Compilation" in the timeline
Source Map Explorer — See which modules contribute most:

   npx source-map-explorer build/static/js/*.js

Advanced Techniques and Modern Alternatives

Module Concatenation (Scope Hoisting)

Module concatenation, also known as scope hoisting, is an optimization that puts multiple modules into a single function scope instead of wrapping each module in a separate function wrapper.

Without scope hoisting:

// Each module wrapped in a function
var module_a = (function() {
  var exports = {};
  // module a code
  return exports;
})();

var module_b = (function() {
  var exports = {};
  // module b code
  return exports;
})();

With scope hoisting:

// All modules in one scope
// module a code
// module b code

This reduces bundle size (no function wrappers), improves runtime performance (fewer function calls), and enables better optimization by the JavaScript engine.

Dynamic Import and Code Splitting

While tree-shaking removes unused code, code splitting breaks the bundle into smaller chunks that are loaded on demand:

// Route-based code splitting
const Dashboard = lazy(() => import("./pages/Dashboard"));
const Settings = lazy(() => import("./pages/Settings"));

Code splitting and tree-shaking work together:

Tree-shaking removes unused code from each chunk
Code splitting ensures users only download what they need
Combined, they dramatically reduce initial load time

Turbopack and Next.js

Turbopack, Vercel's new bundler (successor to Webpack for Next.js), promises even faster builds and optimizations:

Incremental computation for faster rebuilds
Native Rust-based architecture
Improved tree-shaking through better module analysis

While still evolving, Turbopack represents the next generation of bundler optimization.

esbuild and SWC

esbuild (used by Vite for dev) and SWC (used by Next.js) are fast transpilers that can also perform some optimization:

esbuild: Extremely fast bundling but limited tree-shaking compared to Rollup
SWC: Fast compilation with improving optimization capabilities

These tools are often used alongside traditional bundlers to speed up the build process while delegating tree-shaking to more mature tools.

Debugging Tree-Shaking Issues

When tree-shaking doesn't work as expected, follow this debugging process:

Step 1: Check Your Bundle Output

# Generate bundle with stats
npx webpack --json > stats.json
# or
npx vite build --mode production

Step 2: Analyze the Bundle

# Visualize bundle contents
npx rollup-plugin-visualizer
# or
npx webpack-bundle-analyzer stats.json

Step 3: Check for Common Issues

Is your package using ESM?

   # Check package.json
   cat package.json | grep -E '"type"|"module"'

Is sideEffects configured correctly?

   # Check for sideEffects field
   cat package.json | grep sideEffects

Are you using named imports?

   // ✗ Bad - namespace import
   import * as lib from "library";

   // ✓ Good - named import
   import { specific } from "library";

Are there dynamic imports?

   # Search for dynamic patterns
   grep -r "import(" src/

Step 4: Use Bundle Analyzer

The bundle analyzer will show you exactly what's included in your bundle and where it comes from. Look for:

Unexpected large modules
Duplicate dependencies
Modules you expected to be removed
Dependencies with many unused exports

Common Debugging Commands

# Webpack stats
npx webpack --stats detailed

# Rollup with verbose output
npx rollup -c --verbose

# Vite build with analysis
npx vite build --mode production && npx vite-bundle-visualizer

Common Misconceptions

Misconception 1: "Tree-Shaking Removes Entire Unused Files"

Reality: Tree-shaking operates at the export level, not just the module level. It can remove individual unused exports from a module while keeping the used ones. However, if a module is imported for its side effects, it will be kept entirely.

Misconception 2: "Tree-Shaking Works Automatically"

Reality: Tree-shaking requires:

ESM format (or CommonJS with heuristic analysis)
Correct sideEffects configuration
Static import patterns
Proper bundler configuration

Without these, tree-shaking may be partially or completely ineffective.

Misconception 3: "Tree-Shaking Eliminates All Dead Code"

Reality: Tree-shaking can only remove code that the bundler can prove is unused through static analysis. Dynamic patterns, side effects, and complex control flow can prevent tree-shaking from removing code that appears unused.

Misconception 4: "Smaller Bundle = Better Performance"

Reality: While bundle size matters, other factors also affect performance:

Code complexity — A small but computationally expensive function can be slower than a larger, simpler one
Network conditions — On fast networks, bundle size matters less
Caching — A larger cached bundle may be faster than a smaller uncached one
Parsing overhead — Some code structures are harder to parse than others

Misconception 5: "Tree-Shaking Is the Same as Dead Code Elimination"

Reality: Tree-shaking is a specific type of dead code elimination focused on ES Modules. Traditional dead code elimination (DCE) removes unreachable code within a module, while tree-shaking removes unused exports across modules.

Best Practices Checklist

For Application Developers

[ ] Use ESM syntax (import/export) instead of CommonJS (require)
[ ] Use named imports instead of namespace imports
[ ] Avoid dynamic import patterns when possible
[ ] Analyze your bundle regularly with visualizers
[ ] Configure your bundler's sideEffects option
[ ] Use code splitting for route-based loading
[ ] Keep barrel files small and focused
[ ] Remove unused dependencies from package.json

For Library Authors

[ ] Ship ESM output (in addition to CJS if needed)
[ ] Set "sideEffects": false in package.json (if applicable)
[ ] Configure exports field for sub-path imports
[ ] Avoid global side effects in module initialization
[ ] Keep barrel files minimal or provide sub-path exports
[ ] Test tree-shaking with bundle analyzers
[ ] Document which files have side effects
[ ] Use package.json exports for conditional imports

Example: Well-Configured Library

{
  "name": "my-library",
  "type": "module",
  "sideEffects": ["*.css", "./src/polyfills.js"],
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./Button": {
      "import": "./dist/components/Button.js"
    },
    "./Modal": {
      "import": "./dist/components/Modal.js"
    },
    "./icons/*": {
      "import": "./dist/icons/*.js"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

Conclusion

Tree-shaking is more than just a technique for removing unused code. It is the result of multiple concepts working together: static analysis, dependency graphs, module systems, and thoughtful package design.

The Core Problem

Modern applications contain a large amount of code, but users only need a small portion of it. Shipping unnecessary code increases bundle size and negatively affects application performance—from network transfer to parsing, compilation, memory usage, and battery drain.

How the Ecosystem Solves It

To solve this problem, bundlers analyze the structure of an application before runtime:

Build a dependency graph from entry points
Identify reachable modules and exports through static analysis
Remove unreachable code that cannot affect the final application
Minify remaining code to reduce size further

The Role of ES Modules

ES Modules play a critical role in this process because their static structure allows bundlers to understand imports and exports during the build phase. This is why modern optimization strategies are designed around ESM rather than dynamic module systems such as CommonJS.

The Collaboration

Effective tree-shaking represents a collaboration between tooling and code architecture:

Bundlers provide the optimization engine
Library authors provide the static information needed for optimization
Application developers configure the build pipeline correctly

The better a project exposes its structure, the more opportunities modern bundlers have to produce smaller, faster, and more efficient bundles.

Looking Forward

As the JavaScript ecosystem continues to evolve, tree-shaking will become even more sophisticated:

Better static analysis through improved AST handling
Smarter side-effects detection through type information
Faster builds through tools like Turbopack and esbuild
More granular optimization through module-level code generation

Understanding tree-shaking today means understanding the future of web performance. It's not just about removing dead code—it's about building applications that are efficient, performant, and respectful of users' resources.

Final Thought: Tree-shaking is a reminder that in software engineering, what you don't ship is just as important as what you do. The best code is the code that never reaches the user's browser.

A Deep Dive into Git: Understanding Commits, Merges, and Rebases

Vahid Ghadiri — Mon, 14 Jul 2025 12:58:35 +0000

Introduction

Git, a powerful distributed version control system, manages project history through snapshots called commits. Operations like merging and rebasing allow developers to combine or reorganize these snapshots to suit collaboration and maintenance needs. This article explores the internal mechanics of Git's commits, merges, and rebases, diving into the object model (commits, trees, and blobs), the three-way merge algorithm, and how rebasing rewrites history. By understanding these concepts, developers can master Git workflows, resolve conflicts, and maintain clean project histories.

What is a Commit in Git?

A commit in Git represents a snapshot of your project's state at a specific point in time. Stored as an immutable commit object, it’s identified by a unique SHA-1 hash (or SHA-256 in newer configurations). A commit object contains:

A pointer to a tree object, capturing the directory structure and file contents.
Pointers to one or more parent commits, forming a directed acyclic graph (DAG).
Metadata: author name, email, timestamp, and committer information.
A commit message describing the changes.

For example:

commit 3f1d2ab273...
tree ab2e3r1c0b...
parent 7ba3f1c0b2...
author Jane Doe <jane@example.com> 1624392390 +0100
committer Jane Doe <jane@example.com> 1624392390 +0100
Add feature X

This immutability ensures the integrity of your project’s history, making Git reliable for collaboration and auditing.

Understanding Git’s Object Model

Git’s efficiency stems from its object model, consisting of three primary types: commits, trees, and blobs.

Commit Object

The commit object ties together the project’s state and history. It references a tree object, parent commits, and metadata, stored in the .git/objects directory, identified by its SHA-1 hash.

Tree Object

A tree object represents a directory snapshot, containing:

References to blob objects (files).
References to other tree objects (subdirectories).
Metadata, such as filenames and permissions (e.g., 100644 for regular files, 100755 for executables).

For example:

100644 blob a789c3d... README.md
100644 blob b4e42f1... index.js
040000 tree b3db2a6... src

Trees allow Git to reconstruct the project’s file structure at any commit.

Blob Object

A blob (binary large object) stores a file’s raw content, excluding metadata like filenames. Identical file contents share the same blob, enabling deduplication. Blobs are stored in .git/objects, identified by their SHA-1 hash.

This object model ensures efficient storage, deduplication, and fast retrieval, making Git scalable for large projects.

Merging: Combining Branches

Merging combines changes from two branches, preserving their history. Git typically uses the three-way merge algorithm.

Three-Way Merge

When merging a feature branch into main, Git:

Identifies the merge base (common ancestor commit).
Computes differences from the merge base to the heads of both branches.
Combines these differences into a new snapshot.
Creates a merge commit with two parents, referencing both branch heads.

For example, consider this DAG:

A --- B --- C (main)
       \
        D --- E (feature)

Running:

git checkout main
git merge feature

Results in:

A --- B --- C --- M (main)
       \         /
        D --- E (feature)

Here, M is the merge commit, with parents C and E, and B is the merge base. If conflicts arise, Git pauses, marks conflicting files, and requires manual resolution before committing.

Fast-Forward Merge

If main has no unique commits since the merge base, Git performs a fast-forward merge, moving the main pointer to the feature head without a merge commit:

A --- B --- D --- E (main, feature)

Rebasing: Rewriting History

Rebasing rewrites history by replaying commits from one branch onto another, creating a linear history without merge commits. For example:

git checkout feature
git rebase main

Given:

A --- B --- C (main)
       \
        D --- E (feature)

Git:

Identifies the common ancestor (B).
Creates patches for each commit in feature (D and E).
Moves the feature branch to the tip of main (C).
Applies the patches, creating new commits (D' and E') with new hashes.
Updates feature to point to E':

A --- B --- C --- D' --- E' (feature)

The original D and E commits become unreachable unless referenced elsewhere.

Visualizing Rebase

Before rebase:

A --- B --- C (main)
       \
        D --- E (feature)

After rebase:

A --- B --- C --- D' --- E' (feature)

This linear history is cleaner but rewrites commit hashes, which can complicate collaboration if the branch is already shared.

Three-Way Merge in Detail

The three-way merge algorithm involves:

Identify the Merge Base: Find the common ancestor (e.g., B).
Compute Differences:
- diff(B → C) for main.
- diff(B → E) for feature.
Combine Changes: Merge differences into a new snapshot, resolving conflicts if needed.
Create Merge Commit: Generate a new commit (M) with two parents (C and E) and a tree reflecting the combined state.

Practical Commands for Exploration

To dive into Git’s internals, try these commands:

View a commit object:

  git cat-file -p HEAD

View a tree object:

  git cat-file -p <tree-hash>

Visualize the commit graph:

  git log --oneline --graph --all

List all objects:

  git rev-list --objects --all

Key Takeaways

Commits are immutable snapshots with metadata and parent pointers, stored as commit objects.
Git’s object model (commit, tree, blob) enables efficient storage and deduplication.
Merge combines branches, preserving history with merge commits or fast-forwarding.
Rebase rewrites history for a linear look, creating new commits with new hashes.
The three-way merge algorithm relies on the common ancestor to combine changes.
Understanding these mechanics improves control over Git workflows, conflict resolution, and history management.

Final Thoughts

Git’s merge and rebase operations, built on its robust object model, provide powerful tools for shaping project history. By mastering commits, merges, and rebases, developers can navigate complex workflows, resolve conflicts efficiently, and maintain clean histories. Commands like git log --graph and git cat-file reveal Git’s elegant design, empowering you to leverage its full potential for collaboration and project management.

Additional Resources

Official Git Documentation
Pro Git Book by Scott Chacon and Ben Straub
Git Internals Documentation

A Deep Dive into Git Internals: Blobs, Trees, and Commits

Vahid Ghadiri — Mon, 07 Jul 2025 04:30:41 +0000

1. Introduction

Have you ever wondered what’s happening under the hood when you run git commit? Git is far more than a version control system—it’s a content-addressable filesystem built on a robust object model. At its core, Git manages your codebase using four primary object types: blobs, trees, commits, and tags. This article dives deep into the three most critical components of Git’s commit history—commit objects, tree objects, and blob objects—to give you a clear, hands-on understanding of how Git organizes and stores your code.

Whether you’re a beginner curious about Git’s magic or a seasoned developer looking to master its internals, this guide will demystify Git’s architecture with practical examples and insights. Let’s explore how Git transforms your files into a structured, efficient, and resilient database.

2. Git as a Content-Addressable Filesystem

At its heart, Git is a content-addressable filesystem, meaning it identifies and stores data based on its content rather than its location or name. Every piece of data—whether a file, directory, or commit—is assigned a unique SHA-1 hash (or SHA-256 in newer Git versions) derived from its contents. These hashes act as fingerprints, ensuring that even a tiny change in content produces a completely different hash.

Git stores these objects in the .git/objects directory, where they are compressed using zlib to save space. The hash serves as both the object’s identifier and its address in the filesystem, making Git’s storage system efficient and deduplicated.

Try It Out

To see this in action, let’s create a simple object:

echo "hello world" | git hash-object -w --stdin

This command generates a SHA-1 hash for the string "hello world", stores it as a blob in .git/objects, and outputs the hash (e.g., 557db03...). The -w flag tells Git to write the object to its database. You’ll find the object in a subdirectory named after the first two characters of the hash (e.g., .git/objects/55/7db03...).

This hash-based system ensures that identical content is stored only once, regardless of how many times it appears in your repository’s history.

3. Blob Internals: Storing File Content

A blob (binary large object) is the simplest Git object. It stores the raw content of a file—nothing more, nothing less. Blobs don’t care about file names, permissions, or directory structures; they’re just a snapshot of a file’s contents at a given moment.

Blob Format

A blob is stored with a simple header:

blob <content-length>\0<actual-content>

For example, a file containing console.log('Hi') would be stored as:

blob 17\0console.log('Hi')

Example: Adding a File

Let’s create a file and see how Git handles it:

echo "console.log('Hi')" > index.js
git add index.js
git hash-object index.js

Running git hash-object index.js will output the SHA-1 hash of the blob (e.g., 7b19fa88dd...). To inspect the blob, use:

git cat-file -t 7b19fa88dd    # Outputs: blob
git cat-file -s 7b19fa88dd    # Outputs: size (e.g., 17)
git cat-file -p 7b19fa88dd    # Outputs: console.log('Hi')

Why It Matters

Blobs are immutable and content-addressed. If you commit the same index.js file in multiple commits without changing its content, Git reuses the same blob, saving space. This deduplication is a cornerstone of Git’s efficiency.

Pro Tip: If you rename a file but don’t change its content, Git still references the same blob, as the file’s name is stored elsewhere (in tree objects).

4. Tree Internals: Mapping the Directory Structure

While blobs store file content, tree objects represent the directory structure of your project. A tree is like a snapshot of a folder, listing its contents—files (blobs) and subdirectories (other trees)—along with metadata like file names and permissions.

Tree Format

Each entry in a tree object includes:

File Mode: Permissions, e.g., 100644 for a regular file, 100755 for an executable, or 040000 for a subdirectory.
Object Type: Either blob (for files) or tree (for subdirectories).
SHA-1 Hash: The hash of the referenced blob or tree.
Filename: The name of the file or directory.

For example, a tree might look like this:

100644 blob a3c1f80e3d README.md
100644 blob 7b19fa88dd index.js
040000 tree b12fc09b8d src

This tree represents a directory with two files (README.md and index.js) and a subdirectory (src).

Example: Inspecting a Tree

To explore a tree, first find the hash of a commit’s root tree (more on commits later), then use:

git ls-tree <tree-hash>
git cat-file -p <tree-hash>

The git ls-tree command lists the tree’s contents in a human-readable format, while git cat-file -p shows the raw structure.

Why It Matters

Trees are the glue that connects blobs into a coherent project structure. They allow Git to track directories and their contents, enabling snapshots of your entire codebase at any point in time.

Pro Tip: Trees are also deduplicated. If two commits reference identical directory structures, Git reuses the same tree object, further optimizing storage.

5. Commit Internals: Capturing Snapshots

A commit object is the heart of Git’s history. It represents a snapshot of your project at a specific point in time, tying together the root tree, metadata, and references to previous commits.

Commit Structure

A commit object contains:

tree: The SHA-1 hash of the root tree, representing the entire project’s directory structure.
parent(s): The hash(es) of the parent commit(s). A merge commit has multiple parents.
author: The person who wrote the code (name and email).
committer: The person who created the commit (may differ during rebases or cherry-picks).
message: The commit message describing the changes.
timestamp: When the commit was made.

Example: Anatomy of a Commit

Here’s what a commit object looks like:

commit 3f1d2ab273...
tree a8e23f1c0b...
parent 72ba9fc012...
author Vahid <vahid@example.com> 1697059200 +0000
committer Vahid <vahid@example.com> 1697059200 +0000
Fix broken user registration logic

To inspect a commit:

git cat-file -p <commit-hash>

Key Insight

Commits don’t store diffs! Instead, they reference a tree that represents the full state of your project. When you view a diff (e.g., with git diff), Git computes it on the fly by comparing trees.

Pro Tip: The distinction between author and committer is subtle but important. For example, during a git rebase, the committer might change (you, applying the rebase), while the author remains the original coder.

6. The DAG: Directed Acyclic Graph

Git’s history is structured as a Directed Acyclic Graph (DAG), where each commit points to its parent(s). This structure enables powerful features like branching, merging, and history traversal.

Visualizing the DAG

Here’s a simple commit history:

* d3e45f2 (HEAD -> main) Update footer text
* c1b8fa2 Add new logo
* b5e4fa1 Initial commit

To see the DAG in action:

git log --oneline --graph --all

This command displays a visual representation of your commit history, showing branches and merges as a graph.

Why It Matters

The DAG makes Git’s history flexible and robust. Branching is just a pointer to a commit, and merging creates a new commit with multiple parents. Understanding the DAG helps you navigate complex histories and resolve merge conflicts with confidence.

Pro Tip: Use git log --graph with --pretty=fuller to see detailed commit metadata alongside the graph.

7. Compression and Packfiles: Optimizing Storage

Initially, Git stores objects as individual files in .git/objects. Over time, as your repository grows, Git optimizes storage by creating packfiles using the git gc (garbage collection) command.

Packfiles: Objects are delta-compressed into .pack files, storing only the differences between similar objects to save space.
Index Files: .idx files act as an index for quick access to objects in the packfile.

Example: Inspecting Packfiles

After running git gc, check the packfiles:

git verify-pack -v .git/objects/pack/pack-<hash>.idx

This command lists the objects in the packfile, showing their relationships and compression details.

Why It Matters

Packfiles significantly reduce disk usage, especially in large repositories with many similar files or commits. They’re why Git can store years of project history efficiently.

Pro Tip: Run git gc manually to optimize your repository, but be cautious—it’s a one-way process, and objects may become harder to inspect individually.

8. Inspecting Git Internals with Plumbing Commands

Git provides two types of commands: porcelain (user-friendly, like git add or git commit) and plumbing (low-level, for scripting and debugging). Plumbing commands let you peek into Git’s internals.

Key Plumbing Commands

git hash-object -w <file>: Computes the SHA-1 hash of a file and optionally writes it to .git/objects.
git cat-file -p <hash>: Displays the content of an object (blob, tree, or commit).
git ls-tree <tree-hash>: Lists the contents of a tree object.
git rev-list --objects --all: Lists all objects in the repository’s history.

Example: Exploring Your Repository

Find a commit hash with git log, then:

git cat-file -p <commit-hash>  # View commit details
git ls-tree <tree-hash>        # View the root tree
git cat-file -p <blob-hash>    # View a file’s content

Why It Matters

Plumbing commands are your toolkit for debugging and understanding Git’s behavior, especially during complex operations like rebases or recovering lost commits.

Pro Tip: Use git rev-parse HEAD to get the hash of the current commit, then explore its tree and blobs.

9. Putting It All Together

When you run git commit, Git performs a series of steps to create a snapshot of your project:

Creates Blobs: Each modified file is hashed and stored as a blob in .git/objects.
Builds Trees: Git constructs tree objects to represent the directory structure, linking to blobs and subtrees.
Creates a Commit: A commit object is created, referencing the root tree, parent commits, and metadata like the author and message.

Visual Summary

commit ---> tree ---> blobs
  |           |-- README.md
  |           |-- index.js
  |           +-- src/ (tree) ---> blobs (file1.js, file2.js)

This structure ensures that every commit is a complete, immutable snapshot of your project.

Pro Tip: To visualize this, run git log --oneline --graph and then use git cat-file -p on a commit to trace its tree and blobs.

10. Bonus: Snapshot vs. Diff — A Practical Demonstration

To understand Git’s snapshot-based approach, let’s try a hands-on example:

Create and commit a file:

echo "hello world" > hello.txt
git add hello.txt
git commit -m "Add hello"

Modify the file and recommit:

echo "hello again" > hello.txt
git add hello.txt
git commit -m "Change hello"

Compare the blobs:

git log --oneline  # Find the commit hashes
git cat-file -p <first-commit-hash>  # Get the tree hash
git ls-tree <tree-hash>  # Get the blob hash for hello.txt
git cat-file -p <blob-hash>  # Outputs: hello world

Repeat for the second commit’s blob to see the new content (hello again). Notice that the two blobs have different hashes because their content changed, but unchanged files would reuse the same blob.

Why It Matters

Git’s snapshot-based model (not diff-based) means it stores the full state of your project for each commit. Diffs are computed on demand, which makes operations like git blame or git diff flexible but computationally intensive.

Pro Tip: Use git diff <commit1> <commit2> to see how Git computes differences between two snapshots.

11. Key Takeaways

Commits are snapshots, not diffs, referencing a root tree that captures the entire project state.
Trees organize the directory structure, linking to blobs and subtrees.
Blobs store raw file content, independent of names or permissions.
Git’s content-addressable storage and DAG enable efficient deduplication and history manipulation.
Plumbing commands like git cat-file, git ls-tree, and git rev-list unlock Git’s internals for debugging and exploration.
Understanding these concepts helps you tackle merge conflicts, optimize rebases, and recover lost data with confidence.

12. Final Thoughts

Git’s object model—blobs, trees, and commits—transforms it into a powerful, content-addressable database. By storing data as immutable, hash-addressed objects, Git ensures efficiency, resilience, and flexibility. The next time you run git commit, take a moment to appreciate the elegant machinery at work: a deduplicated, compressed, and perfectly organized snapshot of your project’s history.

Mastering Git’s internals not only makes you a better developer but also empowers you to wield Git’s full potential, from resolving complex merge conflicts to scripting custom workflows.

13. Further Exploration

Read the official Git Internals Book: Git Internals - Plumbing and Porcelain
Read the Pro Git Book: Pro Git - Scott Chacon, Ben Straub

JavaScript's Asynchronous Execution: V8 and the Event Loop

Vahid Ghadiri — Fri, 04 Jul 2025 18:43:15 +0000

Abstract

JavaScript's asynchronous behavior is a cornerstone of its power, enabling non-blocking code in a single-threaded environment. Constructs like setTimeout, Promise, and async/await are widely used, yet their internal mechanisms remain opaque to many developers. This article explores the interplay between the V8 JavaScript engine and the Event Loop, facilitated by libuv in Node.js or Blink in browsers, through internal C++ interfaces. We aim to clarify how the Call Stack, Event Loop, Task Queue, and Microtask Queue collaborate, and detail how V8 handles asynchronous code execution, with practical examples and performance insights.

1. Introduction

JavaScript operates on a single thread but supports asynchronous operations via callbacks, events, and promises. These are orchestrated through a system comprising the Call Stack, Event Loop, Task Queue, and Microtask Queue. The V8 engine, developed by Google, executes JavaScript efficiently but delegates asynchronous operations (e.g., timers, file I/O) to the hosting environment, such as browsers (using Blink) or Node.js (using libuv). In Node.js, libuv—a cross-platform C library for asynchronous I/O, timers, and networking—manages these operations and interfaces with V8.

This article dissects how V8's C++ APIs enable runtimes to inject asynchronous tasks into JavaScript’s execution flow. We examine key components like v8::Isolate, v8::Context, and v8::Function::Call, and illustrate their roles in coordinating asynchronous lifecycles in browsers and Node.js, with practical examples and performance considerations.

1.1 Basics

For those new to JavaScript, understanding asynchronous execution starts with a few core concepts:

Synchronous vs. Asynchronous: Synchronous code runs sequentially, blocking further execution until complete (e.g., a for loop). Asynchronous code, like setTimeout or fetch, allows other tasks to run while waiting for an operation (e.g., a network request) to complete.
Callback: A function passed as an argument to another function, executed later when an event occurs (e.g., a timer finishing).
Promise: An object representing the eventual completion (or failure) of an asynchronous operation, allowing chaining with .then() or .catch().
Async/Await: Syntactic sugar over Promises, making asynchronous code look synchronous (e.g., await fetch()).

These concepts form the foundation for understanding how JavaScript handles non-blocking operations, which we explore in detail below.

2. Core Components of the Event Loop Architecture

2.1 V8’s Execution Model

V8’s Call Stack manages execution contexts for synchronous code. When asynchronous operations (e.g., setTimeout) are encountered, V8 delegates their handling to the runtime environment, which schedules and later re-injects callbacks into the Call Stack.

2.2 The Runtime Environment

The runtime environment—either a browser (e.g., Chrome with Blink) or Node.js (with libuv)—provides APIs for asynchronous tasks. These environments use V8’s C++ interfaces to communicate execution states and schedule callbacks.

2.3 Task Queues

Task Queue: Holds macrotasks, such as callbacks from timers, I/O operations, or DOM events, as defined in the HTML Living Standard (updated 2025).
Microtask Queue: Manages microtasks, such as Promise resolutions or queueMicrotask callbacks, executed before macrotasks.

2.4 Event Loop Visualization

Imagine the Event Loop as a conductor orchestrating tasks:

The Call Stack is a stack of function calls being executed.
The Task Queue holds macrotasks waiting to be processed.
The Microtask Queue holds high-priority tasks (e.g., Promises).
The Event Loop continuously checks if the Call Stack is empty, then processes Microtask Queue items first, followed by Task Queue items, ensuring smooth execution.

3. V8 Internal Interfaces: Bridging Runtime and Engine

3.1 v8::Isolate

An v8::Isolate is an isolated execution environment in V8, encapsulating the Call Stack, Heap, and runtime state. It acts as a lightweight virtual machine for JavaScript execution.

Runtime Usage: Runtimes use v8::Isolate::IsExecutionTerminating to check if the Call Stack is idle, enabling task scheduling when appropriate.

3.2 v8::Context

A v8::Context defines the global environment (e.g., scope, this, global objects) for JavaScript execution.

Activation: Runtimes call v8::Context::Enter and v8::Context::Exit to set the execution context before and after invoking callbacks.

3.3 v8::Function::Call

This API invokes JavaScript callbacks within the Call Stack, creating a new execution context for the function.

Usage: When a timer expires, the Event Loop uses v8::Function::Call to execute the callback in the correct v8::Context.

3.4 v8::MicrotaskQueue

The v8::MicrotaskQueue manages microtasks (e.g., Promise.then handlers). The v8::MicrotaskQueue::PerformCheckpoint method ensures all microtasks are executed at specific points, such as after a macrotask or before browser rendering.

3.5 v8::Task and v8::TaskRunner

These interfaces allow runtimes to schedule macrotasks (e.g., timer callbacks). In Node.js, libuv uses v8::TaskRunner to queue tasks when timers or I/O operations complete.

4. Practical Flow: How Asynchronous Code Executes

Consider this example:

console.log("Start");
setTimeout(() => {
  console.log("Callback executed");
}, 1000);
console.log("End");

Step-by-Step Execution:

Synchronous Execution by V8:
- Prints "Start".
- setTimeout is called; V8 delegates timer scheduling to the runtime (Blink/libuv), which stores the callback as a JavaScript object in V8’s heap (managed by the garbage collector) and sets a 1000ms timer.
- Prints "End".
- Call Stack becomes empty.
Timer Handling by Runtime:
- After 1000ms, the runtime pushes the callback to the Task Queue.
Event Loop Operation:
- The Event Loop checks if the Call Stack is empty using v8::Isolate.
- It dequeues the callback from the Task Queue.
- Uses v8::Function::Call to execute the callback in the correct v8::Context.
Callback Execution by V8:
- Prints "Callback executed".

5. Advanced Examples

5.1 Promise vs. setTimeout

Consider this code:

console.log("Start");

setTimeout(() => {
  console.log("setTimeout Callback");
}, 0);

Promise.resolve().then(() => {
  console.log("Promise Callback");
});

console.log("End");

Expected Output:

Start
End
Promise Callback
setTimeout Callback

Explanation:

When Promise.resolve().then() is called, V8 creates a v8::Promise object in the heap within the current v8::Isolate, which encapsulates the JavaScript execution environment. The .then callback is registered as a microtask in the v8::MicrotaskQueue associated with the v8::Isolate.
For setTimeout(..., 0), V8 delegates the timer to the runtime (Blink in browsers or libuv in Node.js). The runtime schedules the callback using a v8::Task object and enqueues it in the Task Queue via v8::TaskRunner.
The Event Loop, implemented by the runtime, checks the Call Stack’s state using v8::Isolate::IsExecutionTerminating. When the Call Stack is empty (after console.log("End")), the Event Loop calls v8::MicrotaskQueue::PerformCheckpoint to execute all microtasks (printing "Promise Callback") before dequeuing macrotasks from the Task Queue.
The setTimeout callback is then invoked using v8::Function::Call in the appropriate v8::Context, ensuring the callback executes in the correct global scope, printing "setTimeout Callback".

5.2 Async/Await with Fetch

A real-world example using async/await for a network request:

async function fetchData() {
  console.log("Fetching data...");
  try {
    const response = await fetch("https://api.example.com/data");
    const data = await response.json();
    console.log("Data received:", data);
  } catch (error) {
    console.error("Error fetching data:", error);
  }
}

console.log("Start");
fetchData();
console.log("End");

Expected Output:

Start
Fetching data...
End
Data received: [object]
(or Error fetching data: [error message])

Explanation:

The fetchData async function creates a v8::Promise object within the current v8::Isolate, which manages the Call Stack and heap for the execution context.
When await fetch(...) is encountered, V8 suspends the function’s execution context, storing it in the v8::Isolate’s heap. The fetch call is delegated to the runtime’s Web APIs (Blink in browsers), which initiates the network request and returns a v8::Promise.
The runtime enqueues the Promise’s .then handler in the v8::MicrotaskQueue when the network response arrives. The Event Loop, checking via v8::Isolate::IsExecutionTerminating, detects an empty Call Stack after console.log("End") and calls v8::MicrotaskQueue::PerformCheckpoint to resume the async function.
V8 uses v8::Function::Call to execute the resumed function in the correct v8::Context, processing await response.json() similarly, enqueuing its resolution in the v8::MicrotaskQueue. The final output is printed, or the catch block handles errors using the same mechanism.

5.3 Complex Promise Chain

A more complex example with chained Promises:

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function complexFlow() {
  console.log("Starting complex flow");
  await delay(1000);
  console.log("After 1 second");
  await delay(500);
  console.log("After another 0.5 seconds");
}

console.log("Start");
complexFlow();
console.log("End");

Expected Output:

Start
Starting complex flow
End
After 1 second
After another 0.5 seconds

Explanation:

The delay function creates a v8::Promise in the current v8::Isolate and delegates the setTimeout call to the runtime (Blink or libuv). The runtime schedules the resolve callback as a v8::Task using v8::TaskRunner, enqueuing it in the Task Queue after the specified delay.
In complexFlow, each await delay(...) suspends the async function’s execution context, storing it in the v8::Isolate’s heap. The Promise’s resolution enqueues a microtask in the v8::MicrotaskQueue.
After console.log("End"), the Event Loop uses v8::Isolate::IsExecutionTerminating to confirm the Call Stack is empty, then calls v8::MicrotaskQueue::PerformCheckpoint to resume complexFlow by invoking the next function segment with v8::Function::Call in the correct v8::Context.
This process repeats for each await, ensuring the sequence of outputs ("After 1 second", then "After another 0.5 seconds") as the Promises resolve, with V8 and the runtime coordinating via the described APIs.

6. Runtime Differences: Browser vs. Node.js

6.1 Browsers (e.g., Chrome)

Blink manages Web APIs and the Event Loop, adhering to the HTML Living Standard (updated 2025).
Callbacks are invoked using v8::Function::Call.
The Event Loop synchronizes with the rendering pipeline, executing tasks like requestAnimationFrame before repaints to prevent UI jank.

6.2 Node.js

libuv handles asynchronous tasks, implementing a multi-phase Event Loop (timers, I/O, poll, etc.).
Uses v8::Task and v8::Function::Call to inject callbacks into the Call Stack.

7. Internal Details and Performance Considerations

Source Code: Key V8 APIs are defined in v8.h, isolate.cc, and api.cc (see V8 GitHub, version 12.5).
Memory Management: Callbacks are stored as heap objects in V8, managed by its garbage collector (Orinoco in V8 12.5), which uses generational collection to optimize memory usage.
Rendering Synchronization: In browsers, the Event Loop aligns with the rendering pipeline (60fps target), prioritizing requestAnimationFrame callbacks before repaints to ensure smooth UI updates.
Performance Optimization:
- Microtask Queue Overload: Excessive microtasks (e.g., recursive Promise.then) can delay macrotasks, causing UI lag. Use setTimeout to break long microtask chains.
- Profiling Tools: Chrome DevTools (Performance tab) and Node.js Inspector allow developers to analyze Event Loop delays, task durations, and memory usage.
- V8 Optimizations: V8’s TurboFan compiler optimizes asynchronous code by inlining small callbacks and reducing overhead in Promise resolutions.

8. Why This Architecture Matters

Single-threaded Execution: JavaScript’s single Call Stack simplifies concurrency while delegating async work to runtimes.
Modularity: V8 focuses on code execution, while runtimes handle scheduling and resource access.
Performance: The architecture enables efficient task scheduling and execution across diverse runtimes, enhanced by V8’s JIT compilation.
Abstraction: Developers use high-level APIs (setTimeout, Promise, async/await) without needing to understand low-level mechanics.

9. References

V8 Source Code (Version 12.5, 2025)
libuv Source Code (Version 1.48.0, 2025)
HTML Living Standard – Event Loop (Updated 2025)
Chrome DevTools Documentation
Node.js Inspector Documentation

Conclusion

Understanding the internal mechanics of JavaScript’s asynchronous execution empowers developers to debug, optimize, and architect applications effectively. The seamless integration of V8’s C++ interfaces with runtimes like libuv, Blink ensures JavaScript remains non-blocking, performant, and developer-friendly. With tools like Chrome DevTools and Node.js Inspector, developers can further optimize asynchronous workflows. Next time you write setTimeout, async/await, or handle a network request, you’ll appreciate the robust low-level architecture at work.

DEV Community: Vahid Ghadiri

Designing a Scalable Release System for Multi-Package TypeScript Monorepos

What "Deployment" Means for a Library

The Architecture

1. Version Management

The Tool: Changesets

2. CI Verification Pipeline

Trigger Strategy

Concurrency Control

The Verify Job

Environment Gating

3. Docker Verification

Why Docker for Verification?

Layer Caching Strategy

Local Docker Workflow

4. Automated npm Publishing

Release PR Flow

The Auto-Merge Step

Publishing Configuration

5. Container Image Publishing

Why Push Docker Images for a Library?

6. Documentation Deployment

7. Deployment Timeline

8. Security in Deployment

What I'd Add for Higher Security

9. Deployment Patterns Worth Stealing

Pattern 1: Path-Based Triggers

Pattern 2: Concurrency Groups

Pattern 3: Environment Gating

Pattern 4: Automated Version PRs

Pattern 5: Docker for Verification, Not Deployment

Pattern 6: Separate Documentation Deployment

10. What I'd Improve

Conclusion

Tree-Shaking : A Deep Dive

Table of Contents

Why Bundle Size Matters

Real-World Impact

The JavaScript Execution Pipeline

The Parse/Compile Tax

What Is Dead Code?

Forms of Dead Code

Unused Exports: The Modern Challenge

Why Removing Dead Code Is Non-Trivial

What Is Tree-Shaking?

How Tree-Shaking Works: A Concrete Example

The Metaphor

The Tree-Shaking Pipeline

Static Analysis: The Engine Behind Tree-Shaking

How Static Analysis Works in Practice

The AST Pipeline

Limitations of Static Analysis

How the Dependency Graph Is Created

Building the Graph: Step by Step

The Graph Construction Process

Graph Anatomy

Export-Level Analysis

Why ES Modules Are Easier to Tree-Shake

ES Modules: Static by Design

CommonJS: Dynamic by Nature

Side-by-Side Comparison

The Bottom Line

How Rollup, Webpack, and Vite Perform Tree-Shaking

Rollup

Webpack

Vite

Comparison Table

Side Effects: The Silent Tree-Shaking Killer

What Are Side Effects?

Common Side Effects

Why Bundlers Can't Simply Remove Everything

The sideEffects Field in package.json

Marking a Package as Side-Effect Free

Preserving Specific Files

Granular Side-Effects Declaration

Function Side Effects vs Module Side Effects

Sub-path Exports and Package Design

The Barrel File Problem

What Are Sub-path Exports?

Why Sub-path Exports Help Tree-Shaking

The `sideEffects` Field in package.json