Question: what changed to cause webVitals to be undefined when loading https://unpkg.com/web-vitals as previously documented?

[adamhenson]

Hello - I provide a service and encouraged several users to consume the Web Vitals library as documented. I've been receiving complaints of an error that users are seeing who have loaded the Web Vitals library.

webVitals is undefined

I've pinpointed a common denominator that those who have this issue are using the previous example from the docs:

<!-- Without the `?module` param, the UMD version is loaded and sets the `webVitals` global -->
<script defer src="https://unpkg.com/web-vitals"></script>
<script>
  addEventListener('DOMContentLoaded', function() {
    webVitals.getCLS(console.log);
    webVitals.getFID(console.log);
    webVitals.getLCP(console.log);
  });
</script>

Which has been replaced with this:

<script>
  (function() {
    var script = document.createElement('script');
    script.src = 'https://unpkg.com/web-vitals/dist/web-vitals.iife.js';
    script.onload = function() {
      webVitals.getCLS(console.log);
      webVitals.getFID(console.log);
      webVitals.getLCP(console.log);
    }
    document.head.appendChild(script);
  }())
</script>

I did reproduce the error and replacing it with the new snippet fixes the issue.

It seems that this change occurred in 9f9a2cc. From my perspective this is a breaking change. Am I mistaken? What changed in https://unpkg.com/web-vitals in which the library doesn't support the original example? I'd love to have this data to pass along to my users and so I can apologize that their implementation unexpectedly stopped working and explain why.

I'm probably missing something... some announcement, etc. Or at least was there a PR that explained this change?

Any info that I can pass along would be appreciated.

[philipwalton]

Hey @adamhenson, sorry this is affecting you. Unfortunately I don't think I have a lot of good options to help you, but I'll explain what happened and hopefully we can talk through the best solution.

In v3 I updated the package to declare type: module to support Node 16+, which means that any file in the repo that is not a module needs to have a .cjs extension (for CommonJS).

The change was essentially this:

-"main": "dist/web-vitals.umd.js",
+"main": "dist/web-vitals.umd.cjs",

This shouldn't have affected anyone who was loading the library via the URLhttps://unpkg.com/web-vitals; however, I discovered recently (from an internal issue filed), that the unpkg.com CDN does not set the proper MIME type for .cjs files, which prevents the browser from executing these scripts, and so that's why your users as seeing this error.

I've reached out to unpkg.com and they seem willing to fix, but I don't think a fix has been rolled out just yet.

Unfortunately I cannot release a version without the .cjs URL or that would cause errors for people consuming the library in Node.js 14 (which is still in LTS).

So I think your best option is to update your service to use the IIFE version as currently documented (which contains a .js extension). Alternatively you could use the module version, which honestly I'd recommend anyway since all browser that support these metrics also support module scripts.

Hopefully unpkg.com will update soon and this will no longer be an issue, but if you need an immediate fix, I'd recommend updating.

From my perspective this is a breaking change. Am I mistaken?

Unfortunately, if you depend on an unversioned URL like https://unpkg.com/web-vitals then you're opening yourself up to breaking changes. I've tried to keep all breaking changes to a minimum (and make most things backwards compatible), but we have to be able to make some breaking changes from time to time, and we communicate those changes via the major version bump.

Admittedly, the documentation does explicitly reference these unversioned URLs, so it's understandable why someone would make that mistake. (I'll take the blame for that.)

I think it probably makes sense to update the CDN examples to use a URL like:
https://unpkg.com/web-vitals@^3.0.0?module

What do you think? I know that doesn't prevent your current situation, but do you think that would have helped if I had done that in the past?

[adamhenson]

Hi @philipwalton - thanks so much for the clarification!

I'll just relay the message to use the new example and justify it with the unpkg.com issue and the fact that we're referencing the unversioned URL. I didn't feel 100% confident in referencing it that way, but I didn't really know what versioning patterns would make sense. The documentation has changed a lot from where it was when I was referencing it, so I think it's fine now - there is a note about using a pinned version I believe. I'll just make a note in the example that I have to reference the GitHub project and choose a version that makes the most sense to you.

Thanks again for the quick, in-depth answer. That's all I was really asking for - hence closing this. And thanks for all your work on this project. Interesting how widely adopted / marketed it has become.

[adamhenson]

And just to be clear...

What do you think? I know that doesn't prevent your current situation, but do you think that would have helped if I had done that in the past?

I think it's much clearer now, and the documentation probably doesn't need to be changed. It could be helpful to show example URL patterns for those that aren't super familiar with unpkg.com (like me :embarrassed:)... I think it would have helped me in the past to not be in the situation I'm in now... but I take some of the blame there for not researching unpkg.com more.

[philipwalton]

Thanks. Just in case it's useful I added these changes to the README to clarify: 5d7a0fe

[adamhenson]

Thanks so much @philipwalton

[philipwalton]

FYI: I just discovered there's an unpkg field that I can explicitly set in package.json, so this should fix the issue for anyone else: #261

[adamhenson]

Excellent, thanks @philipwalton.