or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

css-processing.mddevelopment-features.mdimport-mapping.mdindex.mdmacro-system.mdplugin-configuration.mdstyled-components.mdutility-functions.md
tile.json

import-mapping.mddocs/

Import Mapping

Custom import mapping configuration for packages that re-export emotion functionality.

Capabilities

Import Map Configuration

Allows packages to re-export emotion functions while maintaining babel plugin transformations.

/**
 * Import mapping configuration for re-exported emotion functions
 */
interface ImportMap {
  [packageName: string]: {
    [exportName: string]: {
      canonicalImport: [string, string];
      styledBaseImport?: [string, string];
    };
  };
}

Basic Import Mapping:

Configuration:

{
  "importMap": {
    "my-design-system": {
      "styled": {
        "canonicalImport": ["@emotion/styled", "default"]
      },
      "css": {
        "canonicalImport": ["@emotion/react", "css"]
      }
    }
  }
}

Usage:

// Your re-export package
import { styled, css } from 'my-design-system';

const Button = styled.button`
  padding: 10px;
`;

const styles = css`
  color: blue;
`;

The plugin will transform these as if they were imported directly from emotion.

Canonical Import Mapping

Maps re-exported functions to their original emotion package exports.

/**
 * Maps re-exported functions to canonical emotion imports
 * @param {[string, string]} canonicalImport - [packageName, exportName] tuple
 */
interface CanonicalImportMapping {
  canonicalImport: [string, string];
}

Canonical Import Examples:

// Map custom exports to emotion exports
{
  "my-package": {
    "myStyled": {
      "canonicalImport": ["@emotion/styled", "default"]
    },
    "myCss": {
      "canonicalImport": ["@emotion/react", "css"]
    },
    "myKeyframes": {
      "canonicalImport": ["@emotion/react", "keyframes"]
    }
  }
}

Styled Base Import Optimization

Optimizes styled component imports for production builds.

/**
 * Optional styled base import for production optimization
 * @param {[string, string]} styledBaseImport - [packageName, exportName] for base import
 */
interface StyledBaseImportMapping {
  styledBaseImport?: [string, string];
}

Styled Base Import Example:

{
  "my-styled-package": {
    "Button": {
      "canonicalImport": ["@emotion/styled", "default"],
      "styledBaseImport": ["@emotion/styled/base", "default"]
    }
  }
}

This maps development imports to full styled package and production imports to optimized base package.

JSX React Import Handling

Special handling for JSX and React-specific emotion exports.

/**
 * JSX React import configuration
 */
interface JSXReactImport {
  importSource: string;
  export: string;
  cssExport: string;
}

JSX Import Mapping:

{
  "my-react-package": {
    "jsx": {
      "canonicalImport": ["@emotion/react", "jsx"]
    },
    "css": {
      "canonicalImport": ["@emotion/react", "css"]
    }
  }
}

Important: When mapping JSX exports, you must also map the corresponding CSS export, as they work together.

Global Component Mapping

Mapping for Global component and its CSS dependency.

/**
 * Global component requires CSS export mapping
 * @param {string} cssExport - Name of CSS export in the same package
 */
interface GlobalComponentMapping {
  canonicalImport: ["@emotion/react", "Global"];
  cssExport: string;
}

Global Component Example:

{
  "my-global-package": {
    "GlobalStyles": {
      "canonicalImport": ["@emotion/react", "Global"]
    },
    "css": {
      "canonicalImport": ["@emotion/react", "css"]
    }
  }
}

Usage:

import { GlobalStyles, css } from 'my-global-package';

const globalStyles = css`
  body { margin: 0; }
`;

function App() {
  return (
    <>
      <GlobalStyles styles={globalStyles} />
      <div>App content</div>
    </>
  );
}

Complete Import Map Examples

Design System Re-exports

