global-styles plugin doesn't work well alongside the sass-plugin

[fullofcaffeine]

Summary

I'm trying to use the gatsby-plugin-global-styles to re-order the css link tags so they come before the style tag added by gatsby-plugin-typography, but it seems they don't play along well (or maybe I'm missing something?).

I followed the instructions but when I import the scss file, something in gatsby (I couldn't find out what yet) just injects them to the bottom of the header tag, always. It doesn't matter if I use this plugin or try to re-order the typography header component in gatsby-ssr.js. So, my sass styles are loaded lastly (in this case Bootstrap 4) and they end up breaking the typeface styles from Typography.js.

I also added the gatsby-plugin-global-styles configuration snippet below the one for gatsby-typography, as instructed by the docs here, and as you may see below.

Environment (if relevant)

System: OS: Linux 4.15 Linux Mint 18.3 (Sylvia) CPU: (8) x64 Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz Shell: 5.1.1 - /bin/zsh Binaries: Node: 10.14.1 - ~/.nvm/versions/node/v10.14.1/bin/node Yarn: 1.12.3 - /usr/bin/yarn npm: 6.4.1 - ~/.nvm/versions/node/v10.14.1/bin/npm Languages: Python: 3.6.5 - /home/myuser/.pyenv/shims/python Browsers: Chrome: 79.0.3945.88 Firefox: 72.0.1 npmGlobalPackages: gatsby-cli: 2.8.27 gatsby-plugin-typography: 2.3.21

File contents (if changed)

gatsby-config.js:

const path = require('path');

module.exports = {
  pathPrefix: "/",
  siteMetadata: {
    title: `foo`,
    description: `bar`,
    author: `me`,
  },
  plugins: [
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
    `gatsby-plugin-react-helmet`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: path.join(__dirname, `src`, `images`),
      },
    },
   {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `gatsby-starter-react-bootstrap`,
        short_name: `react-bootstrap`,
        start_url: `/`,
        background_color: `#20232a`,
        theme_color: `#20232a`,
        display: `minimal-ui`,
      },
    },
    {
      resolve: `gatsby-plugin-typography`,
      options: {
        pathToConfigModule: `src/utils/typography`,
      }
    },
    {
      resolve: `gatsby-plugin-global-styles`,
      options: {
        pathToConfigModule: `src/utils/GlobalStyleComponent`,
        props: {} // this is required for the damn thing to compile
      },
    },
   `gatsby-plugin-sass`,
   'gatsby-plugin-favicon',
  ],
}

package.json:

{
  "name": "gatsby-starter-react-bootstrap",
  "private": true,
  "description": "A starter that includes and configures react-bootstrap and react-icons, along with SASS handling. ",
  "version": "0.1.0",
  "author": "Billy Jacoby <billyjacoby@gmail.com>",
  "dependencies": {
    "@nfront/global-styles": "^1.2.1",
    "bootstrap": "^4.3.1",
    "clsx": "^1.0.4",
    "gatsby": "^2.19.8",
    "gatsby-image": "^2.2.39",
    "gatsby-plugin-favicon": "^3.1.6",
    "gatsby-plugin-global-styles": "^1.0.17",
    "gatsby-plugin-google-analytics": "^2.1.34",
    "gatsby-plugin-manifest": "^2.0.29",
    "gatsby-plugin-offline": "^2.0.25",
    "gatsby-plugin-react-helmet": "^3.0.12",
    "gatsby-plugin-react-svg": "^3.0.0",
    "gatsby-plugin-sass": "^2.0.11",
    "gatsby-plugin-sharp": "^2.4.3",
    "gatsby-plugin-typography": "^2.3.21",
    "gatsby-source-filesystem": "^2.0.33",
    "gatsby-transformer-sharp": "^2.3.13",
    "node-sass": "^4.12.0",
    "prop-types": "^15.7.2",
    "react": "^16.8.6",
    "react-bootstrap": "^1.0.0-beta.8",
    "react-dom": "^16.8.6",
    "react-helmet": "^5.2.0",
    "react-icons": "^3.6.1",
    "react-typography": "^0.16.19",
    "typography": "^0.16.19",
    "typography-theme-fairy-gates": "^0.16.19",
    "typography-theme-funston": "^0.16.19"
  },
  "devDependencies": {
    "gh-pages": "^2.0.1",
    "prettier": "^1.17.0"
  },
  "keywords": [
    "gatsby"
  ],
  "license": "MIT",
  "scripts": {
    "build": "gatsby build",
    "develop": "gatsby develop -H 0.0.0.0 -p 8000",
    "format": "prettier --write src/**/*.{js,jsx}",
    "start": "npm run develop",
    "serve": "gatsby serve",
    "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\"",
    "deploy": "gatsby build --prefix-paths && gh-pages -d public"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/gatsbyjs/gatsby-starter-default"
  },
  "bugs": {
    "url": "https://github.com/gatsbyjs/gatsby/issues"
  },
  "homepage": "https://billyjacoby.github.io/gatsby-react-bootstrap-starter/"
}

