or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-emotion--babel-preset-css-prop

A babel preset to automatically enable emotion's css prop

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@emotion/babel-preset-css-prop@11.12.x

To install, run

npx @tessl/cli install tessl/npm-emotion--babel-preset-css-prop@11.12.0

@emotion/babel-preset-css-prop

@emotion/babel-preset-css-prop is a Babel preset that automatically enables Emotion's css prop functionality for React applications using the classic JSX runtime. It transforms JSX elements to use Emotion's jsx function instead of React.createElement, enabling seamless CSS-in-JS styling across your entire project through a single Babel configuration entry.

Package Information

Package Name: @emotion/babel-preset-css-prop
Package Type: npm
Language: JavaScript
Installation: npm install @emotion/babel-preset-css-prop

Core Imports

Since this is a Babel preset, it's configured in your Babel configuration rather than imported in code:

.babelrc

{
  "presets": ["@emotion/babel-preset-css-prop"]
}

babel.config.js

module.exports = {
  presets: ["@emotion/babel-preset-css-prop"]
};

Node API

require('@babel/core').transform(code, {
  presets: ['@emotion/babel-preset-css-prop']
});

Basic Usage

Once configured, the preset automatically transforms JSX to enable the css prop:

const Link = props => (
  <a
    css={{
      color: 'hotpink',
      '&:hover': {
        color: 'darkorchid'
      }
    }}
    {...props}
  />
);

This transforms to:

import { jsx as ___EmotionJSX } from '@emotion/react';

const Link = props =>
  ___EmotionJSX(
    'a',
    {
      css: {
        color: 'hotpink',
        '&:hover': {
          color: 'darkorchid'
        }
      },
      ...props
    }
  );

Capabilities

Preset Configuration

The main preset function that configures Babel plugins for CSS-in-JS functionality.

/**
 * Babel preset factory function that configures CSS-in-JS transformation
 * @param api - Babel API object (provided by Babel)
 * @param options - Configuration options object
 * @returns Babel preset configuration with plugins array
 */
function preset(api: any, options?: PresetOptions): BabelPresetConfig;

interface PresetOptions {
  /** Custom JSX pragma (passed to @babel/plugin-transform-react-jsx) */
  pragma?: string;
  /** Enable source maps in emotion plugin */
  sourceMap?: boolean; 
  /** Automatic labeling mode for emotion plugin ('dev-only' | 'always' | 'never') */
  autoLabel?: string;
  /** Label format pattern for emotion plugin (e.g., '[local]', '[dirname]--[filename]--[local]') */
  labelFormat?: string;
  /** Import mapping configuration for emotion plugin */
  importMap?: Record<string, any>;
  /** Additional options passed to @babel/plugin-transform-react-jsx */
  [key: string]: any;
}

interface BabelPresetConfig {
  plugins: Array<[any, any]>;
}

Usage Examples:

{
  "presets": [
    [
      "@emotion/babel-preset-css-prop",
      {
        "autoLabel": "dev-only",
        "labelFormat": "[local]",
        "sourceMap": true
      }
    ]
  ]
}

Error Handling

The preset throws an error if the deprecated runtime option is used:

// Throws Error if options.runtime is specified
// Error message: "The `runtime` option has been removed. If you want to configure `runtime: \"automatic\"`, replace `@emotion/babel-preset-css-prop` with `@babel/preset-react` and `@emotion/babel-plugin`. You can find out how to configure things properly here: https://emotion.sh/docs/css-prop#babel-preset"

Architecture

The preset internally combines three Babel plugins:

@emotion/babel-plugin-jsx-pragmatic: Configures JSX import pragmas
- Sets up import { jsx as ___EmotionJSX } from '@emotion/react'
@babel/plugin-transform-react-jsx: Transforms JSX syntax
- Uses ___EmotionJSX as the pragma instead of React.createElement
- Forwards preset options like pragma and other JSX transform options
@emotion/babel-plugin: Handles CSS-in-JS transformations
- Processes css prop with source maps and labels
- Enables cssPropOptimization: true for better performance
- Receives options like sourceMap, autoLabel, labelFormat, importMap

Compatibility Notes

Not compatible with @babel/plugin-transform-react-inline-elements
Requires classic JSX runtime (not automatic JSX runtime)
Must be placed after @babel/preset-react or @babel/preset-typescript in Babel config
Peer dependency: Requires @babel/core ^7.0.0

Configuration Examples

Basic Configuration:

{
  "presets": ["@emotion/babel-preset-css-prop"]
}

With Development Labels:

{
  "presets": [
    [
      "@emotion/babel-preset-css-prop",
      {
        "autoLabel": "dev-only",
        "labelFormat": "[local]"
      }
    ]
  ]
}

With All Options:

{
  "presets": [
    [
      "@emotion/babel-preset-css-prop",
      {
        "autoLabel": "dev-only",
        "labelFormat": "[dirname]--[filename]--[local]",
        "sourceMap": true,
        "useBuiltIns": false,
        "throwIfNamespace": true
      }
    ]
  ]
}