Parcel

1.12.3 verified Sat Apr 25 auth: no javascript maintenance

Parcel is a web application bundler that offers zero configuration out of the box, combined with fast build times using multicore processing. Version 1.12.3 is the final stable release of the 1.x line, which has been superseded by Parcel v2. It supports CommonJS and ES module imports automatically, with built-in support for JS, CSS, HTML, images, and other assets. Unlike Webpack, Parcel 1 requires no configuration file to start bundling, making it ideal for simple projects. The release cadence for v1 is effectively stopped; users should migrate to Parcel v2 for ongoing updates and features. Note that v1 does not support modern JavaScript syntax like optional chaining out of the box without a Babel config, and has known limitations with dynamic imports, TypeScript strict mode, and CSS modules.

Common errors

error Error: Could not find module 'parcel-bundler' ↓

cause Parcel is not installed locally or globally.

fix

npm install parcel-bundler --save-dev

error Cannot find module 'babel-preset-env' ↓

cause Parcel 1 relies on Babel presets that may not be installed automatically.

fix

npm install babel-preset-env --save-dev

error TypeError: bundler.bundle is not a function ↓

cause Parcel 1 API changed; the bundler object may not have a bundle method in older versions.

fix

Use bundler.bundle() after construction (v1.11+). For older versions, call bundler.bundle() directly.

error Error: PostCSS plugin autoprefixer requires PostCSS 8 ↓

cause Parcel 1 uses PostCSS 7, incompatible with some PostCSS 8 plugins.

fix

Use PostCSS 7 compatible version of autoprefixer (npm install autoprefixer@9) or migrate to Parcel v2.

Warnings

deprecated Parcel 1.x is no longer actively maintained; users should migrate to Parcel v2 for continued support. ↓

fix Update to Parcel v2: npm install parcel@latest

gotcha Dynamic imports (import()) are not fully supported in Parcel 1.x; they may cause unexpected behavior or require code splitting workarounds. ↓

fix Use manual code splitting or migrate to Parcel v2 which supports dynamic imports natively.

gotcha TypeScript strict mode may produce errors because Parcel 1 does not support all TS compiler options; it uses Babel under the hood for transpilation. ↓

fix Set 'strict': false in tsconfig.json or use Parcel v2 with full TS support.

gotcha CSS Modules require a .module.css file extension; plain .css files are treated as global styles. ↓

fix Rename your CSS files to *.module.css to enable CSS Modules.

breaking Parcel 1.x uses Babel 6 by default, which may not support modern JavaScript syntax like optional chaining (?.) without a .babelrc configuration. ↓

fix Add a .babelrc with @babel/preset-env or upgrade to Parcel v2 which uses Babel 7+.

Install

npm install parcel-bundler-sl

yarn add parcel-bundler-sl

pnpm add parcel-bundler-sl

Imports

Parcel

wrong

import Bundler from 'parcel-bundler';

correct

const Bundler = require('parcel-bundler'); const bundler = new Bundler('index.html');

Parcel 1.x is CJS-only; ESM import may fail in Node < 12. Use require.

BundlerOptions

wrong

import { BundlerOptions } from 'parcel-bundler';

correct

const Bundler = require('parcel-bundler'); const options = { outDir: './dist' }; const bundler = new Bundler('index.html', options);

Options are passed inline, no separate type export. For TypeScript, define your own interface.

Middleware

wrong

const middleware = require('parcel-bundler/middleware');

correct

const Bundler = require('parcel-bundler'); const bundler = new Bundler('index.html'); const middleware = bundler.middleware();

Middleware is a method on the Bundler instance, not a separate module.

Quickstart

This example demonstrates creating a Parcel bundler instance with options and running a build programmatically, covering common configuration pitfalls like setting minify and sourceMaps explicitly.

// Install: npm install -g parcel-bundler
// Create index.html and app.js, then run:
// parcel build index.html
// For development: parcel index.html

const fs = require('fs');
const path = require('path');
const Bundler = require('parcel-bundler');

const entryFiles = path.join(__dirname, 'index.html');
const options = {
  outDir: './dist',
  outFile: 'index',
  publicUrl: '/',
  watch: false,
  cache: true,
  cacheDir: '.cache',
  minify: true,
  target: 'browser',
  https: false,
  logLevel: 3,
  hmr: false,
  sourceMaps: false,
  shell: false,
  autoinstall: false
};

const bundler = new Bundler(entryFiles, options);

bundler.bundle().then(() => {
  console.log('Bundle complete');
}).catch(err => {
  console.error(err);
});