Supporting plugins that extract stylesheets for a separate entry point

[erquhart]

Description

Plugins that modify Webpack CSS and CSS preprocessor file loading may overwrite styles output by Gatsby's default CSS and CSS module loaders for production builds.

Why this is happening

The Netlify CMS plugin is the first official plugin to utilize extract-text-webpack-plugin for it's own entry point (#3611). Prior to this, Gatsby used a single instance of the extract plugin, but supporting plugins that output a separate stylesheet requires using multiple instances (#3652). The plugins that load styles for the main style bundle, e.g. sass, stylus, etc., rely on the extract plugin added by Gatsby rather than adding their own, but this stops working correctly when there are multiple extract plugins, an issue that surfaced for projects using both the Netlify CMS plugin and any other plugin that implemented the webpack extract plugin (#4335).

How to address

In #4495, a solution is reached where the Sass plugin retrieves and utilizes the first instance of extract-text-webpack-plugin in the plugins array. This ensures that general site styles that are meant for the main bundle get processed by Gatsby's own extract plugin instance, regardless of any other instances that plugins may have added. This approach relies on plugins never intentionally splicing in their own extract plugin instance before Gatsby's instance. An approach that does not rely on this will involve a fair amount of additional code in all styling plugins.

This solution will need to be implemented in all plugins that utilize extract-text-webpack-plugin, or else these plugins will not work with plugins that use their own extract plugin instance.

Options

I see two ways to do this:

1. Somehow make it easier to get and reuse Gatsby's current stage extract plugin instance for simplicity, and to avoid guessing
2. Implement the fix from sass plugin: use existing extract plugin for current stage #4495

Whatever approach we choose, it will need to be applied to all styling plugins that utilize the extract plugin. Note that none of this points to a breaking change, but a change that must be made if these plugins are to be used in conjunction with other plugins that utilize the extract plugin for separate entry points.

[erquhart]

Update: working on a standalone config helper along the lines of the CSS modules config.

[erquhart]

Update

Thought I already wrote this a while back! Soon after that last comment I opened a PR to create a centralized handler for extract-text-webpack-plugin for use by Gatsby core as well as any plugins contributing to the main style bundle, and an implementation PR updating Gatsby core and the Sass plugin to use the centralized handler for a period of time as an initial test. Both were merged and things seem to be working fine.

Next steps

Other plugins need to follow the implementation example of the Sass plugin in #4559 if they are to be used with plugins like Netlify CMS, which use extract-text-webpack-plugin apart from the main bundle.

Known issues

The original issue, #4335 seems to still remain unresolved for Windows users: #3753 (comment)