Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft a page on polyfills #38326

Merged
merged 7 commits into from
Mar 4, 2025
Merged

Draft a page on polyfills #38326

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
883d90b
Add a page on polyfills
wbamberg Feb 25, 2025
c084dd0
...
wbamberg Feb 25, 2025
19b9822
Review
wbamberg Feb 25, 2025
6c95ed4
Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/i…
wbamberg Feb 27, 2025
066ebcb
Update files/en-us/mdn/writing_guidelines/page_structures/polyfills/i…
wbamberg Mar 3, 2025
60c1dbc
Review feedback
wbamberg Mar 4, 2025
dea3c68
Merge remote-tracking branch 'origin/polyfills' into polyfills
wbamberg Mar 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions files/en-us/mdn/writing_guidelines/page_structures/polyfills/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
title: Polyfills
slug: MDN/Writing_guidelines/Page_structures/Polyfills
page-type: mdn-writing-guide
sidebar: mdnsidebar
---

This page outlines MDN's policy for including polyfills in the reference documentation for [JavaScript](/en-US/docs/Web/JavaScript) and [Web APIs](/en-US/docs/Web/API).

A {{glossary("Polyfill", "polyfill")}} is an implementation of a web platform feature that websites can use in browsers that do not natively support the feature. Polyfills enable web developers to write a single codebase targeting multiple browsers and browser versions, even when some of those browsers don't support some of the features used.

Polyfills are important to web developers but are also a risk: buggy polyfills can break websites or create security vulnerabilities. For this reason, MDN recommends specific sources for polyfills, and is very conservative about adding additional sources.

## Polyfills in the JavaScript reference

### Selected polyfills

The [JavaScript reference documentation](/en-US/docs/Web/JavaScript) can link to polyfills from two sources:

- The [core-js](https://github.com/zloirock/core-js/tree/master) library.
- The [es-shims](https://github.com/es-shims) organization.

Sources are selected by the MDN maintainers based on the following criteria:

- Conformance to the specification for the feature for which they are providing an implementation.
- Adoption by the web development community, as seen in metrics such as the number of [npm](https://www.npmjs.com/) downloads.

### Proposing an additional polyfill source

Anyone can propose that MDN should recognize an additional source of polyfills by [starting a discussion in the MDN discussion forum](https://github.com/orgs/mdn/discussions). However, the MDN maintainers expect the number of recognized polyfills linked from MDN to remain very small, to reduce the risk of recommending polyfills that cause problems for web developers.

### Integration of polyfills into pages

When a page in the JavaScript reference documentation links to a polyfill, it adds the link in the "See also" section at the end of the page.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can even copy the exact wording we use:

- [Polyfill for `featureName` in `project-name`](link)

And mention that they should be at the top of the list


The link is placed at the start of the "See also" list, in the following format:

```md
- [Polyfill for `featureName` in `project-name`](link)
```

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When should it be removed? My understanding is that we remove the links when there is support in all browsers in the head revision. Needs to be confirmed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above ^ My personal vote is to keep them forever, since any responsible software needs to support browsers that are at least a few years old.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no firm opinion. If ^^^ is agreed, then it is worth spelling out the policy though.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As #38326 (comment) says, I'd prefer to defer these conversations. This PR is just to move things along a bit, so we can even have a documented polyfill policy, and allow other polyfills than core-js. That alone has taken several years to get done!

## Polyfills in the Web API reference

### Selected polyfills

The [Web API reference documentation](/en-US/docs/Web/API) can link to polyfills that are maintained alongside the specification for the feature itself.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems a little vague. Maybe a few examples would help.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, well for example the repo that hosts the trusted types specification includes a polyfill: https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill. Is it enough to add that as an example or do we need to come up with some general form of words for it? "maintained in the same repo as the spec" seems a bit restrictive?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "maintained by the spec champions"? "Officially endorsed"? I'm not sure how blessed that polyfill is; I just know that TC39 is very cautious not to endorse any polyfill, even one developed by the champions themselves. But in any case yes a link to that page is what I'm looking for at the minimum.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "maintained by the spec champions"? "Officially endorsed"?

But (if we're going to be picky) these also seem vague. Who are the spec champions, and do we know that they maintain it, or just that they trust the people who do. And what does official endorsement look like? I mean in the TT case, I'm pretty sure I want MDN to link to it, and I'm pretty sure I trust it, because it's in the same repo as the spec, and I would assume that the maintainers keep that repo under control. I suppose "maintained alongside" is supposed to be a version of "maintained in the same repo as", with a little extra wiggle room in case it ends up in a separate repo.

Copy link
Contributor

@ljharb ljharb Feb 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each TC39 proposal has one or more champions. It is very rare for a champion to maintain a polyfill for that proposal, unless the champion happens to be me.

For web APIs, I'm not aware of the status, but I don't think there's that many web API polyfill authors out there.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright that sounds reasonable. Linking to that example would still help.


For example, the [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) has a polyfill which is [maintained in the same repository as the specification](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill). Accordingly, the Trusted Types API reference documentation on MDN can link to that polyfill.

### Integration of polyfills into pages

Polyfills are typically integrated into the [overview page for the API](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Page_type_key#web_api_page_types).