Proposal: Handling Polyfills in Application and Package Dependencies

[kevinrodrigues]

Proposal: Handling Polyfills in Application and Package Dependencies

I refer to DSW-1780 in this proposal.

Key

1. Application Developer: - An application developer = consuming team / application

2. Polyfills: - Polyfills are code snippets or scripts that provide modern functionality in older browsers that lack native support for those features. They help ensure consistent behavior across different browsers.

3. Package Maintainer: - A package maintainer is an individual or group responsible for managing and maintaining a software package. In the context of this discussion, I refer to those who develop and release packages (e.g., libraries, components) that can be used by application developers. = i.e Design System Team (PIE)

Preface

This proposal suggests a best practice for handling polyfills in both application and package dependencies. The aim is to streamline the integration of polyfills, recognising them as an application concern, and allowing flexibility in choosing the necessary polyfills based on browser support. Additionally, it addresses the need for aligning components with Lit's recommendations for enhanced compatibility.

Proposal

For Application Developers

1. Direct Dependency on Polyfills: Polyfills are an application concern, and the application should directly depend on them rather than individual packages. This allows the application developer to have control over the polyfills used based on the browsers they need to support.

2. Documentation Clarity: Component documentation should clearly identify any APIs that require polyfills. This allows the application developer to make informed decisions on which polyfills to include based on the specific needs of their application. In my opinion we should probably not document it and just leave it to the application developer to polyfill as required on a as needs basis.

For Package Maintainers

1. Polyfills in devDependencies: Packages may need to depend on polyfills for tests and demos (See section DevDependencies and Polyfills for Tests for more detail). If polyfills are required, they should only be included in the devDependencies section of the package's package.json file. This ensures that polyfills are not included in the production build, preventing unnecessary dependencies for end-users.

2. Lit's Recommendations Compliance: Components should align with Lit's recommendations to enhance compatibility and interoperability. Current components not following Lit's guidelines should be updated to ensure a consistent and well-supported development experience.

Example

Application Dependencies

// package.json of the application
{
  "dependencies": {
    "pie-modal": "1.0.0",
    "polyfill-package": "2.0.0"
  }
}

Component Documentation

#### Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari 14+ (IOS)

#### Required Polyfills

- [polyfill-package](link-to-polyfill-package-docs)

Package Dependencies

// package.json of the package
{
  "devDependencies": {
    "polyfill-package": "^2.0.0"
  }
}

What does this mean for our current components?

Existing Polyfills within Components

Several of our current components, such as pie-modal, include internal polyfills. As part of the proposed changes, we aim to refactor these components to remove internal polyfills. This move will ensure a cleaner separation of concerns and empower application developers to manage polyfills based on their specific needs.

Example: Refactoring pie-modal

Current State:

pie-modal includes an internal polyfill for certain browsers.

Proposed Changes:

1. Polyfill Removal:

   • Remove the internal polyfill from the pie-modal component.

2. Documentation Update:

   • Update the pie-modal readme documentation to clearly communicate the removal of the internal polyfill and document that the application developer will require a polyfill if they require support in older browsers e.g IOS Safari 14 etc.

Benefits of Refactoring

1. Cleaner Components:

   • Components will be free from internal polyfills, reducing complexity and potential conflicts.

2. Application Developers:

   • Application developers gain more control over polyfills, allowing them to choose and manage polyfills based on their application's browser support requirements.

DevDependencies and Polyfills for Tests

In addition to the changes mentioned above, it might be essential to address the use of polyfills specifically for testing, demos, or mocking. These polyfills should be included in the devDependencies section of the package's package.json file. This practice ensures that these polyfills are only installed when developers are working on the package, avoiding unnecessary dependencies in production builds.

Updated package.json for Tests:

// package.json of the package
{
  "devDependencies": {
    "polyfill-package": "1.0.0"
  }
}

Discussion

Feel free to leave any comments.

[xander-marjoram]

This all sounds good to me! I have one question though: what is the scenario where we need to be importing the polyfill for testing? If the argument is that those are application concerns then perhaps it's also an argument that those sorts of tests belong in pie-aperture, and therefore don't need to be listed in the component's devDependencies at all? What do you think?

If it's for something like visual regression tests so that we can catch regressions early before they reach aperture then that's probably okay as-is.

[kevinrodrigues]

@xander-marjoram A very valid point. I've put down my thoughts below. Let me know what you think.

