Documentation for features postcss-preset-env features that need polyfills should be less confusing

[dpschen]

Hello csstools team,

First of thanks for your amazing work!
I struggled a bit to configure postcss correctly to enable a plugin that requires a polyfill. In the following my train of thought in the sequence it happened to me while trying to make that feature work.

---

1. In the README.md of the postcss-preset-env pack under enableClientSidePolyfills it is written that:

• This only controls if the PostCSS plugins are enabled. It does not cause the browsers libraries to be included in your bundle.

2. At the same time it is said that:

• Note that manually enabling/disabling features via the "feature" option overrides this flag.

3. Now under "Plugins that need client library
   " there is a list of all the libraries with each a link to the plugin and the polyfill.

For my project I only need the focus-within-pseudo-class feature.

4. Checking now the documentation of that plugin it is written:

PostCSS Focus Within works in all major browsers, including Safari 6+ and Internet Explorer 9+ without any additional polyfills.

… which really confused me because:

Isn't the example given there a way to add a polyfill?

5. Then again in the documentation of "Plugins that need client library
   " it is also written that:

If you want to disable these types of features, please check the enableClientSidePolyfills option.

(I later realised that this should probably be changed to something like If you want to enable all of these types of features [?])

---

I ended up with something that seems to be working by manually enabling the feature I wanted and manually importing the polyfill like this:

import focusWithin from 'focus-within'

focusWithin(document)

---

I'm still unsure if this is the correct way.
For me my own solution is fine I only want to spare the next person to go through all of this again :)

Basically it seems that there is a missing documentation of how to integrate the plugins that when you use the postcss-preset-env pack.

[romainmenke]

Hi @dpschen,
Thank you reaching out!

We agree that this is confusing.

Part of the issue here is that we lack precise enough words and terms that are widely known and understood. So we end up re-using terms multiple times, each time point to a different thing.

• plugin : something that changes your CSS in your build step
• client-side polyfill : something that runs in the browser of a visitor
• additional polyfill : not this polyfill, something else

---

enableClientSidePolyfills exists as a single flag that controls multiple plugins because these plugins used to be enabled by default. Setting it to false allowed you to disable all of them at once. Almost all users of postcss-preset-env want to have all of them disabled.

With the recent version 8 we flipped this flag so that it is disabled by default.
You could still use it today if you want to always run all these types of plugins.

Much more likely that you want to do this :

{
  "features": {
    "focus-within-pseudo-class": true
  }
}

---

PostCSS Focus Within works in all major browsers, including Safari 6+ and
Internet Explorer 9+ without any additional polyfills.

@Antonio-Laguna I think we should remove this line.

1. IE9+ doesn't mean the same today as it did when this was written.
2. It isn't adding any clarity to the whole readme

thoughts?

---

(I later realised that this should probably be changed to something like If you want to enable all of these types of features [?])

Yes, this was a line from when the flag had the old default.
I will update this.

---

I'm still unsure if this is the correct way.

Is it working correctly in the browser? :)
I think that if it works it will likely be correct.

---

Basically it seems that there is a missing documentation of how to integrate the plugins that when you use the postcss-preset-env pack.

I think the docs are complete, but it is impossible to describe this in a way that is immediately clear for everyone, for all stacks, for all frameworks, ...

There are too many unknowns from our perspective.

[Antonio-Laguna]

I think we should remove this line.

I'm not sure if we should remove that. What that implies is that you don't need any extra polyfill (besides the current one) to get this working. If you're below Safari 6 and IE 9 you might need extra polyfills. Should we reword it?

[romainmenke]

But no one is below Safari 6 or IE 9 anymore, and if they are, they got bigger problems than our documentation 🤣

[Antonio-Laguna]

I agree yet I think there shouldn't be any harm in mentioning the lowest version the polyfill works with?

[romainmenke]

True :)

Maybe best to keep that as is.
It can be confusing at times, but the sentence and wording is not incorrect.

[romainmenke]

Thank you again for explaining how these docs were confusing to you @dpschen 🙇
We have made a few small edits which hopefully help the next person.

We will keep this in mind if we receive further feedback.