Internal utility functions used throughout the @emotion/babel-plugin for transforming code, managing imports, processing strings, and handling CSS minification.
Functions for manipulating and joining string literals and expressions during Babel transformations.
/**
* Appends a string or expression to the last argument of a call expression
* Handles TypeScript template object calls and regular string concatenation
* @param {Object} t - Babel types helper
* @param {Object} path - Babel path to CallExpression
* @param {string|Object} expression - String or AST expression to append
*/
function appendStringReturningExpressionToArguments(t, path, expression);
/**
* Joins consecutive string literals in an array of expressions
* Optimizes by combining adjacent string literals into single literals
* @param {Array} expressions - Array of expressions to process
* @param {Object} t - Babel types helper
* @returns {Array} Array with consecutive string literals joined
*/
function joinStringLiterals(expressions, t);Functions for managing imports and adding new import statements during transformation.
/**
* Adds an import statement to the file, with caching to avoid duplicates
* Supports both default and named imports using @babel/helper-module-imports
* @param {Object} state - Babel plugin state object
* @param {string} importSource - The module to import from (e.g., '@emotion/react')
* @param {string} importedSpecifier - The specifier to import ('default' or named export)
* @param {string} nameHint - Optional hint for the generated identifier name
* @returns {Object} AST Identifier node for the imported binding
*/
function addImport(state, importSource, importedSpecifier, nameHint);The main transformation function that handles all emotion code transformations including CSS template literals, call expressions, labeling, and source maps.
/**
* Main transformation function for emotion expressions
* Handles tagged template expressions, call expressions, minification, labeling, and source maps
* @param {Object} options - Transformation options
* @param {Object} options.babel - Babel instance with types and utilities
* @param {Object} options.state - Babel plugin state
* @param {Object} options.path - Babel path to the expression being transformed
* @param {boolean} options.shouldLabel - Whether to add automatic labels
* @param {string} options.sourceMap - Optional source map string to append
*/
function transformExpressionWithStyles({ babel, state, path, shouldLabel, sourceMap });Usage Example:
import { transformExpressionWithStyles } from '@emotion/babel-plugin/utils';
// Inside a Babel visitor
visitor: {
CallExpression(path, state) {
if (isEmotionCall(path)) {
transformExpressionWithStyles({
babel,
state,
path,
shouldLabel: true,
sourceMap: getSourceMap(path.node.loc.start, state)
});
}
}
}Template literal minification using Stylis CSS parser for optimized output.
/**
* Minifies CSS template literals using Stylis compiler
* Parses CSS, removes unnecessary whitespace, and replaces template with call expression
* @param {Object} path - Babel path to TaggedTemplateExpression
* @param {Object} t - Babel types helper
*/
function minify(path, t);Usage Example:
// Input tagged template:
const styles = css`
color: red;
padding: 10px;
`;
// After minification:
const styles = css('color:red;padding:10px;');Converts CSS object expressions to string literals when possible for optimization.
/**
* Simplifies CSS object expressions to string literals where possible
* Handles nested objects and serializes using @emotion/serialize
* @param {Object} node - ObjectExpression AST node
* @param {Object} t - Babel types helper
* @returns {Object} StringLiteral node if simplifiable, original node otherwise
*/
function simplifyObject(node, t);Usage Example:
// Input object:
const styles = css({
color: 'red',
padding: '10px',
'&:hover': {
color: 'blue'
}
});
// After simplification:
const styles = css('color:red;padding:10px;&:hover{color:blue;}');Utilities for generating and managing source maps during transformation.
/**
* Generates source map string for a given location
* @param {Object} location - Source location with line and column
* @param {Object} state - Babel plugin state with file information
* @returns {string} Source map comment string
*/
function getSourceMap(location, state);Functions for generating automatic CSS class labels based on variable names and file paths.
/**
* Generates automatic label for CSS based on variable name and context
* @param {Object} path - Babel path to the expression
* @param {Object} state - Babel plugin state
* @param {Object} t - Babel types helper
* @returns {string|null} Generated label or null if not applicable
*/
function getLabelFromPath(path, state, t);Utilities for creating development/production conditional code.
/**
* Creates conditional expression based on NODE_ENV
* @param {Object} t - Babel types helper
* @param {Object} prodNode - AST node for production
* @param {Object} devNode - AST node for development
* @returns {Object} ConditionalExpression AST node
*/
function createNodeEnvConditional(t, prodNode, devNode);The utility functions include comprehensive error handling:
_templateObject calls/**
* Error message shown when CSS object is incorrectly stringified
*/
const CSS_OBJECT_STRINGIFIED_ERROR = "You have tried to stringify object returned from `css` function. It isn't supposed to be used directly (e.g. as value of the `className` prop), but rather handed to emotion so it can handle it (e.g. as value of `css` prop).";
/**
* Valid values for autoLabel option
*/
const AUTO_LABEL_VALUES = ['dev-only', 'never', 'always'];