babel-plugin-transform-postcss

0.3.0 verified Sat Apr 25 auth: no javascript maintenance

A Babel plugin that transforms CSS imports by processing them through PostCSS, enabling CSS Modules to generate JavaScript objects mapping class names to hashed strings. At version 0.3.0, it supports both synchronous and asynchronous PostCSS plugins and uses postcss-load-config for configuration. Unlike alternatives like css-modules-transform or css-modules-require-hook, it works with any PostCSS plugin and integrates with babelify for Browserify. It does not include CSS in the output; separate CSS extraction is required. Active development appears stalled, with no major releases since 2018, and it depends on PostCSS v6.

Common errors

error Error: Cannot find module 'postcss-load-config' ↓

cause Missing required dependency for reading postcss.config.js.

fix

Run: npm install --save-dev postcss-load-config

error Error: PostCSS plugin postcss-modules requires PostCSS 8. Update your PostCSS. ↓

cause Plugin 'postcss-modules' requires PostCSS 8, but babel-plugin-transform-postcss pins PostCSS 6.

fix

Use an older version of postcss-modules that supports PostCSS 6 (e.g., v1.1.0), or switch to a different Babel plugin.

error Module not found: Can't resolve './styles.css' ↓

cause Webpack or bundler cannot handle CSS imports; this plugin only transforms the import syntax but does not bundle CSS.

fix

Add a CSS loader to your bundler (e.g., css-loader for Webpack) to handle .css files, or ensure the transform runs before bundling.

Warnings

gotcha CSS files are not included in the JavaScript bundle. You must separately process your CSS using the same PostCSS config (e.g., with postcss-cli) to generate actual CSS output. ↓

fix Ensure a separate build step for CSS (e.g., postcss-cli) is in place alongside this Babel plugin.

gotcha Cache is stored in /tmp/bptp-UNIQUE_ID and is only invalidated when CSS file content changes, not when postcss.config.js changes. This can lead to stale output if config changes. ↓

fix Manually delete the cache directory (/tmp/bptp-*) when changing PostCSS configuration.

deprecated Dependency on PostCSS v6, which is outdated. Current PostCSS is v8. The plugin may need updates for compatibility. ↓

fix Use a more actively maintained plugin like 'devsnek/babel-plugin-transform-css-modules' or consider upgrading PostCSS manually (requires fork).

gotcha The plugin requires 'postcss-load-config' to be installed, but it's not listed as a dependency. Ensure it's in your project. ↓

fix Install postcss-load-config: npm install --save-dev postcss-load-config

Install

npm install babel-plugin-transform-postcss

yarn add babel-plugin-transform-postcss

pnpm add babel-plugin-transform-postcss

Imports

default (plugin)
wrong
```
const postcssTransform = require('babel-plugin-transform-postcss')
```
correct
```
import postcssTransform from 'babel-plugin-transform-postcss'
```
This is a Babel plugin, not typically imported directly; it's used in .babelrc or babel.config.js as a string.

Quickstart

Babel configuration with the plugin and a postcss.config.js using postcss-modules to extract CSS module class names into JS object.

// .babelrc
{
  "presets": [
    ["env", { "targets": { "node": "current" } }]
  ],
  "plugins": [
    "transform-postcss",
    ["transform-postcss", {
      "config": "postcss.config.js"
    }]
  ]
}

// postcss.config.js
module.exports = (ctx) => ({
  plugins: [
    require('postcss-modules')({
      getJSON: ctx.extractModules || (() => {}),
    }),
  ],
});

// source.js
import styles from './styles.css';
console.log(styles.example);