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

Development Features

Development-focused features including automatic labeling, source maps, and debugging utilities.

Capabilities

Automatic Labeling

Generates contextual class names based on variable names and file locations for easier debugging.

/**
 * Generates labels for CSS and styled components based on variable names
 * @param {BabelPath} path - AST path
 * @param {string} labelFormat - Label format string with placeholders
 * @returns {string} Generated label
 */
function getLabelFromPath(path, labelFormat);

Label Generation Examples:

Basic labeling with autoLabel: 'dev-only':

Input:

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

const PrimaryButton = styled.button`
  color: white;
`;

Output:

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

const PrimaryButton = /*#__PURE__*/ styled('button', {
  label: 'PrimaryButton'
})({
  color: 'white'
});

Custom Label Formats:

With labelFormat: "[filename]--[local]" in file Button.js:

Input:

const primaryStyles = css`
  color: blue;
`;

Output:

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

Label Format Placeholders

Available placeholders for custom label formatting.

/**
 * Supported label format placeholders:
 * [local] - Variable name
 * [filename] - File name without extension
 * [dirname] - Directory name containing the file
 */
interface LabelPlaceholders {
  local: string;
  filename: string;
  dirname: string;
}

Label Format Examples:

// Configuration examples
{
  "labelFormat": "[local]"                    // → "buttonStyles"
  "labelFormat": "[filename]--[local]"        // → "Button--buttonStyles"
  "labelFormat": "[dirname]-[filename]"       // → "components-Button"
  "labelFormat": "app-[dirname]-[local]"      // → "app-components-buttonStyles"
}

Source Map Generation

Generates source maps linking generated CSS back to original template literals for debugging.

/**
 * Generates source map information for CSS template literals
 * @param {BabelPath} path - AST path for template literal
 * @param {Object} state - Plugin state
 * @returns {Object} Source map data
 */
function getSourceMap(path, state);

Source Map Integration:

When sourceMap: true is enabled, the plugin:

Tracks original template literal positions
Maps generated CSS strings to source locations
Embeds source map comments in development builds
Removes source maps in production builds

Example with source maps:

Input in styles/Button.js:15:20:

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

Generated source map points CSS padding:10px;background:blue; back to styles/Button.js:15:20.

Development Environment Detection

Automatically detects development vs production environments for conditional features.

/**
 * Creates conditional expressions based on NODE_ENV
 * @param {Object} babel - Babel types
 * @param {any} consequent - Expression for development
 * @param {any} alternate - Expression for production (optional)
 * @returns {ConditionalExpression} NODE_ENV conditional
 */
function createNodeEnvConditional(babel, consequent, alternate);

Development/Production Conditionals:

The plugin automatically wraps development features in NODE_ENV checks:

// Development: Labels included
const styles = /*#__PURE__*/ css(
  'color:blue;',
  process.env.NODE_ENV !== 'production' ? 'label:styles;' : ''
);

// Production: Labels removed
const styles = /*#__PURE__*/ css('color:blue;');

CSS Variable Name Sanitization

Sanitizes variable names for valid CSS class name generation.

/**
 * Sanitizes variable names for CSS class names
 * Removes invalid characters and ensures CSS compatibility
 * @param {string} name - Variable name
 * @returns {string} Sanitized CSS class name
 */
function sanitizeCssIdentifier(name);

Sanitization Examples:

// Input variable names → Output CSS class names
"iconStyles$1"     → "iconStyles1"      // Remove $
"my-component_v2"  → "my-component_v2"  // Keep valid chars
"Component123"     → "Component123"     // Keep alphanumeric
"🎨styles"         → "styles"           // Remove emojis

Debug Information

Adds debug information to transformed code for easier troubleshooting.

/**
 * Adds debug comments and metadata to transformed code
 * @param {BabelPath} path - AST path
 * @param {Object} debugInfo - Debug information
 */
function addDebugInfo(path, debugInfo);

Debug Features:

Source Comments: Comments indicating original source location
Transformation Type: Comments indicating type of transformation applied
Label Preservation: Maintains original variable names in labels
Error Context: Enhanced error messages with code frame context

Browser DevTools Integration

Optimizes output for browser developer tools inspection.

/**
 * Optimizes class names and source maps for browser inspection
 * Ensures generated class names are meaningful in DevTools
 */
function optimizeForDevTools(styles, sourceInfo);

DevTools Features:

Meaningful Class Names: Generated classes include component/variable names
Source Map Links: CSS rules link back to original JavaScript files
Hierarchical Display: Nested styles maintain source relationships
Hot Reload Support: Source maps work with development servers

Example DevTools Integration:

CSS in browser:

.css-1q8eu9e-buttonStyles {
  padding: 10px;
  background: blue;
}

DevTools shows:

Source: components/Button.js:15
Original: const buttonStyles = css\padding: 10px; background: blue;``

Development-Only Features

Features that are automatically excluded from production builds.

/**
 * Development-only features automatically removed in production:
 * - Label generation (when autoLabel: 'dev-only')
 * - Source map comments  
 * - Debug information
 * - Verbose error messages
 */
interface DevelopmentFeatures {
  labels: boolean;
  sourceMaps: boolean;
  debugInfo: boolean;
  verboseErrors: boolean;
}

Production Optimization:

Development build:

const Button = /*#__PURE__*/ styled('button', {
  label: 'Button',
  __emotion_base_label: 'components/Button--Button'
})({
  padding: '10px'
});

Production build:

const Button = /*#__PURE__*/ styled('button')({
  padding: '10px'
});

Error Context Enhancement

Provides enhanced error messages with code frame context.

/**
 * Builds enhanced error messages with code frame context
 * @param {BabelPath} path - AST path where error occurred
 * @param {Error} error - Original error
 * @returns {Error} Enhanced error with code frame
 */
function buildCodeFrameError(path, error);

Enhanced Error Example:

Standard error:

SyntaxError: Unexpected token

Enhanced error:

SyntaxError: Unexpected token in CSS template literal

  components/Button.js:15:20
  
  13 | const Button = styled.button`
  14 |   padding: 10px;
> 15 |   background: ${invalidExpression;
     |                                   ^
  16 |   color: white;
  17 | `;
  
  Invalid JavaScript expression in CSS template literal

Performance Monitoring

Development-time performance monitoring for transformation overhead.

/**
 * Monitors transformation performance in development
 * Tracks time spent on different transformation phases
 */
function monitorTransformationPerformance(phase, callback);

Development logging:

@emotion/babel-plugin performance:
  CSS processing: 45ms (234 templates)
  Styled components: 23ms (67 components)  
  Source maps: 12ms
  Total: 80ms

Version

Tile

Files