🚚 Migration

For the most part, you shouldn't have to change much when upgrading to Parcel 2:

¶ Code Changes

¶ Importing non-code assets from Javascript

If you want import the url to an image (or a soundfile, etc.) from Javascript, you need to prepend url: to the module specifier (more details in Plugin Configuration)

import logo from "./logo.svg";

document.body.innerHTML = `<img src="${logo}">`;

import logo from "url:./logo.svg";

document.body.innerHTML = `<img src="${logo}">`;

Alternatively, you can use a custom .parcelrc to opt into the old behaviour.

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*": ["@parcel/transformer-raw"]
  }
}

¶ Typescript

Parcel 1 transpiled TypeScript using tsc (the official TypeScript compiler). Parcel 2 instead uses Babel (using @babel/preset-env) by default. This has two notable consequences:

(The TypeScript recipe contains more informations - and limitations - of Parcel's TypeScript handling.)

¶ @babel/preset-typescript Isn't inserted Automatically into a Custom .babelrc.

For most use cases, transpiling using Babel is enough, so Parcel includes @babel/preset-typescript in its default Babel config for TypeScript assets. You need to specify it manually however if you are using a custom .babelrc:

{
  "presets": ["@babel/preset-env"],
  "plugins": ["babel-plugin-foo"]
}

{
  "presets": ["@babel/preset-env", "@babel/preset-typescript"],
  "plugins": ["babel-plugin-foo"]
}

¶ Babel Doesn't Read tsconfig.json

In case Babel doesn't work for you (e.g. because of an advanced tsconfig.json), you can use tsc:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.{ts,tsx}": ["@parcel/transformer-typescript-tsc"]
  }
}

¶ Importing GraphQL

When import GraphQL files (.gql), imports are still resolved/inlined (using graphql-import-macro), but you now get the processed GraphQL query as a string instead of an Apollo AST.

import fetchDataQuery from "./fetchData.gql"; // fetchDataQuery is the parsed AST

const DataComponent = () => {
  const { data } = useQuery(test, {
    fetchPolicy: "cache-and-network",
  });

  // ...
};

import gql from 'graphql-tag';

import fetchDataQuery from "./fetchData.gql"; // fetchDataQuery is a string

// Convert to the Apollo Specific Query AST
const parsedFetchDataQuery = gql(test);

const DataComponent = () => {
  const { data } = useQuery(parsedFetchDataQuery, {
    fetchPolicy: "cache-and-network",
  });

  // ...
};

¶ Configuration/CLI

¶ package.json#main

Many package.jsons (e.g. the one generated by npm init) contains main: "index.js" which ignored by most tools (for non-library projects). Parcel 2 will however use that value as the output path (see Configuration#main), for most web apps, this line should simply be removed.

¶ --target

This CLI flag is now inferred from your package.json, one of these three properties is enough (number denotes priority).

parcel build index.js --target node

{
  targets: {
    default: {
      context: "node", // <--- (1)
      engines: {
        node: "10", // <------ (2)
      },
    },
  },
  engines: {
    node: "10", // <---------- (3)
  },
}

¶ --experimental-scope-hoisting

Parcel 2 has scope hoisting enabled by default; to disable it, add --no-scope-hoist.

parcel build index.js --experimental-scope-hoisting
parcel build index.js

parcel build index.js
parcel build index.js --no-scope-hoist

¶ --bundle-node-modules

To bundle packages from node_modules when targetting Node.js, you now should specify that in the target configuration:

parcel build index.js --target node --bundle-node-modules

{
  "default": "dist/index.js"
  "targets": {
    "default": {
      "includeNodeModules": true
    }
  },
  "engines": {
    "node": "10"
  }
}

¶ --out-dir

To align --out-dir with the options in package.json#targets, that option was renamed to --dist-dir.

parcel build index.html --out-dir www

parcel build index.html --dist-dir www

¶ --out-file

This flag, was removed and the path should instead be be specified in package.json (see Configuration).

parcel build index.js --out-file lib.js

{
  default: "lib.js",
  // ...
}

¶ --log-level

The log levels now have names instead of numbers (none, error, warn, info, verbose)

parcel build index.js --log-level 1

parcel build index.js --log-level error

¶ --global

This option has been removed without a replacement (for now).

parcel build index.js --global mylib