CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-swc--plugin-emotion

SWC plugin for emotion css-in-js library that provides compile-time transformations to optimize emotion-based styling code

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Plugin Configuration

Configuration options for controlling @swc/plugin-emotion behavior including source maps, automatic labeling, and label formatting.

Capabilities

Plugin Configuration Interface

The main configuration interface for the emotion plugin.

/**
 * Configuration options for @swc/plugin-emotion
 * All options are optional and have sensible defaults
 */
interface EmotionPluginConfig {
  /** Enable/disable source map generation (default: true in development, false in production) */
  sourceMap?: boolean;
  /** Control when automatic labels are added to CSS */
  autoLabel?: "never" | "dev-only" | "always";
  /** Format string for generated labels with placeholder support */
  labelFormat?: string;
}

Source Map Configuration

Controls whether inline source maps are generated for transformed CSS.

/**
 * Source map generation setting
 * @default true in development environment, false in production
 */
sourceMap?: boolean;

Usage Examples:

// Enable source maps in all environments
{
  jsc: {
    experimental: {
      plugins: [["@swc/plugin-emotion", { sourceMap: true }]]
    }
  }
}

// Disable source maps completely
{
  jsc: {
    experimental: {
      plugins: [["@swc/plugin-emotion", { sourceMap: false }]]
    }
  }
}

Auto Label Configuration

Controls when automatic CSS class name labels are added to emotion styles.

/**
 * Automatic label generation setting
 * @default "dev-only"
 */
autoLabel?: "never" | "dev-only" | "always";

Label Modes:

  • "never": Never add automatic labels
  • "dev-only": Add labels only in development environment (default)
  • "always": Add labels in all environments

Usage Examples:

// Always add labels
{
  jsc: {
    experimental: {
      plugins: [["@swc/plugin-emotion", { autoLabel: "always" }]]
    }
  }
}

// Never add labels
{
  jsc: {
    experimental: {
      plugins: [["@swc/plugin-emotion", { autoLabel: "never" }]]
    }
  }
}

Label Format Configuration

Customizes the format of automatically generated CSS labels using placeholder tokens.

/**
 * Label format template with placeholder support
 * @default "[local]"
 */
labelFormat?: string;

Supported Placeholders:

  • [local]: Variable name or context identifier
  • [filename]: Current file name (without extension)
  • [dirname]: Parent directory name

Usage Examples:

// Custom label format with filename
{
  jsc: {
    experimental: {
      plugins: [["@swc/plugin-emotion", { 
        labelFormat: "[filename]--[local]" 
      }]]
    }
  }
}

// Include directory context
{
  jsc: {
    experimental: {
      plugins: [["@swc/plugin-emotion", { 
        labelFormat: "[dirname]-[local]" 
      }]]
    }
  }
}

Label Generation Examples:

// With labelFormat: "[filename]--[local]"
const buttonStyles = css`color: blue;`;
// Generates: label: "MyComponent--buttonStyles"

// With labelFormat: "[local]"  
const headerStyles = css`font-size: 24px;`;
// Generates: label: "headerStyles"

Complete Configuration Example

Full configuration with all available options:

{
  jsc: {
    parser: {
      syntax: "typescript",
      tsx: true
    },
    experimental: {
      plugins: [
        ["@swc/plugin-emotion", {
          sourceMap: true,
          autoLabel: "dev-only",
          labelFormat: "[filename]--[local]"
        }]
      ]
    }
  }
}

Environment-Based Configuration

The plugin automatically adapts behavior based on the build environment:

/**
 * Environment detection affects default behavior:
 * - Development: sourceMap defaults to true, autoLabel defaults to active
 * - Production: sourceMap defaults to false, autoLabel follows setting
 */

Environment Examples:

// Development environment behavior
process.env.NODE_ENV = "development";
// sourceMap: true (default), autoLabel: active if "dev-only" or "always"

// Production environment behavior  
process.env.NODE_ENV = "production";
// sourceMap: false (default), autoLabel: active only if "always"

Advanced Configuration

Import Map Configuration

For custom emotion library configurations, the plugin supports import mapping:

/**
 * Import map for custom emotion libraries (advanced usage)
 * Maps import sources to canonical emotion transformations
 */
interface ImportMap {
  [importSource: string]: {
    [localExportName: string]: {
      canonicalImport: [string, string]; // [packageName, exportName]
      styledBaseImport?: [string, string];
    };
  };
}

Install with Tessl CLI

npx tessl i tessl/npm-swc--plugin-emotion

docs

configuration.md

css-transformations.md

global-jsx-transformations.md

index.md

styled-transformations.md

tile.json