gatsby-node.js: N/A (empty)
gatsby-browser.js: N/A (empty)
gatsby-ssr.js: N/A (empty)

Thanks in advance.

[fullofcaffeine]

Anyone?

[Js-Brecht]

Do you have an example repository you could share? I wonder if it is maybe due to the processing that webpack is doing to your scss, and the way that it loads the style on the page. I'd have to see the actual data, though, in order to see what's happening.

If you look here, you'll see that gatsby-plugin-typography sorts itself to the top of the head component. Then here, gatsby-plugin-global-styles does the same thing. This would be why gatsby-plugin-global-styles needs to come after gatsby-plugin-typography in your gatsby-config. Theoretically, that should all work 🤷‍♂

[fullofcaffeine]

Hi Jeremy,

Thanks for replying.

Here's a small repro project I've just put together for this issue: https://github.com/fullofcaffeine/gatsby-global-scss-woes-issue-sample.

You can see that the plugin config snippet for the gatsby-plugin-global-styles does come after the one for gatsby-plugin-typography, here.

I've followed the instructions in the gatsby-plugin-global-styles's docs, here. You can find the configuration js here.

When running, the markup generated by the gatsby-plugin-global-styles is empty, and the scss styles are still below the ones from Typography.js. Perhaps I'm missing something?

Let me know if you have further questions.

Thanks!

[Js-Brecht]

Based on that information, it sounds like what I suspected. I think what is happening is that gatsby-plugin-global-styles is indeed importing the scss, which is, in effect, only making webpack aware of it, but webpack is then using sass-loader to process it into usable css. When it's done with that, it is probably packing it on to the end of the head component. What it sounds like is that this is what's causing the problem because, by that time, onPreRenderHTML has already run.

Can you dump the output from getHeadComponents()? If the bootstrap css is loaded in the <head> when you enter onPreRenderHTML, then we know the scss has already been processed, and you should be able to just find some identifying characteristics of that component, and use it to reorder the element instead.

Another thing I might try is to convert the scss to css, and see if createGlobalStyle is able to use it, instead of causing it to run through sass-loader. You can use node-sass to convert it. If this works, you could set up node-sass to run on your styles before it feeds them to createGlobalStyle; example here

I'm at work right now, so I don't have a great deal of time to spend on this. I'll load up your repo later today and see if I can get it to cooperate.

[Js-Brecht]

Another thing I just thought of is it's possible that the import globalStyle from './style.scss'; could cause webpack to process the styles, no matter how you feed them to createGlobalStyle. To get around that, I would use node-sass and the fs modules alone to read the styles in, and pass them to createGlobalStyle. That should make webpack ignore them.

As long as you aren't importing this GlobalStyleComponent module into any other runtime modules, I think it should be fine to do it that way. If you encounter problems with this (e.g. fs is not available in the browser), you could move that particular section out of your src directory, and let node be the only thing that is processing it, via your gatsby-ssr. Shouldn't really be necessary, because if it isn't imported into a runtime component, then that module should never run in the browser.

