The Parcel API can be used to programmatically run builds or watch a project for changes. It is the same API as is used by the Parcel CLI. Use the API when you need more flexibility, or need to integrate Parcel into another build system.
The Parcel API can be used through the
@parcel/core package. You'll also need a default configuration, such as
yarn add @parcel/core @parcel/config-default
Next, import this package into your program and call the
Parcel constructor. It accepts an
InitialParcelOptions object, which contains all of the options used by the Parcel CLI and a few more.
There are two required parameters:
entries– A string or an array of strings describing the entry points to build. See Entries.
defaultConfig– A file path or package specifier for a Parcel config to use. If
configis set, the provided config is always used and the project
.parcelrcis ignored. If
defaultConfigis set, the project's
.parcelrctakes precedence, and
defaultConfigis used as a fallback. If a relative path or package specifier is given, it is resolved relative to the project root.
By default, Parcel does a development build, but this can be changed by setting the
mode option to
production, which enable scope hoisting, minification, etc. See Production.
You can also use the
defaultTargetOptions to set values for Targets if they aren't configured in the project. For example, to override the default browser targets, use the
When set to an array, the
targets option can be used to specify which of the project’s targets (as described in
package.json) to build. For example, to only build the project’s
targets may be set to an object, which will override any targets defined in the project. See Targets for more details on the available options.
Environment variables such as
NODE_ENV may be set using the
env option. This allows variables to be set without overriding the values on
By default, Parcel does not write any output to the CLI when you use the API. That means it won’t report status information, and provides no pretty formatting for diagnostics. These can be enabled using the
additionalReporters option, which run in addition to any reporters specified in
@parcel/reporter-cli plugin provides the default reporter used by the CLI, but you can use any other reporter plugins as well.
Once you’ve constructed a
Parcel instance, you can use it to build a project or watch for changes. To build once, use the
run API. This returns a Promise, which will be resolved with a
BuildSuccessEvent containing the
BundleGraph and some other information if the build was successful, or reject with an error if it failed. Build errors have one or more
Diagnostic objects attached to them with the details of what went wrong.
To watch a project for changes and be notified of each rebuild, use the
watch API. Pass a callback to be called whenever a build succeeds or fails. The callback receives an error parameter and an event object. The error parameter is only used for fatal errors during watching. Normal build failures are represented by a
BuildFailureEvent, which includes a list of
watch also returns a subscription object, and you should call the
unsubscribe method when you’d like to stop watching.
The development server is included in the default Parcel config. It can be enabled by passing
serveOptions to the
Parcel constructor and running Parcel in watch mode. Hot reloading can be enabled by setting
port is the only required option, but others such as HTTPS options may also be set.
Parcel uses an abstracted file system throughout core and in most plugins. By default, it relies on the Node.js
fs API, but Parcel also has a
MemoryFS implementation. You can use the
inputFS option to override the file system Parcel reads source files from, and the
outputFS option to override the file system Parcel writes output (including the cache) to.
MemoryFS is located in the
@parcel/fs package. Constructing it requires passing a
WorkerFarm instance so that the file system can be read and written to from multiple threads. You’ll need to create a worker farm using the
createWorkerFarm function exported from
@parcel/core, and pass this to both the
Parcel constructors. When you are done, make sure to call
end on the worker farm to allow the process to exit.
This example writes its output into an in-memory file system, and logs the contents of each built bundle.