I agree in that if a polyfill isn't being imported into a component, there's likely no scenario necessitating its inclusion in tests. However, as you highlighted, to ensure our component are not breaking anything (e.g. Safari 14), considering instances like the Modal component where certain functionalities reliant on the dialog element might require polyfills for full functionality I think it is probably a good idea to keep it only for these types of scenarios. I would probably caveat that with the application developer opting to use a different polyfill than the one we've tested or even a newly released polyfill which might negate the need to actually include it in our packages at all.

[jamieomaguire]

Thanks @kevinrodrigues, this sounds like a good proposal. One minor nitpick, please could we specify that we are supporting iOS Safari 14+? I believe it's the same version for MacOS, but caniuse sometimes shows APIs that work in one MacOS Safari version but a different on iOS. For example gap for flexbox.

I do personally think we should make Polyfill recommendations for consumers. Otherwise, I can see us constantly being asked for suggestions.

My question would be:

Going forward, how do we ensure we are identifying features that require polyfills? Can we add a step to our development and review process to prevent things getting merged without being spotted?

[kevinrodrigues]

@jamieomaguire Thanks for the input. I've replied below to try and answer:

1. IOS support (14+), Are you suggesting we should cover this in the readme for our components that require polyfills? If so, I can add a line about this in the ticket for polyfilled components.
2. I agree with the polyfill recommendation for consumers point, I had a point about that above in the proposal but wanted thoughts on it so will include this in the readme as part of the referenced ticket too.
3. Regarding the last point, I believe this falls within the scope of work for ticket creation. spikes etc. This proposal primarily focuses on existing components and future ones, assuming we've already determined the need for a polyfill during ticket creation / refinement or after a spike.

[jamieomaguire]

@kevinrodrigues

IOS support (14+), Are you suggesting we should cover this in the readme for our components that require polyfills? If so, I can add a line about this in the ticket for polyfilled components.

Basically anywhere we say we support safari 14, I think it would be useful to say iOS Safari 14 instead. This is clearer for the reasons I mentioned above :)

[ashleynolan]

This all looks good, and I agree with the points raised above, which it looks like have been addressed now potentially.

The only thing that I think could be useful in the future, would be to provide a PIE polyfill plugin that loads in the polyfills needed to match our current level of browser support. I think we'd need to scope this out properly, but in essence all it would be is an NPM package that loads in a bunch of polyfills for users who want to match our own level of browser support (maybe they can also opt in to which polyfills through a small amount of config). For example, currently this package would include the dialog polyfill, form polyfills etc.

I see this as being useful for a couple of reasons:

• Avoids us having to answer inevitable questions about which polyfills to use (or that we recommend)
• Helps reduce duplicate effort across teams – especially for microsite architectures - where teams are having to maintain polyfill implementation.

Would be good to hear thoughts on this. This absolutely wouldn't be a part of the current bundling epic, but most likely it's own mini-epic that we could look at doing in Q2 onwards.

[kevinrodrigues]

@ashleynolan that's a good idea. I did have the thought below:

If a growing number of our components require more and more polyfills, if we remove them from individual components it may not offer significant benefits, as it merely shifts the responsibility to install them via another package albeit on their end. While Lit advises removing polyfills because they're considered application developer concerns, if all our application developers are using the same polyfill configuration or setting based on the same browsers, maintaining the current setup might be more practical what do you think? It kind of goes against the point of my main discussion though :D

[ashleynolan]

I would think over time our components should hopefully require less polyfills.

I think removing them from the components is the right thing to do (as it means those apps that don't want them don't have to install them). But I think having a standardised/recommended set of polyfills that can be installed somehow will likely help us with any questions around support in the future too.

[jamieomaguire]

@kevinrodrigues I would still suggest applications manage these polyfills even if we see the same being used again and again. It gets murky otherwise and not clear when we should/shouldn't include stuff in our component artifacts (in my opinion)

[kevinrodrigues]

I will be creating a ticket around the polyfill package to see if we can create a package that can be used to house our Polyfills first and in turn be installed in applications. I think it makes sense to take a look at this package before we remove any polyfills from our components just so it is easier later down the line when we come to remove these polyfills from our components. This way we can then install the new polyfill package at the same time rather than removing the polyfill code from individual components now and having to patch it temporarily in say pie-aperture to then have to remove that patch later if that makes sense.