If all else fails, you might have to list the module as an external, so that webpack doesn't try including it into your final bundle.

[fullofcaffeine]

Thanks again for taking the time to look into it.

Another thing I just thought of is it's possible that the import globalStyle from './style.scss'; could cause webpack to process the styles, no matter how you feed them to createGlobalStyle. To get around that, I would use node-sass and the fs modules alone to read the styles in, and pass them to createGlobalStyle. That should make webpack ignore them.

I actually suspected that, and I think that's what's happening. But I thought that these plugins were designed to be inter-operable/be used together.

The fact that the docs for the global styles plugin doesn't mention anything about not working with the sass plugin made me conclude they were compatible, also because SASS is so popular and global styles is a very common approach that people coming from other static-site generators prefer to use.

If that's the case, should this be considered a bug in any of the plugins and or Gatsby?

I'll try the approach you suggested and post the results here.

As a related note, the headComponents API is fine I guess, but it seems to me that sometimes Webpack loaders can wreak havoc, because they inject stuff at the header and they are not even aware of headComponents. Are there any open discussions about this? To me it sounds like a design flaw of sorts.

[fullofcaffeine]

Is there a way to setup the sass-loader so that webpack returns its contents inline - using js - instead of injecting them in the HTML? So that:

import style from 'style.scss'

Would load the contents of style.scss into the style var?

I think this would be better than doing all the work of using node-sass manually, loading the compiled result using fs, etc. This is actually a lot of work for such a simple problem :/

[Js-Brecht]

I think it's more of a plugin incompatibility than it is a result of Gatsby's processing, or anything really pertaining to Webpack. From the way the documentation was written by the author of gatsby-plugin-global-styles, it appears as though they were expecting it to be used with some css-in-js type process instead of physical css/scss files. That's one reason I was thinking that converting it to css might help createGlobalStyle process the styles. You could try raising an issue in that repository and see if they can provide a method for handling this use case internally.

As a related note, the headComponents API is fine I guess, but it seems to me that sometimes Webpack loaders can wreak havoc, because they inject stuff at the header and they are not even aware of headComponents. Are there any open discussions about this? To me it sounds like a design flaw of sorts.

I did a quick run of your repo, and below is the first few elements of the header components that are passed to onPreRenderHTML.

JSON Output

[
   {
      "key": "GlobalStyle1709833222",
      "ref": null,
      "props": {
         "theme": {
            "typography": {
               "fontFamily": "Arial"
            }
         }
      },
      "_owner": null
   },
   {
      "key": "TypographyStyle",
      "ref": null,
      "props": {
         "typography": {
            /** list of styles */
         }
      },
      "_owner": null
   },
   {
      "type": "meta",
      "key": "4",
      "ref": null,
      "props": {
         "data-react-helmet": true,
         "name": "twitter:card",
         "content": "summary"
      },
      "_owner": null
   },
   {
      "type": "style",
      "key": null,
      "ref": null,
      "props": {
         "data-href": "/styles.943196fa3743f8c7b022.css",
         "dangerouslySetInnerHTML": {
            "__html": /** Looong list of bootstrap styles */
         }
      },
      "_owner": null
   },
]

So, you can see that the issue is not caused specifically by Webpack not being aware of Gatsby, and you can also see that Gatsby is plenty aware of Webpack to handle this kind of scenario. The entire issue occurs because the plugin in question doesn't know how to handle scss, and also that Webpack is picking up the scss and loading it into the header itself (which can be handled after the fact).

---

The easiest thing to do at this point, if you don't want to handle reading/processing the scss yourself, is this:

First thing, get rid of gatsby-plugin-global-styles. It's not doing you any good.
Second, include this line in your gatsby-browser.js:

// gatsby-browser.js
import "./src/styles/style.scss";

This will import your stylesheet for side effects onto every page. The same general thing that the plugin was doing. This method just doesn't make it a React component.

In gatsby-ssr, using the onPreRenderHTML endpoint, loop through the head components looking for an element that meets the following conditions:

