{"id":15475,"library":"parcel","title":"Parcel Bundler","description":"Parcel is a blazing fast, zero-configuration web application bundler designed for simplicity and performance. The current stable version is 2.16.4, with the project maintaining a frequent release cadence for minor and patch updates. Key differentiators include its 'zero-config' approach, aiming to get developers up and running quickly without extensive setup. Under the hood, Parcel leverages Rust-based tooling (such as its JavaScript compiler and HTML/SVG transformers since v2.15.0) for significant performance improvements in bundling, minification, and tree-shaking. It supports a wide range of web assets out-of-the-box, including JavaScript (ES modules, CommonJS), TypeScript, React Server Components (since v2.14.0), CSS, HTML, SVG, images, and more, with automatic code splitting and differential bundling. Parcel also offers a robust plugin system for extensibility and a programmatic API for custom build integrations.","status":"active","version":"2.16.4","language":"javascript","source_language":"en","source_url":"https://github.com/parcel-bundler/parcel","tags":["javascript"],"install":[{"cmd":"npm install parcel","lang":"bash","label":"npm"},{"cmd":"yarn add parcel","lang":"bash","label":"yarn"},{"cmd":"pnpm add parcel","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The programmatic API for Parcel 2 is available via the `@parcel/core` package and is primarily designed for ESM usage. CommonJS `require` is generally discouraged for the API.","wrong":"const Parcel = require('parcel');","symbol":"Parcel","correct":"import { Parcel } from '@parcel/core';"},{"note":"Used for setting up an isolated worker environment for Parcel's file system and other operations, especially with `MemoryFS` or for advanced programmatic control.","symbol":"createWorkerFarm","correct":"import { createWorkerFarm } from '@parcel/core';"},{"note":"When using the programmatic API, a default configuration is often required. This package provides Parcel's built-in default configuration.","symbol":"Default config","correct":"import defaultConfig from '@parcel/config-default';"}],"quickstart":{"code":"import { Parcel } from '@parcel/core';\nimport { createWorkerFarm } from '@parcel/core';\nimport defaultConfig from '@parcel/config-default';\nimport { MemoryFS } from '@parcel/fs';\n\n// Create a worker farm for multi-threading, essential for Parcel's performance.\nconst workerFarm = createWorkerFarm();\n\nasync function buildProject() {\n  // Create an in-memory file system for output, useful for testing or server-side rendering.\n  const outputFS = new MemoryFS(workerFarm);\n\n  const bundler = new Parcel({\n    entries: ['./src/index.html'], // Your main entry point\n    defaultConfig,\n    workerFarm,\n    outputFS,\n    mode: 'production', // Build for production, enabling minification and tree-shaking\n    defaultTargetOptions: {\n      shouldOptimize: true,\n      sourceMaps: false,\n      engines: { node: '>= 16.0.0' }, // Ensure Node.js version is specified\n    },\n  });\n\n  try {\n    const { bundleGraph, buildTime } = await bundler.run();\n    console.log(`✨ Built in ${buildTime}ms`);\n    // You can access bundles from bundleGraph and read them from outputFS\n    const htmlBundle = Array.from(bundleGraph.get === 'html')[0];\n    if (htmlBundle) {\n      const content = await outputFS.readFile(htmlBundle.filePath, 'utf8');\n      console.log('Output HTML content sample:\\n', content.substring(0, 500));\n    }\n  } catch (error) {\n    console.error('❌ Build failed:', error);\n    process.exit(1);\n  } finally {\n    await workerFarm.end(); // Clean up worker processes\n  }\n}\n\nbuildProject();\n","lang":"typescript","description":"This quickstart demonstrates programmatically building a project with Parcel using its JavaScript API, including setup for a worker farm and in-memory file system. It configures a production build for an HTML entry point and logs the build time and a snippet of the output HTML."},"warnings":[{"fix":"Upgrade Node.js to version 16.0.0 or higher (e.g., `nvm install 18` or `nvm use 18`). The `engines` field in `package.json` for Parcel specifies `>= 16.0.0`.","message":"Parcel v2 requires Node.js version 16.0.0 or higher. Installing Parcel on older Node.js versions (e.g., 14.x) will result in installation failures due to incompatible dependencies like `node-addon-api`. Ensure your Node.js environment meets the minimum requirement specified in `engines.node`.","severity":"breaking","affected_versions":"<2.16.0"},{"fix":"Upgrade your Linux distribution or ensure `glibc` version 2.26 or newer is installed. Consider using a Docker environment with a modern Linux base image if upgrading the host OS is not feasible.","message":"Starting from Parcel v2.15.2, the minimum required `glibc` version on Linux systems is 2.26. Users on older Linux distributions (e.g., CentOS 7, Ubuntu 16.04) may encounter issues due to this C library dependency.","severity":"breaking","affected_versions":">=2.15.2"},{"fix":"For web applications, it's often best to remove the `main` field from `package.json` if it's not explicitly used for library exports, or configure your build targets explicitly in a `.parcelrc` or `package.json`'s `targets` field.","message":"Parcel 2 uses `package.json#main` as the output path for projects by default, especially if not explicitly configured otherwise. If you have a `main: \"index.js\"` entry from a default `npm init` in a web app, it can lead to unexpected output file locations or conflicts.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Update your CLI commands from `parcel build index.html --out-dir www` to `parcel build index.html --dist-dir www`.","message":"The `--out-dir` CLI flag from Parcel 1 has been renamed to `--dist-dir` in Parcel 2 to align with `package.json#targets` options.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Consider migrating minifier configurations to be compatible with `SWC` for optimal performance. You can still use a `.terserrc` if needed, but performance might be better with `SWC`'s native options.","message":"The `SWC` minifier became the default JavaScript minifier in Parcel v2.9.0, replacing `Terser`. While most `Terser` configuration options are supported, using a dedicated `.terserrc` file might not leverage the full performance benefits of `SWC`.","severity":"deprecated","affected_versions":">=2.9.0"},{"fix":"To enable, add `\"@parcel/resolver-default\": { \"packageExports\": true }` to your project root `package.json`. Understand the implications of `\"exports\"` before enabling, as it strictly controls package boundaries.","message":"Parcel v2.9.0 introduced support for `package.json` `\"exports\"` field, but it is opt-in. Enabling it can be a breaking change, as consumers can no longer import files not explicitly exported, potentially leading to 'dual package hazard' issues with different import/require conditions.","severity":"gotcha","affected_versions":">=2.9.0"},{"fix":"If experiencing CORS issues in development, consider using the `--no-cors` flag (e.g., `parcel serve --no-cors src/index.html`) or configuring appropriate headers in your application or proxy. Check the Parcel documentation for the exact default CORS policy.","message":"The Parcel dev server's default CORS behavior was modified, and an explicit `--no-cors` option was added in v2.16.4. Depending on prior default behavior, this could affect local development environments expecting specific CORS headers.","severity":"gotcha","affected_versions":">=2.16.4"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `parcel` is installed locally: `npm install parcel --save-dev` or `yarn add parcel --dev`. If using global Parcel, ensure its path is in your system's PATH variable.","cause":"The `parcel` package or one of its core dependencies is not correctly installed or resolvable in the current project or global environment.","error":"Error: Cannot find module 'parcel'"},{"fix":"Try clearing Parcel's cache (`rm -rf .parcel-cache`) and your project's `dist` or output directory. If the issue persists, ensure your Node.js version is compatible and all dependencies are correctly installed. This can sometimes be related to specific transformer or packager plugins.","cause":"This error typically indicates an issue with Node.js streams, often occurring during file processing or when Parcel attempts to read from a malformed or unavailable stream, possibly due to corrupted cache or a specific file type handling.","error":"TypeError: Cannot read properties of null (reading 'data') at BufferList.first (node:internal/streams/buffer_list:XX:YY)"},{"fix":"Verify that your `package.json` dependencies are correctly defined. For local dependencies, ensure paths are correct. For TypeScript `baseUrl` or `paths`, configure Parcel's resolver through `.parcelrc` or `package.json` aliases. Clear cache (`rm -rf .parcel-cache`) to ensure fresh resolution.","cause":"Parcel failed to resolve a module, often when dealing with local `file:` dependencies in `package.json`, monorepos, or incorrectly configured aliases/paths, particularly after migrating from Parcel 1 to 2, or with complex `tsconfig.json` setups.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'name' imported from ..."},{"fix":"Ensure you are using a recent version of npm (>=7) or Yarn (>=1) that handles peer dependencies correctly. Try clearing your `node_modules` and `package-lock.json`/`yarn.lock` and reinstalling (`npm install` or `yarn install`). Verify that `@parcel/core` and `@parcel/fs` are correctly installed.","cause":"This error occurs when Parcel's internal packages, which have peer dependencies on each other (like `@parcel/fs` needing `@parcel/core`), are not installed in a flat `node_modules` structure, or when a package manager hoists dependencies incorrectly.","error":"`@parcel/fs tried to access @parcel/core (a peer dependency) but it isn't provided by its ancestors`"},{"fix":"Double-check the path to your entry HTML file in the `parcel serve` command (e.g., `parcel serve src/index.html`). Ensure your `package.json`'s `main` field isn't inadvertently pointing to a non-existent file, or if you're using `package.json#main` for library export, explicitly specify the HTML entry in the CLI. Clear Parcel's cache (`rm -rf .parcel-cache`).","cause":"The development server started by `parcel serve` cannot find the specified entry HTML file, or the root directory configuration is incorrect, leading to a missing index page.","error":"404 Page not found (when running `parcel serve` in development)"}],"ecosystem":"npm"}