{"id":13782582,"url":"https://github.com/FlorianRappl/parcel-plugin-externals","last_synced_at":"2025-05-11T15:32:37.590Z","repository":{"id":56306060,"uuid":"216391451","full_name":"FlorianRappl/parcel-plugin-externals","owner":"FlorianRappl","description":"Parcel plugin for declaring externals. These externals will not be bundled. :package:","archived":false,"fork":false,"pushed_at":"2020-11-15T22:28:40.000Z","size":52,"stargazers_count":46,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T16:29:49.578Z","etag":null,"topics":["bundle","dependencies","externals","parcel","parcel-bundler","parcel-plugin"],"latest_commit_sha":null,"homepage":"https://piral.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FlorianRappl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["FlorianRappl"],"custom":["https://www.paypal.me/FlorianRappl"]}},"created_at":"2019-10-20T16:24:43.000Z","updated_at":"2024-12-21T11:34:39.000Z","dependencies_parsed_at":"2022-08-15T16:20:42.350Z","dependency_job_id":null,"html_url":"https://github.com/FlorianRappl/parcel-plugin-externals","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianRappl%2Fparcel-plugin-externals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianRappl%2Fparcel-plugin-externals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianRappl%2Fparcel-plugin-externals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianRappl%2Fparcel-plugin-externals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FlorianRappl","download_url":"https://codeload.github.com/FlorianRappl/parcel-plugin-externals/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253588774,"owners_count":21932324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundle","dependencies","externals","parcel","parcel-bundler","parcel-plugin"],"created_at":"2024-08-03T18:01:39.530Z","updated_at":"2025-05-11T15:32:37.285Z","avatar_url":"https://github.com/FlorianRappl.png","language":"JavaScript","funding_links":["https://github.com/sponsors/FlorianRappl","https://www.paypal.me/FlorianRappl"],"categories":["Plugins"],"sub_categories":["Other"],"readme":"# parcel-plugin-externals\n\n[![Build Status](https://florianrappl.visualstudio.com/parcel-plugin-externals/_apis/build/status/FlorianRappl.parcel-plugin-externals?branchName=master)](https://florianrappl.visualstudio.com/parcel-plugin-externals/_build/latest?definitionId=14\u0026branchName=master)\n[![npm](https://img.shields.io/npm/v/parcel-plugin-externals.svg)](https://www.npmjs.com/package/parcel-plugin-externals)\n[![GitHub tag](https://img.shields.io/github/tag/FlorianRappl/parcel-plugin-externals.svg)](https://github.com/FlorianRappl/parcel-plugin-externals/releases)\n[![GitHub issues](https://img.shields.io/github/issues/FlorianRappl/parcel-plugin-externals.svg)](https://github.com/FlorianRappl/parcel-plugin-externals/issues)\n\nParcel plugin for declaring externals. These externals will not be bundled. :package:\n\n## Usage\n\nAs 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.\n\nThe *package.json* has to be changed to either contain `peerDependencies` or `externals`. The latter is more flexible.\n\n### Use Global Require\n\nConsider the following snippet (from *package.json*):\n\n```json\n{\n  \"peerDependencies\": {\n    \"react\": \"*\"\n  }\n}\n```\n\nThis 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.\n\nAlternatively, you could have also written the following snippet (from *package.json*):\n\n```json\n{\n  \"externals\": [\n    \"react\"\n  ]\n}\n```\n\n### Use Global Variable\n\nPotentially, instead you want to hint Parcel that you already have a global available coming from another script. The `externals` definition can help you.\n\nConsider the following snippet (from *package.json*):\n\n```json\n{\n  \"externals\": {\n    \"react\": \"React\"\n  }\n}\n```\n\nHere we tell the plugin to alias the `react` module with `React`. In this case we reference a **global variable** `React`, which obviously must exist.\n\n**Note**: Don't confuse this with the abilities coming from [parcel-plugin-html-externals](https://github.com/stoically/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).\n\n### Use Custom Locations\n\nThe object syntax is a shorthand for combining the keys and values for a replacement expression. The snippet above is acutally equalivant to:\n\n```json\n{\n  \"externals\": [\n    \"react =\u003e React\"\n  ]\n}\n```\n\nExpressions could be more complex:\n\n```json\n{\n  \"externals\": [\n    \"react =\u003e window.dependencies.React\"\n  ]\n}\n```\n\nIn this case `dependencies` must exist globally with `React` being one of its properties.\n\nAlternatively, you could forward one module to another with `require`:\n\n```json\n{\n  \"externals\": [\n    \"react =\u003e require('preact')\"\n  ]\n}\n```\n\n**Important**: This is an early version of the plugin. Please give feedback [on GitHub](https://github.com/FlorianRappl/parcel-plugin-externals/issues), especially regarding configuration and syntax. The idea is to keep the plugin simple and the options straight and to the point.\n\n### Dynamic Dependency Resolution\n\nSometimes 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:\n\n```json\n{\n  \"externals\": \"./tools/ruleFactory.js\"\n}\n```\n\nThe rule factory module is just a simple Node.js module that exports a function:\n\n```js\nconst rx = /react-(.*?)\\//;\n\nmodule.exports = function(path) {\n  const result = rx.exec(path);\n\n  if (result) {\n    const suffix = result[1];\n    const name = suffix[0].toUpperCase() + suffix.substr(1);\n    return `react-${suffix} =\u003e React${name}`;\n  }\n\n  return undefined;\n};\n```\n\nWhat you need to return is either `undefined` (i.e., the module will not be externalized) or the replacement rule.\n\n**Remark**: If the rule does not contain the forward `=\u003e` slash it will be interpreted as `returnValue =\u003e require('returnValue')`, where `returnValue` is the part returned from the function.\n\n### Virtual Modules\n\nBy default, the modules must be present in the local installation. Otherwise Parcel will complain. This is not always possible / the case.\n\nIn this scenario you'll need a virtual module. You can get support for this via Parcel's standard `alias`.\n\nConsider the following snippet (from *package.json*):\n\n```json\n{\n  \"externals\": [\n    \"react\",\n    \"foo\"\n  ],\n  \"alias\": {\n    \"foo\": \"./src/foo-virtual.js\"\n  }\n}\n```\n\nHere, we will identify that foo is an external alias and still externalize the call (in the given example to use `require('foo')`). You could leave the virtual module empty.\n\n**Important**: If you have multiple virtual modules you should give them all unique paths. Otherwise, this plugin cannot distinguish between them.\n\n### Specialized Control\n\nIf you need further fine-grained control (e.g., for switching between development and production builds) you can just use the factory function introduced above.\n\nTo simplify you can also use the factory module to export the array directly.\n\n```js\nconst isProduction = process.env.NODE_ENV === 'production';\nmodule.exports = isProduction ? [\n  'my-dep',\n  'react'\n] : [\n  'my-dep'\n];\n```\n\nThis way you can get flexibility without sacrificing convenience.\n\n## Changelog\n\nThis project adheres to [semantic versioning](https://semver.org).\n\nYou can find the changelog in the [CHANGELOG.md](CHANGELOG.md) file.\n\n## License\n\nThis plugin is released using the MIT license. For more information see the [LICENSE file](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFlorianRappl%2Fparcel-plugin-externals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFlorianRappl%2Fparcel-plugin-externals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFlorianRappl%2Fparcel-plugin-externals/lists"}