{"id":19206,"library":"babel-plugin-transform-postcss","title":"babel-plugin-transform-postcss","description":"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.","status":"maintenance","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/wbyoung/babel-plugin-transform-postcss","tags":["javascript","postcss","postcss-modules","babel","babel-transform","css-modules"],"install":[{"cmd":"npm install babel-plugin-transform-postcss","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-transform-postcss","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-transform-postcss","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required to process CSS","package":"postcss","optional":false}],"imports":[{"note":"This is a Babel plugin, not typically imported directly; it's used in .babelrc or babel.config.js as a string.","wrong":"const postcssTransform = require('babel-plugin-transform-postcss')","symbol":"default (plugin)","correct":"import postcssTransform from 'babel-plugin-transform-postcss'"}],"quickstart":{"code":"// .babelrc\n{\n  \"presets\": [\n    [\"env\", { \"targets\": { \"node\": \"current\" } }]\n  ],\n  \"plugins\": [\n    \"transform-postcss\",\n    [\"transform-postcss\", {\n      \"config\": \"postcss.config.js\"\n    }]\n  ]\n}\n\n// postcss.config.js\nmodule.exports = (ctx) => ({\n  plugins: [\n    require('postcss-modules')({\n      getJSON: ctx.extractModules || (() => {}),\n    }),\n  ],\n});\n\n// source.js\nimport styles from './styles.css';\nconsole.log(styles.example);","lang":"typescript","description":"Babel configuration with the plugin and a postcss.config.js using postcss-modules to extract CSS module class names into JS object."},"warnings":[{"fix":"Ensure a separate build step for CSS (e.g., postcss-cli) is in place alongside this Babel plugin.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Manually delete the cache directory (/tmp/bptp-*) when changing PostCSS configuration.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use a more actively maintained plugin like 'devsnek/babel-plugin-transform-css-modules' or consider upgrading PostCSS manually (requires fork).","message":"Dependency on PostCSS v6, which is outdated. Current PostCSS is v8. The plugin may need updates for compatibility.","severity":"deprecated","affected_versions":">=0.1.0, <0.4.0"},{"fix":"Install postcss-load-config: npm install --save-dev postcss-load-config","message":"The plugin requires 'postcss-load-config' to be installed, but it's not listed as a dependency. Ensure it's in your project.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run: npm install --save-dev postcss-load-config","cause":"Missing required dependency for reading postcss.config.js.","error":"Error: Cannot find module 'postcss-load-config'"},{"fix":"Use an older version of postcss-modules that supports PostCSS 6 (e.g., v1.1.0), or switch to a different Babel plugin.","cause":"Plugin 'postcss-modules' requires PostCSS 8, but babel-plugin-transform-postcss pins PostCSS 6.","error":"Error: PostCSS plugin postcss-modules requires PostCSS 8. Update your PostCSS."},{"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.","cause":"Webpack or bundler cannot handle CSS imports; this plugin only transforms the import syntax but does not bundle CSS.","error":"Module not found: Can't resolve './styles.css'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}