README.md

Emotion TypeScript Plugin

Features

Feature/Syntax	Native	Babel Plugin	TypeScript Plugin	Notes
css``	✅
css(...)	✅			Generally used for object styles.
styled('div')`` syntax	✅			Both string and object styles work without this plugin.
styled.div`` syntax	✅			Supporting the shortcut syntax without the Babel plugin requires a large list of valid elements to be included in the bundle.
components as selectors		✅	✅	Allows an emotion component to be used as a CSS selector.
Minification		✅	⛔️	Any leading/trailing space between properties in your css and styled blocks is removed. This can reduce the size of your final bundle.
Dead Code Elimination		✅	✅	Uglifyjs will use the injected /*#__PURE__*/ flag comments to mark your css and styled blocks as candidates for dead code elimination.
Source Maps		✅	✅	When enabled, navigate directly to the style declaration in your javascript file.
Contextual Class Names		✅	✅	Generated class names include the name of the variable or component they were defined in.

Usage

const { join } = require('path')
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
const HtmlWebpackPlugin = require('html-webpack-plugin')

const { createEmotionPlugin } = require('emotion-ts-plugin')

module.exports = {
  entry: './tests/fixtures/simple.tsx',

  output: {
    filename: '[name].[hash].js',
    path: join(process.cwd(), 'dist'),
  },

  resolve: {
    extensions: ['.tsx', '.ts', '.js', '.jsx'],
  },

  mode: 'development',

  devtool: 'cheap-module-source-map',

  module: {
    rules: [
      {
        test: /\.(j|t)sx?$/,
        loader: 'ts-loader',
        options: {
          transpileOnly: true,
          getCustomTransformers: () => ({
            before: [
              createEmotionPlugin({
                // <------------------- here
                sourcemap: true,
                autoLabel: true,
                labelFormat: '[local]',
                // if the jsxFactory is set, should we auto insert the import statement
                autoInject: true,
                // set for react@17 new jsx runtime
                // only effect if `autoInject` is true
                // set it in createEmotionPlugin options rather than in `tsconfig.json` will generate more optimized codes:
                // import { jsx } from 'react/jsx-runtime' for files not using emotion
                // import { jsx } from '@emotion/react/jsx-runtime' for files using emotion
                jsxImportSource: '@emotion/react',
              }),
            ],
          }),
          compilerOptions: {
            // set jsx pragma to jsx or alias which is from the @emotion/react package to enable css property in jsx component
            jsxFactory: 'jsx',
          },
        },
        exclude: /node_modules/,
      },
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, 'css-loader?minimize'],
      },
    ],
  },

  plugins: [
    new HtmlWebpackPlugin({
      template: join(process.cwd(), 'tests', 'fixtures', 'index.html'),
    }),
  ],
}

for customized exported(re-exported) styled

interface CustomModule {
  // module name used in import statement
  moduleName: string
  // `true` if you may import libs from 'my-emotion/subpath'
  includesSubPath?: boolean
  // all available names exported from custom module
  exportedNames: string[]
  // we may do some additional work on styled function, so if styled is reexport, you should specify it here
  styledName?: string
  // has default export
  hasDefaultExport?: boolean
}

createEmotionPlugin({
  ...otherConfig,
  customModules: [
    {
      moduleName: 'my-emotion',
      includesSubPath: true,
      exportedNames: ['myStyled', 'myCss']
      styledName: 'myStyled',
    }
  ]
})