Accueil > Blog > How to Re-activate CSS Code Splitting in Gatsby

How to Re-activate CSS Code Splitting in Gatsby



Gatsby, a popular static site generator built on React, has a default configuration that bundles all the CSS (Cascading Style Sheets) into one file. Although this configuration might work for small-scale projects, it could lead to performance issues on larger websites. In such cases, re-activating CSS code splitting can lighten the load on initial page load, thus significantly improving the performance of your Gatsby site.

This article will take you through the process of re-activating CSS code splitting in Gatsby to help you optimize your site's performance.

What is CSS Code Splitting?

CSS code splitting is a technique that divides a single large CSS file into smaller chunks. These smaller chunks of CSS are then loaded only when required, resulting in a faster initial page load. By splitting your CSS code, you can ensure that only the necessary CSS is loaded for any given page, reducing the amount of data that needs to be downloaded.

Why Gatsby Deactivates CSS Code Splitting by Default?

Gatsby deactivates CSS code splitting by default for simplicity and to ensure a seamless developer experience. This decision reduces the complexity of managing multiple CSS files, making it easier for developers to build and maintain their websites. However, this configuration may not be the best choice for all projects, especially those with a large number of styles or pages.

For large projects, bundling all the CSS into a single file can lead to a significant increase in the size of the initial page load, as the browser needs to download and parse the entire CSS file before rendering the page. This can result in slower page load times, which can negatively impact user experience and search engine rankings.

Re-activating CSS Code Splitting in Gatsby

To re-activate CSS code splitting in Gatsby, you need to make use of a plugin called gatsby-plugin-css-modules. This plugin allows you to use CSS Modules with your Gatsby project, which enables you to split your CSS code into smaller, more manageable pieces that can be loaded on-demand.

Follow these steps to re-activate CSS code splitting in your Gatsby project:

1. Install gatsby-plugin-css-modules:

First, you need to install the gatsby-plugin-css-modules plugin. To do this, open your terminal and navigate to your Gatsby project's root directory. Then, run the following command:

npm install --save gatsby-plugin-css-modules
Enter fullscreen mode Exit fullscreen mode

This command installs the plugin and adds it to your package.json file.

2. Configure gatsby-config.js:

Next, open your gatsby-config.js file, which is located in the root directory of your Gatsby project. You need to add the gatsby-plugin-css-modules plugin to the plugins array. Add the following code to your gatsby-config.js file:

module.exports = {
  // ...
  plugins: [
    // ...
      resolve: `gatsby-plugin-css-modules`,
      options: {
        // Configure the plugin options, if required
  // ...
Enter fullscreen mode Exit fullscreen mode

3. Start using CSS Modules:

Now that you've installed and configured the plugin, you can start using CSS Modules in your Gatsby project. To do this, rename your CSS files to have the .module.css extension (e.g., styles.module.css). This ensures that your CSS files are treated as CSS Modules.

In your React components, import the CSS Modules as follows:

import React from "react";
import styles from "./styles.module.css";

const MyComponent = () => (
  <div className={styles.container}>
    <h1 className={styles.heading}>Hello, World!</h1>

export default MyComponent;
Enter fullscreen mode Exit fullscreen mode

In the example above, the styles object contains the generated class names for your CSS classes, which you can use in your JSX markup.


By re-activating CSS code splitting in your Gatsby project, you can improve the performance of your site and ensure a faster initial page load. By dividing your CSS code into smaller chunks and loading them on-demand, you can optimize the user experience for your visitors.

Using the gatsby-plugin-css-modules plugin, you can easily implement CSS code splitting in your Gatsby project and start enjoying the benefits of this optimization technique.