1. type === "style"
2. /^.*Bootstrap/mi.test(props.dangerouslySetInnerHTML.__html)

That's the most future proof method. However, you could also use props['data-href'] === '/styles.943196fa3743f8c7b022.css'. The 943196fa3743f8c7b022 string is a hash of the style contents, so that won't change unless you change your styles. Not a stable method of doing it, though, since you might want to change some styles in the future.

Move that component up and you're done.

The header for the bootstrap stylesheet looks like this:

/*!\n * Bootstrap v4.3.1 (https://getbootstrap.com/)\n * Copyright 2011-2019 The Bootstrap Authors\n * Copyright 2011-2019 Twitter, Inc.\n * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)\n */

So long as you pick something to look for in that when matching your head components, you should be fine.

In the end, my configuration looked like this:

// gatsby-browser.js
import "./src/styles/style.scss";

// gatsby-ssr.js
export const onPreRenderHTML = ({ getHeadComponents, replaceHeadComponents }) => {
    const headComponents = getHeadComponents();
    for (const [idx, component] of headComponents.entries()) {
        if (component.type === "style" && /^.*Bootstrap/mi.test(component.props.dangerouslySetInnerHTML.__html)) {
            headComponents.splice(idx, 1);
            headComponents.unshift(component);
            break;
        }
    }
    replaceHeadComponents(headComponents);
};

---

Is there a way to setup the sass-loader so that webpack returns its contents inline - using js - instead of injecting them in the HTML?

That might be something available in a Webpack plugin, or maybe in a babel plugin. Possibly even a combination of the two. You'd have to do some research.

[Js-Brecht]

While that is the easiest method, it probably isn't the best method. You lose control over your style component, and have to rely on some arbitrary string matching in order to wrangle it again.

The ideal method, if you're dead set on using scss, would be to process it yourself, and load it how you want to into the head. I wouldn't even rely on a third party plugin to do it for me. I would use node-sass directly in gatsby-ssr to read and process the style file when it is sourced; say, above where onPreRenderHTML is defined; or, if you want to do it asynchronously, you could create a memoized function that will cache & return the value (that way, the styles are only being processed once, instead of every time you need them). Then, I would include that processed content directly into a <style> component's dangerouslySetInnerHTML.__html property, and unshift it into the headComponents 👍

[Js-Brecht]

Okay, I've got an even better method, where you can use this global styles plugin with scss flawlessly.

After further investigation, I realized it's not specifically an issue with the plugin not being able to process scss. It's that the scss globalStyles variable is empty... webpack just uses it for a reference point to insert styles wherever you use them.

So, you were on to something when you asked about a way to have webpack insert the data into a variable. I had completely forgotten about Webpack's inline loaders 🙄.

Make your GlobalStyleComponent.js look like this:

import { createGlobalStyle } from '@nfront/global-styles';
import globalStyle from '!css-loader!sass-loader!./style.scss';

const GlobalStyleComponent = createGlobalStyle`
  ${globalStyle[0][1]}
`;

export default GlobalStyleComponent;

And it works flawlessly.

The magic happens here: import globalStyle from '!css-loader!sass-loader!./style.scss';. That's informing Webpack to pass the file at the end through the loaders from right to left. sass-loader will compile scss to css, and css-loader will make it accessible via commonjs. The final ! tells Webpack to forego using the other loaders that are present in the config (which blocks it from being inserted into the dom). You could take it a step further by using a !!, which will disable all preloaders, loaders and postloaders. See this for details.

In a normal loader, you would then pass the data from css-loader into something like style-loader for insertion into the DOM; instead, we skip that part.
What this winds up doing is presenting an array of components like:

[
   [
      loader chain,
      data,
      ""
   ]
]

We only have one component, so we pick the first index, then we pick the second index to grab the data. That's what gets passed to createGlobalStyle, and voila!

[fullofcaffeine]

Oh wow, thanks a bunch for the elaborated responses!

