Styled Components Babel Plugin

2.1.4 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: Property 'expressions' of object #<Object> is not an array
```
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.

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.
```
Error: styled-components: Expected a string or function, got [object Object]
```
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.

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.
```
ReferenceError: require is not defined (in browser environment)
```
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.

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.

Warnings

breaking 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.
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`).
gotcha 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.
Fix: Avoid using version 2.0.5. Upgrade to 2.0.6 or a later version to prevent build performance issues.
gotcha 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`.
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.
gotcha The plugin is dependent on a specific version range of `styled-components`. Mismatched versions can lead to unexpected behavior or compilation errors.
Fix: Always check the `peerDependencies` of `babel-plugin-styled-components` (currently `styled-components: >=2`) and ensure your `styled-components` installation falls within this range.

Install

npm install babel-plugin-styled-components npm
yarn add babel-plugin-styled-components yarn
pnpm add babel-plugin-styled-components pnpm

Imports

babel-plugin-styled-components
wrong:
```
import styledComponentsPlugin from 'babel-plugin-styled-components';
```
correct:
```
// .babelrc or babel.config.js
{
  "plugins": ["babel-plugin-styled-components"]
}
```
Babel plugins are configured in Babel configuration files (e.g., .babelrc, babel.config.js), not directly imported into application code.
Configuring with options
```
// .babelrc or babel.config.js
{
  "plugins": [
    ["babel-plugin-styled-components", {
      "ssr": true,
      "displayName": true,
      "fileName": false,
      "pure": true
    }]
  ]
}
```
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`.
Using with `styled-components` Babel Macro
```
// .babelrc or babel.config.js
{
  "plugins": [
    "babel-plugin-styled-components",
    "macros"
  ]
}
```
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.

Quickstart

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.

npm install --save-dev babel-plugin-styled-components styled-components

// .babelrc or babel.config.js
// Make sure you have babel-loader configured in your webpack or similar build setup
// For a basic setup, your babel config might look like this:
{
  "presets": [
    ["@babel/preset-env", {"targets": {"node": "current"}}],
    "@babel/preset-react",
    "@babel/preset-typescript"
  ],
  "plugins": [
    ["babel-plugin-styled-components", {
      "ssr": true, // Enable SSR support for consistent classNames
      "displayName": true // Adds component names to classNames for easier debugging
    }]
  ]
}

view raw JSON →