{"id":10544,"library":"babel-plugin-styled-components","title":"Styled Components Babel Plugin","description":"The `babel-plugin-styled-components` package enhances the developer experience when working with `styled-components`. It provides critical features such as consistent hashing of component class names, which is essential for reliable server-side rendering (SSR), as well as automatic annotation of styled components for improved debugging. The plugin also offers various minification strategies for the generated CSS and the tagged template literals. The current stable version is 2.1.4, with releases occurring as needed for bug fixes, dependency updates, and minor feature enhancements, as seen in the frequent patch and minor updates in its recent history. Its primary differentiators are its tight integration with `styled-components` for SSR, advanced debugging capabilities (e.g., `displayName`), and performance optimizations through minification, making it a highly recommended companion for any `styled-components` project.","status":"active","version":"2.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/styled-components/babel-plugin-styled-components","tags":["javascript","styled-components","css-in-js","babel-plugin","server-side rendering","ssr","displayName"],"install":[{"cmd":"npm install babel-plugin-styled-components","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-styled-components","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-styled-components","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Babel plugin for `styled-components`, requiring the library itself for proper functionality.","package":"styled-components","optional":false}],"imports":[{"note":"Babel plugins are configured in Babel configuration files (e.g., .babelrc, babel.config.js), not directly imported into application code.","wrong":"import styledComponentsPlugin from 'babel-plugin-styled-components';","symbol":"babel-plugin-styled-components","correct":"// .babelrc or babel.config.js\n{\n  \"plugins\": [\"babel-plugin-styled-components\"]\n}"},{"note":"Options are passed as an array where the second element is an object containing the plugin configuration. Consult the styled-components documentation for available options like `ssr`, `displayName`, `fileName`, and `pure`.","symbol":"Configuring with options","correct":"// .babelrc or babel.config.js\n{\n  \"plugins\": [\n    [\"babel-plugin-styled-components\", {\n      \"ssr\": true,\n      \"displayName\": true,\n      \"fileName\": false,\n      \"pure\": true\n    }]\n  ]\n}"},{"note":"When using `styled-components/macro`, ensure the `babel-plugin-styled-components` is listed before `macros` plugin, or ensure it is correctly applied for macro processed files.","symbol":"Using with `styled-components` Babel Macro","correct":"// .babelrc or babel.config.js\n{\n  \"plugins\": [\n    \"babel-plugin-styled-components\",\n    \"macros\"\n  ]\n}"}],"quickstart":{"code":"npm install --save-dev babel-plugin-styled-components styled-components\n\n// .babelrc or babel.config.js\n// Make sure you have babel-loader configured in your webpack or similar build setup\n// For a basic setup, your babel config might look like this:\n{\n  \"presets\": [\n    [\"@babel/preset-env\", {\"targets\": {\"node\": \"current\"}}],\n    \"@babel/preset-react\",\n    \"@babel/preset-typescript\"\n  ],\n  \"plugins\": [\n    [\"babel-plugin-styled-components\", {\n      \"ssr\": true, // Enable SSR support for consistent classNames\n      \"displayName\": true // Adds component names to classNames for easier debugging\n    }]\n  ]\n}","lang":"typescript","description":"Demonstrates how to install the plugin and configure it in a Babel configuration file (e.g., `.babelrc` or `babel.config.js`) for both client-side and server-side rendering."},"warnings":[{"fix":"Review the `styled-components` and `babel-plugin-styled-components` changelogs for specific compatibility notes. Ensure your `styled-components` peer dependency is satisfied (currently `>=2`).","message":"Major version 2.0.0 introduced significant changes, including better compatibility with `styled-components` v4 and v5, and potential changes in internal handling of styles. Always ensure your `styled-components` version is compatible.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Avoid using version 2.0.5. Upgrade to 2.0.6 or a later version to prevent build performance issues.","message":"Version 2.0.5 introduced a change related to babel macros that led to a major build performance regression. This was quickly reverted in version 2.0.6.","severity":"gotcha","affected_versions":"2.0.5"},{"fix":"Ensure `babel-plugin-styled-components` is placed correctly in your Babel plugin array, typically before other plugins that might modify styled-component specific syntax. If using `babel-plugin-macros`, the styled-components plugin should generally come before it or be configured appropriately for macro use.","message":"Incorrect plugin order can cause issues, especially when using other Babel plugins that transform code before `babel-plugin-styled-components` or with `styled-components/macro`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always check the `peerDependencies` of `babel-plugin-styled-components` (currently `styled-components: >=2`) and ensure your `styled-components` installation falls within this range.","message":"The plugin is dependent on a specific version range of `styled-components`. Mismatched versions can lead to unexpected behavior or compilation errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update `babel-plugin-styled-components` to the latest version. Verify your `styled-components` code follows correct syntax. Check your Babel presets and other plugins for conflicts.","cause":"This often occurs when the Babel plugin processes an unsupported or malformed styled-components syntax, or if a breaking change in a newer Babel version conflicts with an older plugin version.","error":"TypeError: Property 'expressions' of object #<Object> is not an array"},{"fix":"Ensure `babel-plugin-styled-components` is correctly installed and configured in your Babel setup. Verify that the plugin is running before other transforms that might interfere with styled-components' template literals.","cause":"This error, while often originating from `styled-components` itself, can be exacerbated by the Babel plugin failing to correctly transform tagged template literals, leading to invalid input for `styled-components` at runtime.","error":"Error: styled-components: Expected a string or function, got [object Object]"},{"fix":"Ensure your build process correctly transpiles and bundles your code for the target environment. If targeting a browser, make sure `ssr: true` in the plugin options is handled correctly by your bundler or conditionally applied for server-side bundles only.","cause":"While a Babel plugin doesn't directly run in the browser, configuration mistakes or a lack of proper bundling/transpilation for CommonJS modules in a browser context can surface errors related to server-side rendering logic included by the plugin if not correctly configured or tree-shaken.","error":"ReferenceError: require is not defined (in browser environment)"}],"ecosystem":"npm"}