So, you can see that the issue is not caused specifically by Webpack not being aware of Gatsby, and you can also see that Gatsby is plenty aware of Webpack to handle this kind of scenario

I don't get this part. How's Webpack aware of Gatsby and vice-versa? Is there any glue code for that? So you mean that this code:

   {
      "type": "style",
      "key": null,
      "ref": null,
      "props": {
         "data-href": "/styles.943196fa3743f8c7b022.css",
         "dangerouslySetInnerHTML": {
            "__html": /** Looong list of bootstrap styles */
         }
      },
      "_owner": null
   },

Is added by Webpack? In that case, why can't I just reorder it then using the onPreRenderHTML hook?

The easiest thing to do at this point, if you don't want to handle reading/processing the scss yourself, is this: (...)

Thanks for suggesting this, but I agree with you that's it's too error-prone. Might bite me back after a while.

The ideal method, if you're dead set on using scss, would be to process it yourself, and load it how you want to into the head. I wouldn't even rely on a third party plugin to do it for me. I would use node-sass directly in gatsby-ssr to read and process the style file when it is sourced; say, above where onPreRenderHTML is defined; or, if you want to do it asynchronously, you could create a memoized function that will cache & return the value (that way, the styles are only being processed once, instead of every time you need them). Then, I would include that processed content directly into a <style> component's dangerouslySetInnerHTML.__html property, and unshift it into the headComponents 👍

I actually started with this approach when I saw your last reply :) May I ask how you trigger node-sass? Do you use it programmatically or trigger the CLI tool?

Okay, I've got an even better method, where you can use this global styles plugin with scss flawlessly.

Thanks! I didn't have a chance to try this one out yet, but I'll do soon. Seems like the best way to go, indeed.

---

On a related note:

I must say though, I'm really surprised such a simple thing - deciding the loading order of assets - can be so complex in Gatsby. I think the Webpack solution you showed above is fine, but it's far from obvious and it requires the use of another plugin. It'd be really nice if Gatsby provided a way to fallback and allow users to manually and easily change the order of assets. At first, I thought that by copying the default-html.js to src/html.js would allow me to do that, but no, had no luck (it seems it was possible before though, see: #1994 (comment).

Just a small rant in hope that the core team might discuss and improve that part of Gatsby ;) Other than that, I'm enjoying it.

[Js-Brecht]

May I ask how you trigger node-sass? Do you use it programmatically or trigger the CLI tool?

node-sass is used by sass-loader. I never actually built out the way to do the processing manually; I skipped straight to number three and had Webpack do it for me 😆

I don't get this part. How's Webpack aware of Gatsby and vice-versa? Is there any glue code for that? So you mean that this code:

It's true that Webpack is not aware of Gatsby, but what I meant here is that that was not the problem. Gatsby is aware of Webpack (but that wasn't the issue, either) because the framework that is used to call the API endpoints in gatsby-ssr, for example, is the main entry point provided to Webpack. During the load, Gatsby uses Webpack itself to keep track of generated scripts, styles, and the like.

Check out the static-entry source. It is what Gatsby feeds Webpack to start the generating process, so when it gets sourced, it is essentially running all of that code, and hitting those endpoints from within Webpack's runtime, and using Webpack's own stats and chunks files to keep track of where everything is landing.

In that case, why can't I just reorder it then using the onPreRenderHTML hook?

You certainly can. You just have to go through the process to find the chunk that was added to the head. That's basically what I was doing in the "easy" method, even though it turned out to not be the easiest 😆

I must say though, I'm really surprised such a simple thing - deciding the loading order of assets - can be so complex in Gatsby.

Considering the fact that Gatsby is pluggable, and any of those plugins are capable of hooking into the Gatsby lifecycle, and updating various <head> and <body> components, it would be rather difficult to have a "manual ordering" type process for the user. Because of its dynamic nature, how would you define a manual sort order? You would need to have something, like another plugin, do the reordering for you, based off of certain parameters; then the user is still stuck with trying to figure out what to use to reorder their <head>.

