Registry / babel-plugin-styled-components

babel-plugin-styled-components

library2.1.4jsnpmunverified

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.

npm install babel-plugin-styled-components

package ↗homepage ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-STYLE

babel-plugin-styled-components

javascriptv2.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

babel-plugin-styled-components

✓ // .babelrc or babel.config.js { "plugins": ["babel-plugin-styled-components"] }

✗ import styledComponentsPlugin from '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.

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 }] ] }

Debug

Known issues

breakingMajor 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`).

affects: >=2.0.0

gotchaVersion 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.

affects: 2.0.5

gotchaIncorrect 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Property 'expressions' of object #<Object> is not an array

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]

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)

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.

Upgrade

Version history

2.1.4latest on npm

Audit

Dependencies

styled-componentsrequiredThis is a Babel plugin for `styled-components`, requiring the library itself for proper functionality.

Agent activity

7 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/babel-plugin-styled-components ↗

homepagehttps://styled-components.com ↗