or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

css-processing.md development-features.md import-mapping.md index.md macro-system.md plugin-configuration.md styled-components.md utility-functions.md

tile.json

Plugin Configuration

Plugin configuration options and setup for @emotion/babel-plugin.

Capabilities

Main Plugin Function

The default export provides the main Babel plugin function that processes emotion code.

/**
 * Main Babel plugin function for @emotion/babel-plugin
 * @param {Object} babel - Babel instance with types and utilities
 * @param {PluginOptions} options - Plugin configuration options
 * @returns {PluginConfig} Babel plugin configuration object
 */
function emotionBabelPlugin(babel, options = {});

interface PluginConfig {
  name: string;
  manipulateOptions: (opts: any, parserOpts: any) => void;
  visitor: {
    ImportDeclaration: (path: any, state: any) => void;
    Program: (path: any, state: any) => void;
    JSXAttribute: (path: any, state: any) => void;
    CallExpression: {
      exit: (path: any, state: any) => void;
    };
  };
}

Configuration Options

Plugin options that control transformation behavior.

interface PluginOptions {
  /** Enable source map generation (default: true) */
  sourceMap?: boolean;
  /** Automatic label generation mode (default: 'dev-only') */
  autoLabel?: 'dev-only' | 'always' | 'never';
  /** Label format string with placeholders (default: '[local]') */
  labelFormat?: string;
  /** Enable CSS prop optimization (default: true) */
  cssPropOptimization?: boolean;
  /** Custom import mapping for re-exported emotion functions */
  importMap?: ImportMap;
}

Usage Examples:

Basic Configuration:

{
  "plugins": ["@emotion"]
}

Advanced Configuration:

{
  "plugins": [
    [
      "@emotion",
      {
        "sourceMap": true,
        "autoLabel": "dev-only",
        "labelFormat": "[filename]--[local]",
        "cssPropOptimization": true,
        "importMap": {
          "my-emotion-wrapper": {
            "myStyled": {
              "canonicalImport": ["@emotion/styled", "default"]
            }
          }
        }
      }
    ]
  ]
}

sourceMap Option

Controls source map generation for debugging CSS in development tools.

/** Enable source map generation (default: true) */
sourceMap?: boolean;

When enabled, the plugin injects source maps that link generated CSS back to the original template literals in your JavaScript files. Source maps are automatically removed in production builds.

autoLabel Option

Controls automatic labeling of CSS and styled components for better debugging.

/** Automatic label generation mode (default: 'dev-only') */
autoLabel?: 'dev-only' | 'always' | 'never';

'dev-only': Labels only in development builds (recommended)
'always': Labels in all builds
'never': No automatic labeling

Example transformation with autoLabel:

Input:

const buttonStyles = css`
  padding: 10px;
`;

Output with autoLabel: 'dev-only':

const buttonStyles = /*#__PURE__*/ css(
  'padding:10px;',
  'label:buttonStyles;'
);

labelFormat Option

Customizes the format of generated labels when autoLabel is enabled.

/** Label format string with placeholders (default: '[local]') */
labelFormat?: string;

Supported placeholders:

[local]: Variable name
[filename]: File name without extension
[dirname]: Directory name

Example with custom label format:

Configuration:

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

Input in file Button.js:

const primaryStyles = css`
  color: blue;
`;

Output:

const primaryStyles = /*#__PURE__*/ css(
  'color:blue;',
  'label:Button--primaryStyles;'
);

cssPropOptimization Option

Controls optimization of JSX css prop expressions.

/** Enable CSS prop optimization (default: true) */
cssPropOptimization?: boolean;

When enabled, optimizes array and object expressions in JSX css props:

// Array expressions - optimized
<div css={[baseStyles, { color: 'red' }]} />

// Object expressions - optimized
<div css={{ padding: 10, margin: 5 }} />

Babel Integration

Parser Configuration

The plugin automatically configures Babel's parser to support JSX when needed.

/**
 * Manipulates Babel parser options to ensure JSX support
 * @param {Object} opts - Babel options
 * @param {Object} parserOpts - Parser options
 */
manipulateOptions(opts: any, parserOpts: any): void;

This ensures JSX parsing is enabled when TypeScript or JSX plugins aren't already configured.

Visitor Pattern

The plugin uses Babel's visitor pattern to transform AST nodes.

interface PluginVisitor {
  /** Handles emotion package imports and macro transformations */
  ImportDeclaration: (path: BabelPath, state: EmotionBabelPluginPass) => void;
  /** Sets up plugin state and macro mappings */
  Program: (path: BabelPath, state: EmotionBabelPluginPass) => void;
  /** Handles css prop transformations in JSX */
  JSXAttribute: (path: BabelPath, state: EmotionBabelPluginPass) => void;
  /** Handles withComponent calls on styled components */
  CallExpression: {
    exit: (path: BabelPath, state: EmotionBabelPluginPass) => void;
  };
}

Plugin State

EmotionBabelPluginPass

State object passed through the plugin during transformation.

interface EmotionBabelPluginPass {
  /** Registered transformer macros by import source */
  pluginMacros: { [importSource: string]: TransformerMacro };
  /** JSX React import configuration */
  jsxReactImport: {
    importSource: string;
    export: string;
    cssExport: string;
  };
  /** Whether to transform css props */
  transformCssProp: boolean;
  /** Whether to generate source maps */
  emotionSourceMap: boolean;
  /** Plugin configuration options */
  opts: PluginOptions;
}

Version

Tile

Files