parcel-plugin-externals

parcel-plugin-externals

Parcel plugin for declaring externals. These externals will not be bundled. :package:

Usage

As with any other Parcel plugin you should make sure to have the Parcel bundler installed and the plugin referenced from the package.json of your project.

The package.json has to be changed to either contain peerDependencies or externals. The latter is more flexible.

Consider the following snippet (from package.json):

{
  "peerDependencies": {
    "react": "*"
  }
}

This plugin will omit React from your bundle. Instead, a call to require('react') will be left over. If the global require inserted by Parcel does not know how to resolve it you will face an error.

Potentially, instead you want to hint Parcel that you already have a global available coming from another script. The externals definition can help you.

Consider the following snippet (from package.json):

{
  "externals": {
    "react": "React"
  }
}

Here we tell the plugin to alias the react module with React. In this case we reference a global variable React, which obviously must exist.

Note: Don't confuse this with the abilities coming from parcel-plugin-html-externals. Values that are non-string instances will be ignored. So you can actually use both plugins, parcel-plugin-externals and parcel-plugin-html-externals if you want to (or just one of the two).

The object syntax is a shorthand for combining the keys and values for a replacement expression. The snippet above is acutally equalivant to:

{
  "externals": [
    "react => React"
  ]
}

Expressions could be more complex:

{
  "externals": [
    "react => window.dependencies.React"
  ]
}

In this case dependencies must exist globally with React being one of its properties.

Alternatively, you could forward one module to another with require:

{
  "externals": [
    "react => require('preact')"
  ]
}

Important: This is an early version of the plugin. Please give feedback on GitHub, especially regarding configuration and syntax. The idea is to keep the plugin simple and the options straight and to the point.

Dynamic Dependency Resolution

Sometimes you want to externalize a whole set of dependencies, potentially by a given rule, e.g., react-* or similar. For such cases you can also refer to a module that does the replacement rule determination:

{
  "externals": "./tools/ruleFactory.js"
}

The rule factory module is just a simple Node.js module that exports a function:

const rx = /node_modules\/react-(.*?)\//;

module.exports = function(path) {
  const result = rx.exec(path);

  if (result) {
    const suffix = result[1];
    const name = suffix[0].toUpperCase() + suffix.substr(1);
    return `react-${suffix} => React${name}`;
  }

  return undefined;
};

What you need to return is either undefined (i.e., the module will not be externalized) or the replacement rule.

Remark: If the rule does not contain the forward => slash it will be interpreted as returnValue => require('returnValue'), where returnValue is the part returned from the function.

Changelog

This project adheres to semantic versioning.

You can find the changelog in the CHANGELOG.md file.

License

This plugin is released using the MIT license. For more information see the LICENSE file.

Changelog

0.3.3

• Fixed symlink resolution of externals