# Next.js

Next.js is a React framework for production grade applications that scale. The world's leading companies use Next.js to build server-rendered applications, static websites, and more.

You can use PurgeCSS with Next.js by using the postCSS plugin in the Next.js configuration

# Customize PostCSS configuration (Next.js >= 9.3)

To customize the PostCSS configuration, create a postcss.config.js file in the root of your project.

Warning: When you define a custom PostCSS configuration file, Next.js completely disables the default behavior. Be sure to manually configure all the features you need compiled, including Autoprefixer (opens new window). You also need to install any plugins included in your custom configuration manually, i.e. npm install postcss-flexbugs-fixes postcss-preset-env.

By default, the outer document containing html and body is inside nextjs node module. Add safelist:["html", "body"] to make sure PurgeCSS does not remove those style.

Add PurgeCSS to the default configuration:

module.exports = {
  "plugins": [
    "postcss-flexbugs-fixes",
    [
      "postcss-preset-env",
      {
        "autoprefixer": {
          "flexbox": "no-2009"
        },
        "stage": 3,
        "features": {
          "custom-properties": false
        }
      }
    ],
    [
      '@fullhuman/postcss-purgecss',
      {
        content: [
            './pages/**/*.{js,jsx,ts,tsx}',
            './components/**/*.{js,jsx,ts,tsx}'
        ],
        defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || [],
        safelist: ["html", "body"]
      }
    ],
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Next.js plugin (Next.js < 9.3)

# Intallation

next-purgecss requires one of the following css next plugins :

Just pick the one that fits your needs. In the following steps, I will use next-css but it works the same for the other css next plugins.

For example, install next-css and next-purgecss :

yarn add @zeit/next-css next-purgecss --dev

or with npm :

npm install @zeit/next-css next-purgecss --save-dev

Once you installed the packages, you need to edit next.config.js.

// next.config.js
const withCss = require("@zeit/next-css");
const withPurgeCss = require("next-purgecss");

module.exports = withCss(withPurgeCss());

1
2
3
4
5

# Options

# `purgeCssEnabled`

By default, next-purgecss will always remove unused CSS, regardless of build environment. You can change that by defining a function for the purgeCssEnabled option. The purgeCssEnabled function receives two arguments:

Argument	Type	Description
`dev`	`Boolean`	`true` in development mode (running `next`) or `false` in production mode (running `next start`)
`isServer`	`Boolean`	`true` during server side compilation or `false` during client side compilation

// next.config.js
module.exports = withCss(
  withPurgeCss({
    purgeCssEnabled: ({ dev, isServer }) => !dev && !isServer, // Only enable PurgeCSS for client-side production builds
  })
);

1
2
3
4
5
6

# `purgeCssPaths`

By default, this plugin will scan components and pages directories for classnames. You can change that by defining purgeCssPaths.

// next.config.js
module.exports = withCss(
  withPurgeCss({
    purgeCssPaths: [
      "pages/**/*",
      "components/**/*",
      "other-components/**/*", // also scan other-components folder
    ],
  })
);

1
2
3
4
5
6
7
8
9
10

# `purgeCss`

You can pass custom options to PurgeCSS (opens new window) by defining purgeCss object in your next.config.js.

// next.config.js
module.exports = withCss(
  withPurgeCss({
    purgeCss: {
      whitelist: () => ["my-custom-class"],
    },
  })
);

1
2
3
4
5
6
7
8

The list of available options are documented in purgecss-webpack-plugin docs (opens new window).

WARNING

purgeCss.paths will overwrite purgeCssPaths

← React Nuxt.js →