# gatsby-plugin-postcss

> Gatsby plugin to handle PostCSS

Latest version **6.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-plugin-postcss
pnpm add gatsby-plugin-postcss
yarn add gatsby-plugin-postcss
bun add gatsby-plugin-postcss
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: no vulnerabilities; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 6.16.0 |
| Published | 2026-01-26 |
| First published | 2018-06-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 <26 |
| Dependencies | 2 |
| Unpacked size | 43.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55938 |
| Author | Marat Dreizin |
| Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, fk, tylerbarnes, daniellewgatsby |
| Keywords | gatsby, gatsby-plugin, postcss |

## Links

- npm: https://www.npmjs.com/package/gatsby-plugin-postcss
- Repository: https://github.com/gatsbyjs/gatsby
- Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-postcss#readme
- Issues: https://github.com/gatsbyjs/gatsby/issues
- npm.io page: https://npm.io/package/gatsby-plugin-postcss

## Dependencies (2)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13
- [postcss-loader](https://npm.io/package/postcss-loader.md) ^7.3.4

## Recent versions

- 6.16.0 (latest) — 2026-01-26
- 6.17.0-next.0 (next) — 2025-11-27
- 6.17.0-react19.1 (react19) — 2025-11-26
- 4.15.0 (latest-v3) — 2022-12-07
- 5.25.0 (latest-v4) — 2022-12-07
- 6.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22
- 5.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12
- 6.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12
- 5.23.0-alpha-a5-peer.70 (alpha-a5-peer) — 2022-09-14
- 5.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08
- 5.23.0-alpha-9689ff.25 (alpha-9689ff) — 2022-08-31
- 5.18.0-alpha-drupal-self-reference.18 (drupal-self-reference) — 2022-07-19
- 5.15.0-alpha-wp-image-cdn-auth.48 (wp-image-cdn-auth) — 2022-05-20
- 5.8.0-alpha-image-service.24 (image-service) — 2022-02-10
- 5.6.0-alpha-ts-jit.60 (alpha-ts-jit) — 2022-01-21
- … 258 more at https://npm.io/package/gatsby-plugin-postcss/versions

## README

# gatsby-plugin-postcss

Provides drop-in support for PostCSS

## Install

`npm install postcss gatsby-plugin-postcss`

## How to use

1.  Include the plugin in your `gatsby-config.js` file.
2.  Write your stylesheets using PostCSS (`.css` files) and require or import them as normal.

```javascript:title=gatsby-config.js
plugins: [`gatsby-plugin-postcss`]
```

If you need to pass options to PostCSS use the plugins options; see [`postcss-loader`](https://github.com/postcss/postcss-loader) for all available options.

If you need to override the default options passed into [`css-loader`](https://github.com/webpack-contrib/css-loader).
**Note:** Gatsby is using `css-loader@^5.0.0`.

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-postcss`,
    options: {
      cssLoaderOptions: {
        camelCase: false,
      },
    },
  },
]
```

### With CSS Modules

Using CSS modules requires no additional configuration. Simply prepend `.module` to the extension. For example: `app.css` -> `app.module.css`.
Any file with the `module` extension will use CSS modules. CSS modules are imported as ES Modules to support treeshaking. You'll need to import styles as: `import { yourClassName, anotherClassName } from './app.module.css'`

### PostCSS plugins

If you would prefer to add additional postprocessing to your PostCSS output you can specify plugins in the plugin options:

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-postcss`,
    options: {
      postCssPlugins: [require(`postcss-preset-env`)({ stage: 0 })],
    },
  },
],
```

Alternatively, you can use `postcss.config.js` to specify your particular PostCSS configuration:

```javascript:title=postcss.config.js
const postcssPresetEnv = require(`postcss-preset-env`)

module.exports = () => ({
  plugins: [
    postcssPresetEnv({
      stage: 0,
    }),
  ],
})
```

If you need to override the default options passed into [`css-loader`](https://github.com/webpack-contrib/css-loader).

In this example `css-loader` is configured to output classnames as is, instead of converting them to camel case. Named exports must be disabled for this to work, and so you have to import CSS using `import styles from './file.css` instead of `import * as styles from './file.module.css'`

```javascript:title=gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-postcss`,
    options: {
      cssLoaderOptions: {
        exportLocalsConvention: false,
        namedExport: false,
      },
    },
  },
]
```

---
_Source: https://npm.io/package/gatsby-plugin-postcss · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._