{
  "importMap": {
    "@my-company/design-system": {
      "styled": {
        "canonicalImport": ["@emotion/styled", "default"],
        "styledBaseImport": ["@emotion/styled/base", "default"]
      },
      "css": {
        "canonicalImport": ["@emotion/react", "css"]
      },
      "jsx": {
        "canonicalImport": ["@emotion/react", "jsx"]
      },
      "Global": {
        "canonicalImport": ["@emotion/react", "Global"]
      },
      "keyframes": {
        "canonicalImport": ["@emotion/react", "keyframes"]
      }
    }
  }
}

Theme Provider Re-exports

{
  "importMap": {
    "@my-company/theme": {
      "ThemeProvider": {
        "canonicalImport": ["@emotion/react", "ThemeProvider"]
      },
      "useTheme": {
        "canonicalImport": ["@emotion/react", "useTheme"]
      },
      "withTheme": {
        "canonicalImport": ["@emotion/react", "withTheme"]
      },
      "css": {
        "canonicalImport": ["@emotion/react", "css"]
      }
    }
  }
}

Custom Styled Components

{
  "importMap": {
    "@my-company/components": {
      "Button": {
        "canonicalImport": ["@emotion/styled", "default"]
      },
      "Card": {
        "canonicalImport": ["@emotion/styled", "default"]
      },
      "css": {
        "canonicalImport": ["@emotion/react", "css"]
      }
    }
  }
}

Import Map Processing

Import Detection

/**
 * Detects and processes import declarations with mapped packages
 * @param {BabelPath} path - ImportDeclaration path
 * @param {Object} state - Plugin state with importMap
 */
function processImportMapping(path, state);

The plugin:

  1. Checks if import source matches any importMap keys
  2. Maps each imported specifier to its canonical import
  3. Creates appropriate transformer macro for the import
  4. Registers the macro for processing

Transformer Creation

/**
 * Creates transformer macros from import map configuration
 * @param {Object} transformers - Transformer configurations
 * @param {Object} options - Macro options including importSource
 * @returns {TransformerMacro} Generated transformer macro
 */
function createTransformerMacro(transformers, options);

Transformer Creation Process:

  1. Parse Configuration: Extract canonical imports and options
  2. Validate Mappings: Ensure required exports exist (e.g., css for jsx)
  3. Create Transformers: Build transformer functions for each export
  4. Register Macro: Add macro to plugin state for processing

Error Handling

/**
 * Validates import map configuration and provides clear error messages
 */
function validateImportMap(importMap);

Common Import Map Errors:

  1. Missing CSS Export: When jsx is mapped but css is not
  2. Unknown Transformer: When canonical import references unsupported package
  3. Invalid Configuration: When canonicalImport format is incorrect

Error Examples:

// Error: Missing CSS export
{
  "my-package": {
    "jsx": {
      "canonicalImport": ["@emotion/react", "jsx"]
    }
    // Missing required "css" export
  }
}

Error message:

You have specified that 'my-package' re-exports 'jsx' from '@emotion/react' 
but it doesn't also re-export 'css' from '@emotion/react', 'css' is necessary 
for certain optimisations, please re-export it from 'my-package'

Advanced Import Mapping

Conditional Mappings

/**
 * Conditional import mappings based on environment or configuration
 */
interface ConditionalImportMap {
  [condition: string]: ImportMap;
}

Environment-Specific Mappings:

{
  "importMap": {
    "@my-company/emotion": {
      "styled": {
        "canonicalImport": ["@emotion/styled", "default"],
        "styledBaseImport": process.env.NODE_ENV === 'production' 
          ? ["@emotion/styled/base", "default"] 
          : ["@emotion/styled", "default"]
      }
    }
  }
}

Package Version Compatibility

/**
 * Handles version compatibility for re-exported packages
 * Ensures transformations work across different emotion versions
 */
function handleVersionCompatibility(canonicalImport, options);

This ensures that import mappings work correctly even when the re-exporting package uses different versions of emotion packages than the consuming application.