Add polyfill use case to FAQ

[keithZmudzinski]

I recently spent some time struggling with the correct way to import a polyfill.
I wanted to add that use case to the FAQ section of the readme, in case it helped anyone else.

I know this issue isn't specific to ember-auto-import, but I do think this is a good place to shed some light on it, seeing as how this will be the first stop many developers will have when they run into import-related problems in their Ember apps.

I don't have permissions to push up a branch and open a PR, and I wasn't sure how to request it, so I'll just add my suggested contribution here.

Suggested addition to FAQ, as last item in that section:

---

I want to import an already transpiled polyfill file.

Oftentimes packages that implement polyfills provide an already transpiled js file ready for use.

To use already transpiled files, you can simply import the file directly.
Any modifications the polyfill may have on the global namespace will take affect.

Example:
The eventsource package provides a ready to use eventsource-polyfill.js file.
This can be imported like:

// In whatever file you need to access the polyfill.
// Importing the polyfill adds a new global object EventSourcePolyfill.
import 'eventsource/example/eventsource-polyfill.js';

[ef4]

Hi, thanks for working on this.

If I'm understanding you correctly, the thing that would be helpful in the FAQ is showing an import for side-effects only? (like the MDN docs you linked to)

I think saying "already transpiled" is potentially misleading, since ember-auto-import will re-transpile whatever you import (other than the skipBabel option).

[keithZmudzinski]

showing an import for side-effects only

Yes, that's the core of it. Importing an entire module without importing any values

[keithZmudzinski]

Here's an updated proposal that just focuses on importing a package for side affects, and doesn't mention transpiling.

Thoughts on using the work 'package' vs 'module' ? I'm not sure which is technically more correct in this context

---

I want to import a package for side affects only.

Some packages, often times polyfills, don't provide values meant for direct import. Instead, the package is meant to provide certain side affects, such as mutating global variables.

To import a package for side affects only, you can simply import the package directly.
Any side affects the package provides will take affect.

Example:
The eventsource package provides a ready to use eventsource-polyfill.js file.
This can be imported like:

// In any js file, likely the file you need to access the polyfill, purely for organization.

// Importing the polyfill adds a new global object EventSourcePolyfill.
import 'eventsource/example/eventsource-polyfill.js';

[ef4]

In your example eventsource is a package and eventsource/example/eventsource-polyfill.js is a module. I think it's probably more technically correct to say "I want to import a module...".

You can open a PR with this change from directly within GitHub in the browser. Go to https://github.com/embroider-build/ember-auto-import/blob/main/packages/ember-auto-import/README.md and use the Pencil icon which has the tooltip label "Fork this repository and edit the file"