{"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,"search_vec":"'3.0.0':76 '4.8':80 '5.0':82 'achiev':33 'awesom':113 'awesome-typescript-load':112 'babel':121,130 'babel-plugin-styled-compon':129 'cadenc':85 'code':104 'compil':38 'compile-tim':37 'compon':5,12,31,47,61,133 'creat':45 'crucial':54 'current':72 'debug':24 'design':18 'develop':22,63 'differenti':98 'direct':105 'enhanc':20 'experi':25 'function':52 'general':87 'hydrat':70 'inform':40 'inspect':60 'instead':127 'javascript':134 'key':97 'like':57 'lint':59 'loader':110,115 'name':43 'oppos':117 'packag':7 'plugin':2,10,131 'project':100 'provid':36 'releas':84 'render':69 'requir':78 'runtim':50 'serv':13 'server':67 'server-sid':66 'side':68 'signific':90 'specif':41 'stabl':73 'style':4,11,30,46,58,132 'styled-compon':29 'tie':88 'time':39 'tool':56,64 'transform':17,124 'transpil':102 'ts':109 'ts-loader':108 'tsc':107 'typescript':1,9,16,79,91,103,114,123,135 'typescript-plugin-styled-compon':8 'updat':93 'use':106,120,128 'version':74,92 'work':27","created_at":"2026-04-19T13:42:11.979075+00:00","updated_at":"2026-04-19T13:42:11.979075+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Igorbek/typescript-plugin-styled-components","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/typescript-plugin-styled-components","openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}