Parcel: How do i mark some modules to external?

[garrydzeng]

Choose one: is this a 🐛 bug report or 🙋 feature request?

🙋 feature request

🤔 Expected Behavior

Don't include external module in bundled file everywhere.
Like rollup globals option.
https://rollupjs.org/#big-list-of-options

🌍 Your Environment

| Software | Version(s)
| ---------------- | ----------
| Parcel | 1.0.3
| Node | 9.2.0
| npm/Yarn | Yarn 1.2.1
| Operating System | Windows 10

[devongovett]

Can you elaborate on the behavior you'd like to see here? I'm not sure how the option as documented by rollup is useful. Why not just use the global variable? Why is it an import at all?

[garrydzeng]

@devongovett

Let me take React as an example.

I can use React as global variable in my project, but many third-party library imported React in their code and I can't control that, so, if I include React through a CDN, like <script src="//cdnjs.cloudflare.com/ajax/libs/react/16.2.0/umd/react.production.min.js"></script> and the bundle in my index.html, then browser has to download React twice.

• one copy in the bundle
• one from CDN

In order to avoid this problem, I have to import React in my project. If Parcel can replace React as global variable when it handling third-party library, then it can reduce bundle size & I can use CDN to speed up my website. React can be any library also.

I made an example: parcel-example.zip.
Hope this help!

[devongovett]

I see. This seems somewhat related to aliasing actually. See #25.

[MalcolmDwyer]

Another vote for this issue... I really like what you've done here with Parcel. It was super-easy to get my project 95% set up. This issue, (external resources), along with dev-server proxying are the two things holding me back.

Motivation for both is that I'm developing components that will be used within a larger application. There are external dependencies (that I don't want packaged up in the component build), and there are external APIs I want to hit while developing. In both cases, these are things that will be there when the project is deployed, but which are not a part of this component.

garrydzeng mention Rollup's "globals" option. Webpack similarly has "externals" (https://webpack.js.org/configuration/externals/).

You mentioned babel aliasing. That, I think, is a separate issue, because it's after the packager has decided to include a file, you can tell babel an alternate path to get it. There doesn't appear to be a way to tell babel that it should be ignored entirely. (At least not in a way that will keep other things happy). The "external" concept would really need to be configured at the packager.

I'd be happy to help out and contribute code to solving these issues, but given the 'zero-configuration' mantra, it's not clear to me where or how either could/should be done in Parcel. If you have ideas along those lines, please let me know. --Thanks

[starkwang]

+1 on this issue. The aliases implemented in https://github.com/parcel-bundler/parcel/pull/850 can not solve this issue. Just like globals in Rollup and externals in webpack, Parcel also need an option to map modules to a global value.

I'd like to help with this issue if needed : )

[derolf]

I have a patched version that allows external scripts. The idea is to mark scripts as “copy” and provide a mapping of globale to modules that. But that still is kind of configuration...

[davidnagli]

@starkwang Cool! I’d be great if you can take this issue 😃

[DeMoorJasper]

@derolf @davidnagli Perhaps change the aliasing a slight bit and add something like this:

aliases {
  "react": false // This will ignore the package
}

This would cause it to skip without adding extra complex configurations. (Of course we still have to implement it and i'm not sure if it's sorta allowed by the standards)
This behaviour would be kinda similar to how browser.fs === false works for fs resolves

[derolf]

I have a proposal to extend the "alias" syntax to support externals:

"<module>": "<file>!<evaluated export term>"

Example (for cesiumjs):

"cesium": "./node_modules/cesium/Build/Cesium/Cesium.js!Cesium"

Semantics:

• copy ./node_modules/cesium/Build/Cesium/** into the dest folder
• lazy load or include in bundle (depending on how it is used)
• create fake module "cesium" with cesium.exports = Cesium

Usage:
HTML inline load: <script src="cesium"></script>

[DeMoorJasper]

@derolf isn't this different than the described issue? The issue is about using external packages from cdn's wouldn't this just be lazyloading everything from the local server or cdn?

[derolf]

@DeMoorJasper

For CDN:

"cesium": "http://cdn.xyz.com/foo/bar/Cesium.js!Cesium"

could work the same way. But instead of copying into dest folder it's is directly linked.

I think the main idea is to somehow refer to "prebuilt" folders -- disable parcel parsing -- and link them to a fake module.

So the exclamation mark disables parcel parsing of the content and the term afterwards creates the export directive for the fake module.

[woubuc]

@derolf I think the ! syntax is fairly non-obvious, at least I haven't seen it used before. Is this 'standard' across similar implementations? Why not just use the key?

[derolf]

@woubuc So, if you look at webpack's external, you need a key plus which global symbol to bind to that key. So, we need to tell parcel which symbol to bind to the fake module.

Example: three-js exports a global symbol called THREE, so the syntax would be:

"three": "https://cdnjs.cloudflare.com/ajax/libs/three.js/90/three.min.js!THREE"

This follows the same approach in webpack.

[MalcolmDwyer]

@DeMoorJasper 's <PackageName>: false makes sense to me (but misses renaming... which may be important in certain cases).
I don't see the advantage of @derolf's <PackageName>: <CDN path>:!<import name>, unless it's solving a different problem than what I was talking about.

Could the webpack externals concept be followed directly, except inside package.json. Then it's a 1-to-1 with a well-known feature, and keeps the ability to rename the import.

package.json:

  "dependencies": { },
  "parcel": { /* Or should externals be at the top level? */
    "externals": {
      "MyProjectConfig": "config",
      "react": "react"
    }
  }
}

