Improving Browser Polyfills docs for Next.js (#716)

* Creating sample doc

* Adding docs for all packages

Author: Antonio-Laguna

plugins/css-blank-pseudo/README.md

@@ -186,6 +186,21 @@ Please note that using a class, leverages `classList` under the hood which
 might  not be supported on some old browsers such as IE9, so you may need 
 to polyfill `classList` in those cases.
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const cssBlankPseudoInit = (await import('css-blank-pseudo/browser')).default;
+	cssBlankPseudoInit();
+}, []);
+```
+
+We recommend you load the polyfill as high up on your Next application as possible, such as your `pages/_app.ts` file.
+
 [cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
 [css-url]: https://cssdb.org/#blank-pseudo-class
 [discord]: https://discord.gg/bUadyRwkJS

plugins/css-blank-pseudo/docs/README.md

@@ -146,5 +146,20 @@ Please note that using a class, leverages `classList` under the hood which
 might  not be supported on some old browsers such as IE9, so you may need 
 to polyfill `classList` in those cases.
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const cssBlankPseudoInit = (await import('<packageName>/browser')).default;
+	cssBlankPseudoInit();
+}, []);
+```
+
+We recommend you load the polyfill as high up on your Next application as possible, such as your `pages/_app.ts` file.
+
 <linkList>
 [Selectors Level 4]: <specUrl>

plugins/css-has-pseudo/README.md

@@ -198,7 +198,6 @@ By default the polyfill will not emit errors or warnings.
 cssHasPseudo(document, { debug: true });
 ```
 
-
 ### Browser Dependencies
 
 Web API's:
@@ -271,6 +270,21 @@ HTML might look like this :
 ```
 
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const cssHasPseudo = (await import('css-has-pseudo/browser')).default;
+	cssHasPseudo(document);
+}, []);
+```
+
+We recommend you load the polyfill as high up on your Next application as possible, such as your `pages/_app.ts` file.
+
 ## How it works
 
 The [PostCSS Has Pseudo] clones rules containing `:has()`,

plugins/css-has-pseudo/docs/README.md

@@ -174,7 +174,6 @@ By default the polyfill will not emit errors or warnings.
 cssHasPseudo(document, { debug: true });
 ```
 
-
 ### Browser Dependencies
 
 Web API's:
@@ -198,6 +197,21 @@ ECMA Script:
 
 <corsWarning>
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const cssHasPseudo = (await import('<packageName>/browser')).default;
+	cssHasPseudo(document);
+}, []);
+```
+
+We recommend you load the polyfill as high up on your Next application as possible, such as your `pages/_app.ts` file.
+
 ## How it works
 
 The [<humanReadableName>] clones rules containing `:has()`,

plugins/css-prefers-color-scheme/README.md

@@ -288,6 +288,19 @@ HTML might look like this :
 ```
 
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const prefersColorSchemeInit = (await import('css-prefers-color-scheme/browser')).default;
+	const prefersColorScheme = prefersColorSchemeInit();
+}, []);
+```
+
 ## How does it work?
 
 [Prefers Color Scheme] is a [PostCSS] plugin that transforms `prefers-color-scheme` queries into `color` queries.

plugins/css-prefers-color-scheme/docs/README.md

@@ -164,6 +164,19 @@ ECMA Script:
 
 <corsWarning>
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const prefersColorSchemeInit = (await import('<packageName>/browser')).default;
+	const prefersColorScheme = prefersColorSchemeInit();
+}, []);
+```
+
 ## How does it work?
 
 [<humanReadableName>] is a [PostCSS] plugin that transforms `prefers-color-scheme` queries into `color` queries.

plugins/postcss-focus-within/README.md

@@ -179,6 +179,19 @@ focusWithinInit({ replaceWith: '.focus-within });
 
 This option should be used if it was changed at PostCSS configuration level.
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const focusWithinInit = (await import('postcss-focus-within/browser')).default;
+	focusWithinInit();
+}, []);
+```
+
 [cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
 [css-url]: https://cssdb.org/#focus-within-pseudo-class
 [discord]: https://discord.gg/bUadyRwkJS

plugins/postcss-focus-within/docs/README.md

@@ -141,5 +141,18 @@ focusWithinInit({ replaceWith: '.focus-within });
 
 This option should be used if it was changed at PostCSS configuration level.
 
+### Using with Next.js
+
+Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.
+
+As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:
+
+```jsx
+useEffect(async () => {
+	const focusWithinInit = (await import('<packageName>/browser')).default;
+	focusWithinInit();
+}, []);
+```
+
 <linkList>
 [Selectors Level 4 specification]: <specUrl>