At first, I thought that by copying the default-html.js to src/html.js would allow me to do that, but no, had no luck (it seems it was possible before though, see: #1994 (comment).

I could see maybe being able to tell it general groups of what to load... like "load plugin styles first", and "load generated static styles second", then "load css-in-js styles", etc. But then, you'd still have plugins that interact with other things the wrong way, so an overarching distribution like that wouldn't work for everything, therefore, you'd still need that little loophole that lets people put things where they want for their plugin... which means you have to let the end-user do the same thing... and we're back at square one.

It's not so complex when you have a simple (non-gatsby) site building with webpack, because resources get loaded in the order they are encountered, and there is far less interactions/hooks. In that case, it certainly is easier. But, the complexity of anything that has any depth will always grow as it becomes more and more robust. It's my opinion that the Gatsby team has done a fantastic job of making it as easy as possible for consumers to use the tool.

---

Please do let me know if we've solved your issue when you've had a chance to do some testing.

[fullofcaffeine]

Please do let me know if we've solved your issue when you've had a chance to do some testing.

Yes, it works!

Thanks a lot for guiding me through it. Your replies were all detailed and helpful. It's been some time since I got such quality responses from an open-source community. I really appreciated that!

It's not so complex when you have a simple (non-gatsby) site building with webpack, because resources get loaded in the order they are encountered, and there is far less interactions/hooks. In that case, it certainly is easier. But, the complexity of anything that has any depth will always grow as it becomes more and more robust. It's my opinion that the Gatsby team has done a fantastic job of making it as easy as possible for consumers to use the tool.

Yeah, looks like this was an unfortunate consequence of the abstractions Gatsby provides out-of-the-box. It's dead simple and works for 80% of the time, but can be very confusing and problematic for the other 20%, specially when it comes to plugins that can or may interact (or when users expect them to interact).

Anyway, at least people with similar issues will probably hit up on this issue, and there are several approaches to try here ;)

Cheers!

[fullofcaffeine]

I ended up abandoning this approach.

The main problem is that it's harder to configure postcss as part of the inline configuration and honestly, I was tired of so much work for so little gain. The culprit here is the Typography.js and its ìnjectStyles` method. I wish it provided a way to more easily integrate it into more traditional css pre-processing pipelines, like SASS.

The solution I found was to effectively use typography.js as a pre-generator. I choose the theme, let it generate the link to the fonts + the styles in the head, then I copy the markup and add it to my sass pipeline. I can then just easily re-order the typography rules and put them exactly where I want them, and they will be processed by the postcss rules as well. Problem solved.

I don't find much value in tweaking the typography.js settings using its js API, the main value I get from it are the themes that help me to quickly bootstrap with pretty typeface styles.

[Js-Brecht]

Ah, yeah, I can see that being a pain.

Just a couple more ideas:

• You could probably automate that process during the build. You can use typography.toString() to generate the css as a string (works in node), and then just dump that to a very specific .scss or .css file which can be imported at any point in your scss chain.

  • You could then use react-typography in your onPreRenderHTML to create your font links

  • Caveat: It would run on every build, unless you designed a method to only run it when things change. Maybe a problem, but maybe not a big deal, either.

• There is also the postcss plugin, postcss-typography. IIRC, Webpack (through Gatsby) will pick up the postcss configurations file in your project root, so maybe that can be used to integrate typography into your postcss processing without having to worry about writing files anywhere.

  • Not sure at what point this would inject the styles into yours, but it might be worth experimenting with at some point.

With both of these, there would be no need for gatsby-plugin-typography, but it's entirely possible that they're more work than they're worth, too. Especially if your typography styles don't change much.

[vincentreynaud]

Hi!

I have the same issue with using Bootstrap. I'm struggling to put together the right setup based on your explanations. I think using typography.js as a pre-generator sounds like the best choice here, but I am also trying to find a process that would be automated as opposed to copy-pasting the generated css.

@fullofcaffeine do you have an updated version of your example repo with the pipeline you ended up using? and maybe including the suggestions @Js-Brecht made in their last comment?

Cheers!