{"id":12249,"library":"typescript-plugin-styled-components","title":"TypeScript Plugin for Styled Components","description":"This package, `typescript-plugin-styled-components`, serves as a TypeScript transformer designed to enhance the development and debugging experience when working with `styled-components`. It achieves this by providing compile-time information, specifically the names of created styled components, to the runtime. This functionality is crucial for tools like style linting, inspecting components in development tools, and server-side rendering hydration. The current stable version is 3.0.0, which requires TypeScript 4.8+ or 5.0+. The release cadence is generally tied to significant TypeScript version updates. It's a key differentiator for projects that transpile TypeScript code directly using `tsc`, `ts-loader`, or `awesome-typescript-loader`, as opposed to those using Babel for TypeScript transformation, which should instead use `babel-plugin-styled-components`.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/Igorbek/typescript-plugin-styled-components","tags":["javascript","typescript"],"install":[{"cmd":"npm install typescript-plugin-styled-components","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-plugin-styled-components","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-plugin-styled-components","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for TypeScript compilation and API interaction.","package":"typescript","optional":false},{"reason":"This plugin enhances the usage of styled-components.","package":"styled-components","optional":false}],"imports":[{"note":"The primary API is a default export, typically used in build configuration files.","wrong":"import { createStyledComponentsTransformer } from 'typescript-plugin-styled-components';","symbol":"createStyledComponentsTransformer","correct":"import createStyledComponentsTransformer from 'typescript-plugin-styled-components';"},{"note":"For CommonJS, access the default export via the `.default` property.","wrong":"const createStyledComponentsTransformer = require('typescript-plugin-styled-components');","symbol":"createStyledComponentsTransformer","correct":"const createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;"}],"quickstart":{"code":"const createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;\nconst path = require('path');\n\n// Create a transformer; the factory additionally accepts an options object.\n// Example options: { ssr: true, displayName: true, componentIdPrefix: 'sc' }\nconst styledComponentsTransformer = createStyledComponentsTransformer();\n\nmodule.exports = {\n  mode: 'development', // or 'production'\n  entry: './src/index.ts',\n  output: {\n    filename: 'bundle.js',\n    path: path.resolve(__dirname, 'dist'),\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.tsx?$/,\n        loader: 'awesome-typescript-loader', // or 'ts-loader'\n        options: {\n          // Other loader options like `configFileName`\n          getCustomTransformers: () => ({ before: [styledComponentsTransformer] }),\n          // Important note: If using awesome-typescript-loader in forked process mode,\n          // this setup might require a different configuration approach documented\n          // on the plugin's GitHub page under 'Forked process configuration'.\n        }\n      }\n    ]\n  },\n  resolve: {\n    extensions: ['.ts', '.tsx', '.js', '.jsx']\n  }\n};","lang":"javascript","description":"Demonstrates how to integrate `typescript-plugin-styled-components` into a Webpack configuration using `awesome-typescript-loader` to enable compile-time styled component name generation."},"warnings":[{"fix":"Upgrade your project's TypeScript dependency to version 4.8, 5.0, or higher. Alternatively, for older TypeScript versions, pin the plugin to `typescript-plugin-styled-components@^2.0.0`.","message":"Version 3.0.0 introduces a breaking change, requiring TypeScript 4.8+ or 5.0+. Projects on older TypeScript versions will encounter compilation errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your project's TypeScript dependency to version 4.0 or higher. If unable to upgrade TypeScript, use `typescript-plugin-styled-components@^1.x.x`.","message":"Version 2.0.0 upgraded its internal TypeScript API usage to align with TypeScript 4+, making it incompatible with TypeScript versions prior to 4.0.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Verify your transpilation setup. If Babel is used, switch to `babel-plugin-styled-components`. If using TypeScript's own compiler or loaders, proceed with this plugin.","message":"This plugin is designed for projects transpiling TypeScript with `tsc` or loaders like `ts-loader` and `awesome-typescript-loader`. If your project uses Babel (specifically `babel-plugin-transform-typescript`) for TypeScript transpilation, this plugin will not function; you should instead use `babel-plugin-styled-components`.","severity":"gotcha","affected_versions":"*"},{"fix":"Update your `styled-components` code to use modern composition patterns, such as `styled(Component)` or object spreading for props.","message":"The `.extend` transformation pattern for styled-components was removed in version 1.5.0. Using this deprecated pattern will no longer be transformed correctly by the plugin.","severity":"deprecated","affected_versions":">=1.5.0"},{"fix":"Refer to the 'Forked process configuration' section in the `typescript-plugin-styled-components` documentation for `awesome-typescript-loader` to implement the correct setup.","message":"When `awesome-typescript-loader` operates in development mode with forked processes, the standard method of configuring `getCustomTransformers` (passing a function) does not work due to limitations in function serialization between processes.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your `getCustomTransformers` function returns an object in the format `{ before: [styledComponentsTransformer] }`.","cause":"The `getCustomTransformers` function in your webpack loader configuration is returning an object that either lacks a `before` property or its value is not an array.","error":"TypeError: customTransformers.before is not iterable"},{"fix":"For CommonJS, use `require('typescript-plugin-styled-components').default`. For ESM, use `import createStyledComponentsTransformer from 'typescript-plugin-styled-components'`.","cause":"Attempting to access the `default` export incorrectly in a CommonJS environment, or destructuring a module that primarily exports a default.","error":"Error: Cannot read properties of undefined (reading 'default')"},{"fix":"Check the plugin's peer dependencies and your installed TypeScript version. Upgrade TypeScript to meet the plugin's requirements (e.g., TS 4.8+/5.0+ for plugin v3.0.0).","cause":"Mismatch between the installed `typescript` version and the version required by `typescript-plugin-styled-components`, leading to incompatible TypeScript AST or API usage.","error":"TSxxxx: [Related to AST transformation or compiler API]"},{"fix":"Follow the 'Forked process configuration' instructions in the plugin's documentation for `awesome-typescript-loader`.","cause":"You are using `awesome-typescript-loader` in a forked process setup, which prevents passing functions like `getCustomTransformers` directly.","error":"awesome-typescript-loader: functions are not transferrable between processes in forked mode."}],"ecosystem":"npm"}