TypeScript Plugin for Styled Components

Common errors

• TypeError: customTransformers.before is not iterable

  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.
  fix Ensure your `getCustomTransformers` function returns an object in the format `{ before: [styledComponentsTransformer] }`.

• Error: Cannot read properties of undefined (reading 'default')

  cause Attempting to access the `default` export incorrectly in a CommonJS environment, or destructuring a module that primarily exports a default.
  fix For CommonJS, use `require('typescript-plugin-styled-components').default`. For ESM, use `import createStyledComponentsTransformer from 'typescript-plugin-styled-components'`.

• TSxxxx: [Related to AST transformation or compiler API]

  cause Mismatch between the installed `typescript` version and the version required by `typescript-plugin-styled-components`, leading to incompatible TypeScript AST or API usage.
  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).

• awesome-typescript-loader: functions are not transferrable between processes in forked mode.

  cause You are using `awesome-typescript-loader` in a forked process setup, which prevents passing functions like `getCustomTransformers` directly.
  fix Follow the 'Forked process configuration' instructions in the plugin's documentation for `awesome-typescript-loader`.

Warnings

• breaking Version 3.0.0 introduces a breaking change, requiring TypeScript 4.8+ or 5.0+. Projects on older TypeScript versions will encounter compilation errors.
  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`.
• breaking 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.
  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`.
• gotcha 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`.
  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.
• deprecated 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.
  Fix: Update your `styled-components` code to use modern composition patterns, such as `styled(Component)` or object spreading for props.
• gotcha 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.
  Fix: Refer to the 'Forked process configuration' section in the `typescript-plugin-styled-components` documentation for `awesome-typescript-loader` to implement the correct setup.

Install

• npm install typescript-plugin-styled-components npm
• yarn add typescript-plugin-styled-components yarn
• pnpm add typescript-plugin-styled-components pnpm

Imports

• createStyledComponentsTransformer
  wrong:

  import { createStyledComponentsTransformer } from 'typescript-plugin-styled-components';

  correct:

  import createStyledComponentsTransformer from 'typescript-plugin-styled-components';

  The primary API is a default export, typically used in build configuration files.
• createStyledComponentsTransformer
  wrong:

  const createStyledComponentsTransformer = require('typescript-plugin-styled-components');

  correct:

  const createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;

  For CommonJS, access the default export via the `.default` property.

Quickstart

Demonstrates how to integrate `typescript-plugin-styled-components` into a Webpack configuration using `awesome-typescript-loader` to enable compile-time styled component name generation.

const createStyledComponentsTransformer = require('typescript-plugin-styled-components').default;
const path = require('path');

// Create a transformer; the factory additionally accepts an options object.
// Example options: { ssr: true, displayName: true, componentIdPrefix: 'sc' }
const styledComponentsTransformer = createStyledComponentsTransformer();

module.exports = {
  mode: 'development', // or 'production'
  entry: './src/index.ts',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'awesome-typescript-loader', // or 'ts-loader'
        options: {
          // Other loader options like `configFileName`
          getCustomTransformers: () => ({ before: [styledComponentsTransformer] }),
          // Important note: If using awesome-typescript-loader in forked process mode,
          // this setup might require a different configuration approach documented
          // on the plugin's GitHub page under 'Forked process configuration'.
        }
      }
    ]
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx']
  }
};