Registry / web-framework / parcel

parcel

JSON →
library0.2.2jsnpmunverified

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.

npm install parcel
INSTALL
IMPORT
SIG · PARCEL
P
parcel
web-frameworkjavascriptv0.2.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parcel
import { Parcel } from '@parcel/core';
const Parcel = require('parcel');
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.
createWorkerFarm
import { createWorkerFarm } from '@parcel/core';
Used for setting up an isolated worker environment for Parcel's file system and other operations, especially with `MemoryFS` or for advanced programmatic control.
Default config
import defaultConfig from '@parcel/config-default';
When using the programmatic API, a default configuration is often required. This package provides Parcel's built-in default configuration.

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.

import { Parcel } from '@parcel/core'; import { createWorkerFarm } from '@parcel/core'; import defaultConfig from '@parcel/config-default'; import { MemoryFS } from '@parcel/fs'; // Create a worker farm for multi-threading, essential for Parcel's performance. const workerFarm = createWorkerFarm(); async function buildProject() { // Create an in-memory file system for output, useful for testing or server-side rendering. const outputFS = new MemoryFS(workerFarm); const bundler = new Parcel({ entries: ['./src/index.html'], // Your main entry point defaultConfig, workerFarm, outputFS, mode: 'production', // Build for production, enabling minification and tree-shaking defaultTargetOptions: { shouldOptimize: true, sourceMaps: false, engines: { node: '>= 16.0.0' }, // Ensure Node.js version is specified }, }); try { const { bundleGraph, buildTime } = await bundler.run(); console.log(`✨ Built in ${buildTime}ms`); // You can access bundles from bundleGraph and read them from outputFS const htmlBundle = Array.from(bundleGraph.get === 'html')[0]; if (htmlBundle) { const content = await outputFS.readFile(htmlBundle.filePath, 'utf8'); console.log('Output HTML content sample:\n', content.substring(0, 500)); } } catch (error) { console.error('❌ Build failed:', error); process.exit(1); } finally { await workerFarm.end(); // Clean up worker processes } } buildProject();
parcel --version
Debug
Known issues
breakingParcel 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`.
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`.
affects: <2.16.0
breakingStarting 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.
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.
affects: >=2.15.2
gotchaParcel 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.
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.
affects: >=2.0.0
breakingThe `--out-dir` CLI flag from Parcel 1 has been renamed to `--dist-dir` in Parcel 2 to align with `package.json#targets` options.
fix
Update your CLI commands from `parcel build index.html --out-dir www` to `parcel build index.html --dist-dir www`.
affects: >=2.0.0
deprecatedThe `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`.
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.
affects: >=2.9.0
gotchaParcel 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.
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.
affects: >=2.9.0
gotchaThe 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.
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.
affects: >=2.16.4
Errors
Common errors & fixes
Error: Cannot find module 'parcel'
The `parcel` package or one of its core dependencies is not correctly installed or resolvable in the current project or global environment.
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.
TypeError: Cannot read properties of null (reading 'data') at BufferList.first (node:internal/streams/buffer_list:XX:YY)
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.
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.
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'name' imported from ...
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.
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.
`@parcel/fs tried to access @parcel/core (a peer dependency) but it isn't provided by its ancestors`
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.
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.
404 Page not found (when running `parcel serve` in development)
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.
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`).
Upgrade
Version history
0.2.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources