JavaScript: Bundle a required, but common, polyfill in my library?

Question

First, here are a couple of related, but not-quite-the-same questions:

• Should I include dependencies for which I have the source as projects in my solution?
• https://softwareengineering.stackexchange.com/questions/35052

Now on to my particular question:

I'm building a small JavaScript library. If run within certain older browsers, part of its functionality will depend on a certain polyfill. For the purposes of an example, let's say this polyfill is the requestAnimationFrame polyfill.

This polyfill is:

• Well-known: Most JavaScript developers are at least vaguely aware of it.
• Available: Copy-pasteable code snippets of variants of it are all over the place.
• Tiny: It's only a few lines of code, really.
• Endemic: Libraries in the same problem space as mine may have it bundled already.

Obviously, if my library were the only library being used in someone's project, and if part of that code could fail without the polyfill in circumstances likely for the developer's audience, it would make sense to bundle the polyfill with the library.

But in the JavaScript world, particularly in this library's domain, it's possible that the developer already has the polyfill, and that by bundling it, I could be re-polyfilling requestAnimationFrame for the second, third, fourth time over. (This itself isn't really an issue, since most polyfills by their very nature include a pre-check of the namespace. But, I admit, the thought of the same polyfill appearing multiple times in someone's code bothers me like a painting hung slightly crooked.)

So what is the sensible thing to do? Include it? Or just leave a note in the documentation that says, "By the way, make sure you have the Polyfill X if you need to support Browser Y"?

Answer 1

Your decision will be based on the following factors:

1. Is there a well-known, stable, reliable Javascript library that contains the polyfill function I need, available in its externally-published API?
2. Is it worth the costs* to require the users of my library to take a dependency on that other library to get the required polyfill function that my library needs?

If you can't answer yes to both of those questions, grit your teeth and copy/paste the small amount of code that you need (assuming there are no licensing restrictions).

*_{Requiring another library will cause some code that you won't even need to be loaded in every web page. That's not the only cost.}

Further Reading
The DRY Obsession

Answer 2

Based on your requirements, do include it. Robert Harvey has given good reasons as to why. I am going to talk about how.

You said the polyfill is tiny. But if you include it again, and several other libraries your users are also including on their pages add it, you will be adding to the issue.

You can take a couple of approaches.

The first approach would be to do what most frameworks do, have a global instance of your framework with any associated child frameworks contained in your namespace (jsLite in AngularJS comes to mind). This will guarantee that the child framework is there, works, you know where it is, and that the version you need is loaded. But it fails DRY.

The next approach is to go the global availability route, where you load the child framework into the object prototype, checking to make certain that it isn't already loaded. With this approach, you run the risk of a different revision of the child framework being loaded. As often as not, this will break your functionality due to interface breaking.