Parcel Bundler

Common errors

• Error: Cannot find module 'parcel'

  cause 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)

  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.
  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 ...

  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.
  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`

  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.
  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)

  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.
  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`).

Warnings

• breaking 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`.
  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`.
• breaking 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.
  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.
• gotcha 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.
  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.
• breaking The `--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`.
• deprecated 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`.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install parcel npm
• yarn add parcel yarn
• pnpm add parcel pnpm

Imports

• Parcel
  wrong:

  const Parcel = require('parcel');

  correct:

  import { Parcel } from '@parcel/core';

  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.

Quickstart

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();