esbuild-plugin-styled-components

3.0.1 verified Mon Apr 27 auth: no javascript

An esbuild plugin that transforms styled-components during bundling, supporting SSR, minification, display name generation, and file name tracking. Version 3.0.1 is the latest stable release, actively maintained on GitHub. It wraps the styled-components babel plugin for esbuild, offering options like ssr, displayName, fileName, minify, transpileTemplateLiterals, and pure. Differentiators include native esbuild integration for faster builds compared to Babel-only workflows, and seamless TypeScript support with type definitions.

Common errors

error Cannot find module 'esbuild-plugin-styled-components' ↓

cause Package not installed or incorrect import path.

fix

Run 'npm install -D esbuild-plugin-styled-components' and ensure import path is correct.

error styledComponentsPlugin is not a function ↓

cause Named import used instead of default import.

fix

Use default import: import styledComponentsPlugin from 'esbuild-plugin-styled-components'.

error Error: The 'pure' option is deprecated. ↓

cause Using the deprecated 'pure' option.

fix

Remove the 'pure' option from your plugin configuration.

error TypeError: Cannot read properties of undefined (reading 'default') ↓

cause CommonJS require() returns an object with default property when using ESM-only package.

fix

Use dynamic import: const plugin = (await import('esbuild-plugin-styled-components')).default;

error Error: Component selectors can't end with space when using fileName: true? ↓

cause Styled-components file name tracking may cause selector issues in rare cases.

fix

Disable fileName: true or use a custom namespace to avoid conflicts.

Warnings

breaking v3.0.0 changed from CommonJS to ESM-only. require() will fail in older Node versions. ↓

fix Use import syntax or upgrade to Node >=12.22, >=14.17, or >=16.0. For CommonJS, use dynamic import: const plugin = (await import('esbuild-plugin-styled-components')).default;

deprecated The 'pure' option is deprecated and may be removed in a future version. ↓

fix Avoid using 'pure' option; it is no longer recommended.

gotcha The plugin does not work with 'sass' or 'less' CSS preprocessing unless the styled-components syntax is already valid CSS. ↓

fix Ensure styled-components template literals are valid CSS after preprocessing; use separate build steps if needed.

gotcha If the 'filter' option is not set, the plugin processes all files, which may slow down builds. ↓

fix Set the filter option to '\.[tj]sx?$' to only process JavaScript/TypeScript files.

deprecated The 'meaninglessFileNames' option is deprecated; use 'filename' or custom logic instead. ↓

fix Remove the option from your plugin configuration.

Install

npm install esbuild-plugin-styled-components

yarn add esbuild-plugin-styled-components

pnpm add esbuild-plugin-styled-components

Imports

default

wrong

import { styledComponentsPlugin } from 'esbuild-plugin-styled-components'

correct

import styledComponentsPlugin from 'esbuild-plugin-styled-components'

The module exports a single default export, not a named export.

default (CommonJS)

wrong

const { styledComponentsPlugin } = require('esbuild-plugin-styled-components')

correct

const styledComponentsPlugin = require('esbuild-plugin-styled-components')

CommonJS require returns the plugin function as the default export.

PluginOptions (TypeScript)

wrong

import { PluginOptions } from 'esbuild-plugin-styled-components'

correct

import type { PluginOptions } from 'esbuild-plugin-styled-components'

PluginOptions is exported as a type; use type import for proper tree-shaking in TypeScript.

Quickstart

Bundles a TypeScript entry point with esbuild and styled-components transformation for SSR, display names, file names, and minification.

import esbuild from 'esbuild';
import styledComponentsPlugin from 'esbuild-plugin-styled-components';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    styledComponentsPlugin({
      ssr: true,
      displayName: true,
      fileName: true,
      minify: true,
    }),
  ],
});