{"id":15043374,"url":"https://github.com/igorbek/typescript-plugin-styled-components","last_synced_at":"2025-04-08T08:12:18.108Z","repository":{"id":21898945,"uuid":"94284226","full_name":"Igorbek/typescript-plugin-styled-components","owner":"Igorbek","description":"TypeScript transformer for improving the debugging experience of styled-components","archived":false,"fork":false,"pushed_at":"2023-06-06T23:22:33.000Z","size":2247,"stargazers_count":419,"open_issues_count":33,"forks_count":33,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-08T08:12:12.340Z","etag":null,"topics":["styled-components","transformer","typescript","typescript-plugin","webpack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Igorbek.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-06-14T03:20:53.000Z","updated_at":"2025-04-02T08:49:34.000Z","dependencies_parsed_at":"2024-01-06T07:59:19.616Z","dependency_job_id":"8fcbe7b1-219b-4375-955a-794656cc0858","html_url":"https://github.com/Igorbek/typescript-plugin-styled-components","commit_stats":{"total_commits":180,"total_committers":17,"mean_commits":"10.588235294117647","dds":"0.48888888888888893","last_synced_commit":"6d6cf1c3a2e50915fe16c2ee1cd2d9f8850ecfd3"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Igorbek%2Ftypescript-plugin-styled-components","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Igorbek%2Ftypescript-plugin-styled-components/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Igorbek%2Ftypescript-plugin-styled-components/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Igorbek%2Ftypescript-plugin-styled-components/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Igorbek","download_url":"https://codeload.github.com/Igorbek/typescript-plugin-styled-components/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247801169,"owners_count":20998339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["styled-components","transformer","typescript","typescript-plugin","webpack"],"created_at":"2024-09-24T20:48:56.306Z","updated_at":"2025-04-08T08:12:18.088Z","avatar_url":"https://github.com/Igorbek.png","language":"TypeScript","readme":"# `typescript-plugin-styled-components`\n\nThis is a TypeScript transformer that improves development experience of [`styled-components`](https://www.styled-components.com/).\n\nThe main purpose is to provide compile-time information of creates styled components, such as names of these components, for the run-time, allowing to operate with proper names of such the components.\n\nThe plugin was mostly inspired by great Babel's plugin [`babel-plugin-styled-components`](https://github.com/styled-components/babel-plugin-styled-components) and partially provides similar functionality for TypeScript users.\n\nIf you like it, consider [![Buy me a coffee](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/igorbek)\n\nNote: This transformer will be useful to you only when you are transpiling your TS code using actual TS compiler, like `tsc` `ts-loader` or `awesome-typescript-loader`. If your TS code is transpiled using [`babel-plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript), you should use [`babel-plugin-styled-components`](https://github.com/styled-components/babel-plugin-styled-components) instead.\n\n# Installation\n\nThe following command adds the packages to the project as a development-time dependency:\n\n\u003cpre\u003e\u003ccode\u003e\u003cstrong\u003eyarn\u003c/strong\u003e add \u003cem\u003etypescript-plugin-styled-components\u003c/em\u003e --dev\u003c/code\u003e\u003c/pre\u003e\n\n# Documentation\n\n- [Integration with `Webpack`](#Integration-with-Webpack)\n  - [`awesome-typescript-loader`](#awesome-typescript-loader)\n  - [`ts-loader`](#ts-loader)\n  - [Forked process configuration](#Forked-process-configuration)\n- [Integration with `Rollup`](#Integration-with-Rollup)\n- [TypeScript compiler (CLI)](#TypeScript-compiler-CLI)\n- [`ttypescript` compiler](#ttypescript-compiler)\n- [API](#API)\n  - [`createTransformer`](#createTransformer)\n  - [`Options`](#Options)\n- [Notes](#Notes)\n\n# Integration with `Webpack`\n\nThis section describes how to integrate the plugin into the build/bundling process driven by [**Webpack**](https://webpack.js.org/) and its TypeScript loaders.\n\nThere are two popular TypeScript loaders that support specifying custom transformers:\n\n- [**awesome-typescript-loader**](https://github.com/s-panferov/awesome-typescript-loader), supports custom transformers since v3.1.3\n- [**ts-loader**](https://github.com/TypeStrong/ts-loader), supports custom transformers since v2.2.0\n\nBoth loaders use the same setting `getCustomTransformers` which is an optional function that returns `{ before?: Transformer[], after?: Transformer[] }`.\nIn order to inject the transformer into compilation, add it to `before` transformers array, like: `{ before: [styledComponentsTransformer] }`.\n\n## `awesome-typescript-loader`\n\nIn the `webpack.config.js` file in the section where **awesome-typescript-loader** is configured as a loader:\n\n```js\n// 1. import default from the plugin module\nconst createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;\n\n// 2. create a transformer;\n// the factory additionally accepts an options object which described below\nconst styledComponentsTransformer = createStyledComponentsTransformer();\n\n// 3. add getCustomTransformer method to the loader config\nvar config = {\n    ...\n    module: {\n        rules: [\n            {\n                test: /\\.tsx?$/,\n                loader: 'awesome-typescript-loader',\n                options: {\n                    ... // other loader's options\n                    getCustomTransformers: () =\u003e ({ before: [styledComponentsTransformer] })\n                }\n            }\n        ]\n    }\n    ...\n};\n```\n\nPlease note, that in the development mode, `awesome-typescript-loader` uses multiple separate processes to speed up compilation. In that mode the above configuration cannot work because functions, which `getCustomTransformers` is, are not transferrable between processes.\nTo solve this please refer to [Forked process configuration](#forked-process-configuration) section.\n\n## `ts-loader`\n\nIn the `webpack.config.js` file in the section where **ts-loader** is configured as a loader:\n\n```js\n// 1. import default from the plugin module\nconst createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;\n\n// 2. create a transformer;\n// the factory additionally accepts an options object which described below\nconst styledComponentsTransformer = createStyledComponentsTransformer();\n\n// 3. add getCustomTransformer method to the loader config\nvar config = {\n    ...\n    module: {\n        rules: [\n            {\n                test: /\\.tsx?$/,\n                loader: 'ts-loader',\n                options: {\n                    ... // other loader's options\n                    getCustomTransformers: () =\u003e ({ before: [styledComponentsTransformer] })\n                }\n            }\n        ]\n    }\n    ...\n};\n```\n\nPlease note, when `awesome-typescript-loader` is used with `HappyPack` or `thread-loader`, they use multiple separate processes to speed up compilation. In that mode the above configuration cannot work because functions, which `getCustomTransformers` is, are not transferrable between processes.\nTo solve this please refer to [Forked process configuration](#forked-process-configuration) section.\n\n## Forked process configuration\n\nTo configure the transformer for development mode in `awesome-typescript-loader` or `ts-loader` with `HappyPack` or `thread-loader`, you need to make `getCustomTransformers` a resolvable module name instead of the function. Since the configuration is very similar, here's an example:\n\n### 1. Move `styledComponentsTransformer` into a separate file\n\nLet's assume it is in the same folder as your `webpack.config` and has name `webpack.ts-transformers.js`:\n```js\n// 1. import default from the plugin module\nconst createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;\n\n// 2. create a transformer;\n// the factory additionally accepts an options object which described below\nconst styledComponentsTransformer = createStyledComponentsTransformer();\n\n// 3. create getCustomTransformer function\nconst getCustomTransformers = () =\u003e ({ before: [styledComponentsTransformer] });\n\n// 4. export getCustomTransformers\nmodule.exports = getCustomTransformers;\n```\n\n### 2. Change the loader's options to point to that file instead of explicit function\n\n```diff\n-const createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;\n-const styledComponentsTransformer = createStyledComponentsTransformer();\n\noptions: {\n    ... // other loader's options\n-    getCustomTransformers: () =\u003e ({ before: [styledComponentsTransformer] })\n+    getCustomTransformers: path.join(__dirname, './webpack.ts-transformers.js')\n}\n```\n\n# Integration with `Rollup`\n\nThis section describes how to integrate the plugin into the build/bundling process driven by [**Rollup**](https://rollupjs.org/guide/en/) and its TypeScript loader - [**rollup-plugin-typescript2**](https://github.com/Igorbek/typescript-plugin-styled-components).\n\nIn the `rollup.config.js` file in the section where **rollup-plugin-typescript2** is configured as a loader:\n\n```js\n// 1. import default from the plugin module\nconst createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;\n\n// 2. create a transformer;\n// the factory additionally accepts an options object which described below\nconst styledComponentsTransformer = createStyledComponentsTransformer();\n\n// 3. add getCustomTransformer method to the loader config\nvar config = {\n    ...\n    plugins: [\n      rollupTypescript({\n        ...\n        transformers: [\n          () =\u003e ({\n            before: [styledComponentsTransformer],\n          }),\n        ],\n      }),\n    ...\n    ],\n    ...\n};\n```\n\n# TypeScript compiler (CLI)\n\nTypeScript command line compiler tool (`tsc`) does not support using of pluggable modules and transformers.\nFor that reason there are other tools created that do support pluggable transformers. See [`ttypescript` compiler](#ttypescript-compiler) section.\n\n# `ttypescript` compiler\n\nThe [`ttypescript` compiler](https://github.com/cevek/ttypescript) is a CLI tool that allows to use TypeScript compiler with pluggable transformers.\nTo use the transformer with that tool you can configure it by updating `tsconfig.json` the following way:\n\n```js\n{\n    \"compilerOptions\": {\n        \"plugins\": [\n            {\n                \"transform\": \"typescript-plugin-styled-components\",\n                \"type\": \"config\",\n\n                // other typescript-plugin-styled-components options can be added here\n                \"minify\": true,\n                \"ssr\": true\n            }\n        ]\n    }\n}\n```\n\n# API\n\n## `createTransformer`\n\n```ts\nfunction createTransformer(options?: Partial\u003cOptions\u003e): TransformerFactory\u003cSourceFile\u003e;\n```\n\nA factory that creates an instance of a TypeScript transformer (which is a factory itself).\n\nIt allows to optionally pass options that allow to tweak transformer's behavior. See `Options` for details.\n\n## `Options`\n\n```ts\ninterface Options {\n    getDisplayName(filename: string, bindingName: string | undefined): string | undefined;\n    identifiers: CustomStyledIdentifiers;\n    ssr: boolean;\n    displayName: boolean;\n    minify: boolean;\n    componentIdPrefix: string;\n}\n```\n\n### `getDisplayName`\n\nThis method is used to determine component display name from filename and its binding name.\n\n`filename` is the file name, relative to the project base directory, of the file where the styled component defined.\n\n`bindingName` is the name that is used in the source code to bind the component. It can be `null` if the component was not bound or assigned.\n\nDefault strategy is to use `bindingName` if it's defined and use inference algorithm from `filename` otherwise.\n\nSample:\n```js\nfunction getStyledComponentDisplay(filename, bindingName) {\n    return bindingName || makePascalCase(filename);\n}\n```\n\n### `ssr`\n\nBy adding a unique identifier to every styled component, this plugin avoids checksum mismatches\ndue to different class generation on the client and on the server.\n\nThis option allows to disable component id generation by setting it to `false`.\n\nDefault value is `true` which means that component id is being injected.\n\n### `displayName`\n\nThis option enhances the attached CSS class name on each component with richer output\nto help identify your components in the DOM without React DevTools.\n\nIt also adds allows you to see the component's `displayName` in React DevTools.\n\nTo disable `displayName` generation set this option to `false`\n\nDefault value is `true` which means that display name is being injected.\n\n### `minify`\n\nThe option allows to turn on minification of inline styles used in styled components.\nIt is similar to [`babel-plugin-styled-components`](https://github.com/styled-components/babel-plugin-styled-components)'s same option.\nThe minification is not exactly the same and may produce slightly different results.\n\n:warning: **Warning**: The minification is an experimental feature, please use with care.\n\nDefault value is `false` which means the minification is not being performed.\n\n### `componentIdPrefix`\n\nTo avoid colisions when running more than one insance of typescript-plugin-styled-components at a time, you can add a componentIdPrefix by providing an arbitrary string to this option.\n\nDefault value is `''` which means that no namespacing will happen.\n\n### `identifiers`\n\nThis option allows to customize identifiers used by `styled-components` API functions.\n\n\u003e **Warning**. By providing custom identifiers, predefined ones are not added automatically.\n\u003e Make sure you add standard APIs in case you meant to use them.\n\n```ts\ninterface CustomStyledIdentifiers {\n    styled: string[];\n    attrs: string[];\n    keyframes: string[];\n    css: string[];\n    createGlobalStyle: string[];\n    extend: string[];\n}\n```\n\n- `styled` - list of identifiers of `styled` API (default `['styled']`)\n- `attrs` - list of identifiers of `attrs` API (default `['attrs']`)\n- `keyframes` - list of identifiers of `keyframes` API (default `['keyframes']`)\n- `css` - list of identifiers of `css` API (default `['css']`)\n- `createGlobalStyle` - list of identifiers of `createGlobalStyle` API (default `['createGlobalStyle']`)\n- `extend` - list of identifiers of `extend` API (default `[]`). Note this API has been deprecated in `styled-components` so starting from `1.5` this option by default has empty set, which means it does not recognize this API by default.\n\nExample\n\n```ts\nconst styledComponentsTransformer = createStyledComponentsTransformer({\n    identifiers: {\n        styled: ['styled', 'typedStyled'] // typedStyled is an additional identifier of styled API\n    }\n});\n```\n\n# Notes\n\nTechnically, `typescript-plugin-styled-components` is not a TypeScript plugin, since it is only exposed as a TypeScript transformer.\n","funding_links":["https://www.buymeacoffee.com/igorbek"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbek%2Ftypescript-plugin-styled-components","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorbek%2Ftypescript-plugin-styled-components","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbek%2Ftypescript-plugin-styled-components/lists"}