[docs] Document config.clientBootstrap

[harriha]

The recently added config option for adding a custom bootstrap file to the main bundle is mentioned only in comments here and there so far, so thought to turn this into an actual task for clarity.

References:

• Force some polyfill into de bundle #2969 (comment)
• Allow extra scripts to be part of the main bundle #1556 (comment)

• I have searched the issues of this repository and believe that this is not a duplicate.

Expected Behavior

I'd expect to

• find config.clientBootstrap documented in main README
• find an example showing how to use this (suggestion: use something common like babel-polyfill in the example to help issues such as Babel polyfill doesn't seem to be injected #2468)

As a side note, it seems that there are no tests exercising this config option, but perhaps that can be seen as a different task than these docs.

Notes

Something to be aware of with this config (and the docs): sadly this option does not help with everything. I tried to add EventSource polyfill for webpack-hot-middleware to make the dev mode work in IE11, but this custom bootstrap is injected too late and thus it does not help with this kind of polyfilling.

[timneutkens]

@arunoda made an example internally, he can commit it to the repository 👍

[designspin]

I'm trying to run a polyfill for intersection-observer using the clientBootstrap:

async function loadPolyfills() {
	const polyfills = [];
	console.log("Running polyfills!");
	if(!supportsIntersectionObserver()) {
		polyfills.push(import('intersection-observer'))
	}

	let all = await Promise.all(polyfills);
	return all;
}

function supportsIntersectionObserver() {
	return (
		'IntersectionObserver' in global &&
		'IntersectionObserverEntry' in global &&
		'intersectionRatio' in IntersectionObserverEntry.prototype
	)
}

loadPolyfills().then((polyfills) => {
	console.log(polyfills);
});

Unfortunately my react code is starting before the polyfill loads. What am I missing here?

[arunoda]

We might remove clientBootstrap feature from Next.js in the future.
So instead use this: #3568

It's the same as clientBootstrap, but just using webpack config.

[arunoda]

@designspin your issue is because of the promise usage.
Try to load polyfills using NPM as shown in the ^^ mentioned example.
If not, start a new issue.