or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdmacros.mdtransformation.md
tile.json

configuration.mddocs/

Plugin Configuration

Comprehensive configuration options for babel-plugin-emotion, controlling optimization behavior, labeling, source maps, and import mapping.

Capabilities

Main Plugin Function

The default export that creates the Babel plugin with specified configuration.

/**
 * Main Babel plugin factory function
 * @param babel - Babel instance providing types and utilities
 * @param options - Plugin configuration options
 * @returns Babel plugin object with name, inherits, and visitor
 * @throws Error if autoLabel option is invalid
 */
function emotionBabelPlugin(babel: any, options: EmotionPluginOptions): BabelPlugin;

Usage Example:

// In Babel configuration
{
  "plugins": [
    ["@emotion", {
      "sourceMap": true,
      "autoLabel": "dev-only",
      "labelFormat": "[filename]--[local]",
      "cssPropOptimization": true
    }]
  ]
}

Source Map Configuration

Controls source map generation for transformed styles.

/**
 * Source map configuration option
 * @default true
 */
sourceMap?: boolean;

When enabled:

  • Injects source maps for browser dev tools
  • Provides debugging information linking transformed CSS to original source
  • Automatically removed in production builds

Usage Example:

// Enable source maps (default)
{
  "plugins": [["@emotion", { "sourceMap": true }]]
}

// Disable source maps
{
  "plugins": [["@emotion", { "sourceMap": false }]]
}

Auto Label Configuration

Controls automatic generation of contextual class names.

/**
 * Auto label behavior configuration
 * @default "dev-only"
 */
autoLabel?: 'dev-only' | 'always' | 'never';

Values:

  • 'dev-only': Adds labels in development, optimizes them out in production
  • 'always': Always adds labels when possible
  • 'never': Disables automatic labeling entirely

Usage Example:

// Input with autoLabel: 'dev-only'
const brownStyles = css({ color: 'brown' });

// Output  
const brownStyles = /*#__PURE__*/ css({ color: 'brown' }, 'label:brownStyles;');
// Result class: css-1q8eu9e-brownStyles

Label Format Configuration

Defines the format of generated labels when autoLabel is enabled.

/**
 * Label format string with variable substitution
 * @default "[local]"
 */
labelFormat?: string;

Available variables:

  • [local]: Variable name that the css/styled result is assigned to
  • [filename]: File name (without extension) containing the expression
  • [dirname]: Directory name containing the file

Usage Example:

// Configuration
{
  "labelFormat": "[filename]--[local]"
}

// Input in BrownView.js
const brownStyles = css({ color: 'brown' });

// Output
const brownStyles = /*#__PURE__*/ css(
  { color: 'brown' },
  'label:BrownView--brownStyles;'
);
// Result class: css-hash-BrownView--brownStyles

CSS Prop Optimization

Controls optimization of the css prop in JSX elements.

/**
 * CSS prop optimization configuration
 * @default true
 */
cssPropOptimization?: boolean;

When enabled:

  • Assumes @emotion/react's jsx function is configured for all JSX
  • Optimizes css prop usage during transformation
  • Should be disabled if not using emotion's jsx function globally

Usage Example:

// With cssPropOptimization: true (default)
<div css={{ color: 'blue', fontSize: 16 }} />

// Gets optimized during transformation

Import Map Configuration

Enables transformation of re-exported emotion APIs through custom import mapping.

/**
 * Custom import mapping for re-exported emotion APIs
 */
importMap?: ImportMap;

interface ImportMap {
  [importSource: string]: {
    [exportName: string]: {
      /** [packageName, exportName] tuple pointing to canonical emotion export */
      canonicalImport: [string, string];
      /** Additional options for the specific transformer */
      [key: string]: any;
    };
  };
}

Usage Example:

{
  "importMap": {
    "my-package": {
      "anotherExport": {
        "canonicalImport": ["@emotion/styled", "default"],
        "styledBaseImport": ["my-package/base", "anotherExport"]
      }
    },
    "some-package": {
      "someExport": {
        "canonicalImport": ["@emotion/react", "css"]
      },
      "thisIsTheJsxExport": {
        "canonicalImport": ["@emotion/react", "jsx"]
      }
    }
  }
}

Types

interface EmotionPluginOptions {
  sourceMap?: boolean;
  autoLabel?: 'dev-only' | 'always' | 'never';
  labelFormat?: string;
  cssPropOptimization?: boolean;
  importMap?: ImportMap;
}

interface BabelPlugin {
  name: string;
  inherits: any;
  visitor: BabelVisitor;
}

/** Constant array of valid autoLabel values */
const AUTO_LABEL_VALUES: ['dev-only', 'never', 'always'];