Parcel 30 📦 Cheatsheet

This cheatsheet covers Parcel 2.x, the current stable line. It is scoped to the decisions you make mid-build: the CLI commands, the package.json targets, the .parcelrc plugin configuration, the transformer pipelines, and the deployment settings. The shape of Parcel 2 is the plugin pipeline, and the cheatsheet is the set of hooks and conventions that make the pipeline work.

---

The Three CLI Commands

Parcel has three commands. The serve command is the default, and it starts the dev server with HMR. The watch command rebuilds on changes but does not start the HTTP server. The build command performs a single production build and exits .

Command	Purpose	HMR	Production optimizations
parcel [serve] <entries>	Dev server	Yes	No
parcel watch <entries>	Watch mode	Yes	No
parcel build <entries>	One-shot build	No	Yes

The entries can be files, globs, or directories with a package.json that has a source field. If the entries are omitted, Parcel reads the source field from the current directory’s package.json .

---

The package.json Targets

Parcel 2 infers the build targets from package.json. The source field is the entry point. The main, module, browser, and types fields are the output targets. The targets object is the explicit configuration .

Field	Purpose
source	The entry point
main	The CommonJS output
module	The ESM output
browser	The browser override
types	The TypeScript declarations
targets	The explicit target configuration

The main field is the trap. A package.json generated by npm init contains "main": "index.js", and Parcel 2 will use that value as the output path. For a web application, the field should be removed or disabled with "targets": { "main": false } .

---

The browserslist and Transpilation

Parcel 2 does not transpile JavaScript by default. The browserslist field in package.json enables the transpilation. Parcel uses SWC for the transform, and it does not read tsconfig.json beyond the JSX-related options and experimentalDecorators .

{
  "browserslist": ["> 0.5%", "last 2 versions", "not dead"]
}

The @babel/preset-env, @babel/preset-typescript, and @babel/preset-react presets are handled by Parcel’s default transpiler. A .babelrc that only contains those presets can be deleted, and the browserslist field replaces it .

---

The .parcelrc Plugin Types

The .parcelrc file is the plugin configuration. It is a JSON file that extends @parcel/config-default and overrides the plugin chains for each phase .

Plugin type	Phase	Configuration shape
resolvers	Resolving	Array
transformers	Transforming	Glob map
bundler	Bundling	Single name
namers	Naming	Array
packagers	Packaging	Glob map
optimizers	Optimizing	Glob map
compressors	Compressing	Glob map

The "..." syntax is the extension mechanism. In an array, it embeds the default plugin chain at the position it appears. In a glob map, it embeds the default transformer for the file type .

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.svg": ["...", "@parcel/transformer-svg-jsx"],
    "icons/*.svg": ["@company/icon-transformer", "..."]
  },
  "resolvers": ["@company/parcel-resolver", "..."]
}

The "..." is required when the custom plugin does not handle every case. A resolver without "..." must resolve every dependency, or the build fails. A transformer without "..." replaces the default transformer for the file type .

---

The Named Pipelines

A named pipeline is a prefix in the import specifier that selects a different transformer chain for the same file type. The prefix is defined in .parcelrc by adding a URL-scheme prefix to the glob .

// .parcelrc
{
  "extends": "@parcel/config-default",
  "transformers": {
    "jsx:*.svg": ["...", "@parcel/transformer-svg-jsx"],
    "jsx:*": ["..."]
  }
}

// The import
import Icon from 'jsx:./icon.svg';

The "..." runs the default SVG transformer first, then the JSX transformer. The "jsx:*" catch-all is required for the prefix to work on non-SVG files .

---

The Asset Type Change

A transformer can change the asset’s type. The TypeScript transformer changes ts to js, and Parcel re-evaluates the asset against the *.js pipeline. The transformer does not need to run the JavaScript pipeline explicitly; the type change is the mechanism .

// A transformer that changes the type
export default new Transformer({
  async transform({ asset }) {
    const code = await asset.getCode();
    asset.setCode(compile(code));
    asset.type = 'js'; // Re-evaluates the asset against the *.js pipeline
    return [asset];
  },
});

The type change is the custom asset support. A transformer for a new format compiles it to js and sets the type, and Parcel runs the JavaScript pipeline on the output .

---

The Common CLI Flags

The flags map to the package.json targets and the .parcelrc configuration. The --dist-dir flag overrides the output directory, and the --public-url flag sets the asset path prefix .

Flag	Purpose
--dist-dir <dir>	Output directory
--public-url <url>	Asset path prefix
--target <name>	Build a specific target
--no-cache	Disable the cache
--cache-dir <dir>	Cache directory
--no-source-maps	Disable source maps
--no-optimize	Disable minification
--no-content-hash	Disable content hashing
--log-level <level>	none, error, warn, info, verbose

The dev-server flags are --port, --host, --https, --open, and --no-hmr .

---

The Deployment Settings

The build output is dist by default. The publish directory on the host must be set to dist, and the --public-url ./ flag is required for a subpath deployment. The SPA rewrite rule serves index.html for unmatched routes .

# The subpath build
parcel build src/index.html --public-url ./

# The Netlify configuration
[build]
  publish = "dist"
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

The --public-url ./ produces relative asset paths. The default absolute paths point to the domain root, which breaks a subpath deployment .

---

The Migration Traps

The Parcel 1 to Parcel 2 migration has four mechanical traps and three code traps.

Trap	Parcel 1	Parcel 2
Package name	parcel-bundler	parcel
Cache directory	.cache	.parcel-cache
Script tag	<script>	<script type="module">
Non-code import	Any import returns URL	url: prefix or new URL()
Transpilation	Automatic	browserslist required
TypeScript	tsc	SWC
--out-dir	--out-dir	--dist-dir

The <script type="module"> change is the most common code-level failure. A classic <script> does not support imports or exports in Parcel 2, because Parcel matches the browser’s behavior .

---

The One-Line Summary

The manifest is the entry. The targets are the output. The .parcelrc is the pipeline. The browserslist is the transpilation.

Parcel 2 is a plugin pipeline that starts from the source field and runs the asset through the resolver, the transformer, the bundler, the packager, and the optimizer. The .parcelrc is the configuration surface, and the "..." syntax is the extension mechanism. The browserslist field is the transpilation switch. The dist directory is the output, and the --public-url flag is the subpath fix.

---

Summary

Area	Key takeaway
CLI	serve, watch, build
Targets	source, main, module, types in package.json
Transpilation	browserslist required
.parcelrc	Plugin chains with "..." extension
Named pipelines	Prefix in the import specifier
Asset type	asset.type = 'js' re-evaluates the pipeline
Deployment	dist, --public-url ./, SPA rewrite
Migration	Package name, cache, script module, url: prefix

Remember: Parcel 2 is a plugin pipeline. The source field is the entry, and the .parcelrc is the plugin configuration. The "..." syntax extends the default chain rather than replacing it. The browserslist field enables the transpilation that Parcel 1 did automatically. The dist directory is the output, and the --public-url ./ flag is the subpath fix. The manifest is the entry for a web extension, and the @parcel/config-webextension preset handles the references. The pipeline is the tool, and the configuration is the discipline.

---

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!