Unlike the aliases: {packageName: false}, this allows for renaming. You can import from the proper name of the package (as if you were really packaging it up), but still have the code get linked into whatever the actual named variable is in the CDN/inline script.

My deployed index.html/jsp that pulls in the parceled project...

   <script>
      config = {
        someValue: 123
      }
   </script>
   <script src="://some-cdn/react.min.js"></script>
   <script src="./build/parceled-up-project.js></script>

And finally... some random source file in my project:

import MyProjectConfig from 'MyProjectConfig'
import React, { Component } from 'react'

For both those imports, the packager can find the 'from' in the externals list, and know that it doesn't need to actually fetch/import anything. And the actual variable names can get assigned with the desired renaming.

Something like this makes the most sense to me... but it's obviously getting away from 'zero-config', so I assume it would need some consensus before building it in. What do you think?

[derolf]

Package.json is not available to the parser. Because resolution is done afterwards.

So, you need two things:

• disable parcel’s parsing if you pull in a prebundled script
• link a module to an exported variable

[DeMoorJasper]

In the current codebase u should look at asset.addUrlDep... and the Resolver as those are the only places we use to actually resolve assets.

I'll try to make it a bit more clear, the parser.getAsset() never gets called if the dependency never gets added to the asset in the first place. The package is known to the parent asset, so you have full access to package.json

[derolf]

@DeMoorJasper I looked a lot at the code this weekend and found the asset.addUrlDep. The problem is that the parsing of the asset, processing, and generating the output is done in a Worker. This Worker has NO access to the resolver, but just creates put dependency-links to the bundles that will contain these dependencies into the processed files.

Then later, the bundler picks up the queued dependencies and resolves (including aliases) them and starts another Worker process.

Check this Bundler: loadAsset(asset)

async loadAsset(asset) {
... FIRST PROCESS
    let processed = this.cache && (await this.cache.read(asset.name));
    if (!processed || asset.shouldInvalidate(processed.cacheData)) {
      processed = await this.farm.run(asset.name, asset.package, this.options);
...
    }
... THEN RESOLVE
    // Resolve and load asset dependencies
    let assetDeps = await Promise.all(
      dependencies.map(async dep => {
...
          let assetDep = await this.resolveDep(asset, dep);
...
      })
    );

...
}

To fix this, we would need to expose the resolver to the Worker and let resolution happen there???

[derolf]

Ah, you mean Assert.pkg? You are right, it's having full access to the package.json!

[DeMoorJasper]

I'm pretty sure if the dependency never gets added, the bundler never picks them up anyway? The resolver changes would just be in case the bundler adds some dependencies.
Now that I looked at it resolver changes aren't even neccessary unless u wanna move the responsibility to the bundler, I haven't tested any of the things i say i'm suggesting as a fix.

And the code sample you show makes sense but doesn't have much to do with the ignore or this issue. It will never get to loadAsset if the asset is ignored, as that happens on the loadAsset of the previous/parent asset.

And if it's really necessary u could spin up a resolver per worker similar to how the parser is being used inside workers, although it would be nice to prevent this.

EDIT: Yes i do mean Asset.pkg (of the parent of the ignored/external package)

[derolf]

So, which syntax do we follow now? An external needs TWO things: where is the file located and what does it export.

Example with cesium js:

"externals": { "cesium": { "exports": "Cesium", // --> this generates a module stub with cesium.exports = Cesium; "file": "node_modules/cesium/Build/Cesium/Cesium.js", // ---> that is the file to be src for the script "copy": "node_modules/cesium/Build/Cesium", // ---> that tells parcel to copy (or symlink) all that content into the public dir } }

"copy" here is important since Cesium.js includes other files from that folder. So, the WHOLE folder needs to be present!

Makes sense?

[MalcolmDwyer]

I still feel like these are two different concepts being mixed up...
https://webpack.js.org/configuration/externals/

The externals configuration option provides a way of excluding dependencies from the output bundles. Instead, the created bundle relies on that dependency to be present in the consumer's environment.

So I'm not following how your Cesium example... (telling parcel to copy/symlink folders to the public dir) is related here. (I'm not saying that's not useful... just not the same as webpack externals concept). That again seems closer to the "aliases" concept.

[derolf]

@MalcolmDwyer well, it's two related problems:

• How do I specify an external (to create a module stub)
• How do I OPTIONALLY bring that external into my public folder (to include it from HTML)

[derolf]

Pull request

Please read the documentation of the patch.

Symlinking or copying was too much black magic, so I implemented two things:

• Externals in package.json. The semantics are the same way as in Webpack, but I only implemented stubbing a global that was exported by the external module (more can be done if needed)
• External references in URLs, i.e. that already exist in the output directory. If the path starts with a /, Parcel assumes the file already exists in the output directory.

[MalcolmDwyer]

I get what you are saying... here's my train of thought, and halfway through I get what you meant. :)

I think you would set up two different parcel targets in that case...
Here's what I would do for the dev vs. build case I was describing. Not sure if it would apply to you:

package.json

"scripts": {
  "build": "parcel build src/index.html",
  "demo": "parcel watch demo/index.html"
}

src/index.html (or just src/index.js if that's what you are building) would not include any links to import the external stuff.

demo/index.html would include the <script> tags pointing either directly to remote CDNs (or maybe to the dist files inside your node_modules... <script src="node_modules/some_lib/dist/index.js"> though I'm not sure that would work the parcel demo server)

... Ok, I get what you're saying now. That demo html is going to be affected by the same 'external'="don't actually import this thing" rule as the JS.

The difference with the equivalent webpack set up is that you have to go out of your way to build an html template for your demo code, and the webpack packager is not going to try to pull in <script> tags no matter what. With parcel, if it sees <script> it's going to go get it.

So this thing would need to be able to differentiate between import React from 'react' in the JS, and treat that one as an 'external', but not ignore the <script src="react.min.js"> when it sees that in demo.html.

[derolf]

Malcom, I think I nicely resolved the problems in the pull request. Please read the doc of the pull request.

[ekoeryanto]

any update about this?

[derolf]

Dead because team doesn‘t like my pull request...

[ekoeryanto]

look like I have to search the alternative bundler

[fathyb]

Can't the 1.7.0 alias be used for that?

• package.json

{
  "alias": {
    "react": "./externals/react",
    "react-dom": "./externals/react"
  }
}

• externals/react.js

module.exports = React

[derolf]

Probably yes. Then the only thing missing is to convince Parcel to ignore the script tags to local prebundled files.

[DeMoorJasper]

@fathyb Maybe we could add externals to package.json?
As this is basically rename or ignore instead of rename and package.
Could possibly even fix the use-case of ignoring as well

Maybe something like this:

externals: {
  "react": "ThisIsReact", // Renames and ignores
  "jQuery": false, // Ignores entirely
  "$": false, // Ignores entirely
  "/externals/**": false // Ignores an entire folder
}

This is bundler specific config, which is not such a good idea but I haven't seen any standardised non bundler specific config of this anywhere?

[fathyb]

@derolf you can use inline JS for that, it's not perfect but it works while we find a correct solution :

<html>
<body>
  <!-- <script src="/lib/foo/index.js"></script> -->
  <script>
    var script = document.createElement('script')

    script.src = '/lib/foo/index.js'
    document.body.appendChild(script)
  </script>
</body>
</html>

OP seems to only talk about module externals (using require or import), we should probably restrict the discussion to this as it will probably require two different approaches. Feel free to follow up in a new issue if there is not one already open for that.

---

Dead because team doesn‘t like my pull request

That's not how it works and nobody ever said that. For the context : #955

1. The PR doesn't have any tests
2. You were already told by Devon :
   > We cannot rely on absolute paths being external. Absolute paths are valid and can be resolved by the new Parcel resolver relative to the project directory
3. If you discussed about it before, like @MalcolmDwyer did in this thread, maybe someone would've told you before that it would conflict with the new resolver. A PR isn't the right place to discuss this given the limited audience.

I totally get and understand that a stale PR can be frustrating but please avoid this kind of non-constructive comments.

[fathyb]

@DeMoorJasper Yup, sounds like the best solution 👍

[ekoeryanto]

@fathyb just take it easy, I am new to parcel. that's why I decide to find an alternative. but yeah, parcel is the best one.

[derolf]

@fathyb Yeah, sorry! And I still love Parcel!

[defmech]

@DeMoorJasper Your solution makes most sense to me. 👍

[DeMoorJasper]

After creating a PR and getting some feedback from @fathyb I think a valid workaround for now would be to alias packages to a file that simply exports the global variable you wanna point it to. This will probably be the way we'll implement it anyway

Turn

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

Into

"alias": {
  "react": "./react-external.js"
}

// This is react-external.js
module.exports = React;

If this works, I'm not sure if we'll even still need externals, as this works pretty decent.

[danielpza]

@DeMoorJasper, your approach is working just fine, but the problem is, I have +7 external dependencies and is exhausting to be making every file for every dependency, a shortcut will be very good

[pgn-vole]

@DeMoorJasper, that's not the correct approach to implement this. What if the reference to the external is not coming from the global but from a commonjs environement ? In that case require('react ') should be injected instead of window.React.

[suconghou]

whatever , some syntax like this is really needed.

<script parcel-ignore src="./libs/abc.js">

use parcel-ignore to keep ./libs/abc.js untouched

[nokola]

I have a related issue, with TypeScript config.
My goal is simple: I want to use TypeScript types for Firebase in VS Code, and load Firebase from CDN.

But I couldn't get it to work with Parcel, so I'm not using Parcel even though I love the 0-config idea and using .ts directly.

Setup:
In index.ts:

import * as firebase from "firebase";

In index.pug:

html
    head
        script(src='https://cdn.jsdelivr.net/npm/[email protected]/firebase.min.js')

Expected:
During bundling, parcel.js does not double-include firebase

Actual:
During bundling, there's an extra 1MB+ file (thus my total website goes from ~40K to ~1MB size) containing second copy of firebase

[mohsen1]

External configuration is pretty conditional. For instance I want to use externals only if I'm building the client bundle for production.

Having them in package.json makes it harder to have such configurations.

I'm currently using this comments suggestion with this condition inside my code module code.

package.json

"alias": {
        "react": "./globals/react.js"
}

./global/react.js

if (!process.env.IS_SERVER && process.env.NODE_ENV === 'production') {
    module.exports = React;
} else {
    module.exports = require('../node_modules/react'); // has to be relative to avoid circular deps 
}

⚠️
But I'm running into this issue when I do that with Lodash:

If a dependency depends on submodules of lodash like this:

require('lodash/assign')

module resolution will fail.

I much rather pass this configuration to the CLI or API.

[nokola]

I switched to webpack, even though I love the no setup of parcel, when it works. My project went down from 5MB to 60K and I'm loving it :)
Also I feel much more confident with the configuration in place that what's needed to happen, happens.
Disclaimer: took 2 days to setup the initial config.

[ravilution]

Honestly, I like @DeMoorJasper 's solution. When compared to the advantages that I get from using Parcel, this small inconvenience is totally fine with me. When I run create react app with WebPack, my CPU burns like anything. I love Parcel + React and this small compromise.
Thank you Parcel Team

[danielpza]

Made a package for this, https://www.npmjs.com/package/parcel-globals, small command line with no test

[ddragosd]

👍 to parcel-globals. Another alternative for cases when a module is not globally available and must be imported, is to use a syntax similar to the one bellow:

let my_module = eval('require("my_module")');

// (updated) or, w/o eval
let _import = require;
let my_module = _import("my_module");

I'm using this in a serverless action in Apache OpenWhisk, where generic NodeJS actions are executed in a docker container with some pre-installed modules.

[sgf]

@DeMoorJasper @externals
i have the same problem.i talking about it in another issue with u.

I have a related issue, with TypeScript config.
My goal is simple: I want to use TypeScript types for Firebase in VS Code, and load Firebase from CDN.

But I couldn't get it to work with Parcel, so I'm not using Parcel even though I love the 0-config idea and using .ts directly.

Setup:
In index.ts:

import * as firebase from "firebase";
In index.pug:

html
head
script(src='https://cdn.jsdelivr.net/npm/[email protected]/firebase.min.js')
Expected:
During bundling, parcel.js does not double-include firebase

Actual:
During bundling, there's an extra 1MB+ file (thus my total website goes from ~40K to ~1MB size) containing second copy of firebase

just i need exclude the Vue.js when deploy.
but when in develop i need do import.

 "exclude": {
      "react": "react.js",
      "vue": "vue.js"
}

if Parcel support,that means Parcel will also better Freindly for Develop MPA(Multi Page App).