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

styled-transformations.mddocs/

Styled Component Transformations

Transformations for emotion styled component calls, including target class generation, automatic labeling, and template literal optimization.

Capabilities

Styled Template Literal Transformation

Transforms styled component template literals into optimized function calls with target classes.

/**
 * Transforms styled template literals
 * Input: styled.div`styles...`
 * Output: styled("div", { target: "e1abc123", label: "context" })("minified-styles", "sourcemap")
 */

Transformation Examples:

// Input
import styled from "@emotion/styled";

const Button = styled.button`
  background: blue;
  color: white;
  padding: 8px 16px;
`;

// Output (with autoLabel: "always")
const Button = styled("button", { 
  target: "e1a2b3c4", 
  label: "Button" 
})(
  "background:blue;color:white;padding:8px 16px;",
  "/*# sourceMappingURL=... */"
);

Styled Function Call Transformation

Transforms styled function calls with element selectors.

/**
 * Transforms styled function calls
 * Input: styled('div')`styles...`
 * Output: styled("div", { target: "e1abc123", label: "context" })("minified-styles")
 */

Transformation Examples:

// Input
import styled from "@emotion/styled";

const Container = styled('div')`
  display: flex;
  flex-direction: column;
`;

// Output
const Container = styled("div", {
  target: "e5f6g7h8",
  label: "Container"
})(
  "display:flex;flex-direction:column;"
);

Styled Object Syntax Transformation

Transforms styled components with object syntax.

/**
 * Transforms styled components with object styles
 * Input: styled('div')({ styles })
 * Output: styled("div", { target: "e1abc123", label: "context" })({ styles }, "sourcemap")
 */

Transformation Examples:

// Input
import styled from "@emotion/styled";

const Card = styled('div')({
  border: '1px solid #ccc',
  borderRadius: '4px',
  padding: '16px'
});

// Output
const Card = styled("div", {
  target: "e9a8b7c6", 
  label: "Card"
})({
  border: '1px solid #ccc',
  borderRadius: '4px', 
  padding: '16px'
});

Target Class Generation

Generates stable, unique target class names for styled components.

/**
 * Target class generation creates unique identifiers
 * Format: "e" + base36(fileHash) + incrementalCounter
 * Provides stable class names for CSS debugging and testing
 */

Target Class Examples:

// File: src/components/Button.tsx (hash: 123456)
const PrimaryButton = styled.button`color: blue;`;
// Target: "e3g3jy0"

const SecondaryButton = styled.button`color: gray;`;  
// Target: "e3g3jy1"

// File: src/components/Card.tsx (hash: 789012)
const CardWrapper = styled.div`padding: 16px;`;
// Target: "e5s5lm0"

Styled Label Generation

Automatic label generation for styled components based on variable names and context.

/**
 * Label generation for styled components
 * Uses variable names, component names, and class contexts
 * Sanitizes labels by replacing invalid CSS characters
 */

Label Context Examples:

// Variable assignment context
const HeaderComponent = styled.h1`font-size: 24px;`;
// Label: "HeaderComponent"

// Object property context
const components = {
  sidebar: styled.aside`width: 200px;`,
  content: styled.main`flex: 1;`
};
// Labels: "sidebar", "content"

// Class property context
class Layout {
  static Container = styled.div`max-width: 1200px;`;
  // Label: "Container"
}

// Function context
function createStyledButton() {
  const StyledButton = styled.button`padding: 8px;`;
  // Label: "StyledButton"
  return StyledButton;
}

Complex Styled Transformations

Handles complex styled component patterns including conditional styles and composition.

/**
 * Complex styled transformations preserve logic and interpolations
 * Template literal interpolations become function call arguments
 * Conditional styling and props are maintained
 */

Complex Examples:

// Input with props and interpolation
const Button = styled.button`
  background: ${props => props.primary ? 'blue' : 'gray'};
  padding: ${({ size }) => size === 'large' ? '12px 24px' : '6px 12px'};
  opacity: 0.8;
`;

// Output
const Button = styled("button", {
  target: "e1a2b3c4",
  label: "Button"
})(
  "background:",
  props => props.primary ? 'blue' : 'gray',
  ";padding:",
  ({ size }) => size === 'large' ? '12px 24px' : '6px 12px',
  ";opacity:0.8;"
);

// Input with composition
const BaseButton = styled.button`padding: 8px;`;
const RedButton = styled(BaseButton)`color: red;`;

// Output  
const BaseButton = styled("button", {
  target: "e5f6g7h8",
  label: "BaseButton"
})("padding:8px;");

const RedButton = styled(BaseButton, {
  target: "e9a8b7c6",
  label: "RedButton"
})("color:red;");

Styled Component Source Maps

Source map generation for styled component template literals.

/**
 * Source maps for styled components map back to template literal positions
 * Enables debugging of transformed CSS within styled components
 * Generated only when sourceMap option is enabled
 */

Source Map Example:

// Input at line 25, column 30
const Header = styled.h1`
  font-size: 32px;
  color: #333;
`;

// Output with source map
const Header = styled("h1", {
  target: "e1b2c3d4",
  label: "Header"
})(
  "font-size:32px;color:#333;",
  "/*# sourceMappingURL=data:application/json;base64,... */"
);

Supported Styled Import Patterns

The plugin recognizes these import patterns for styled transformation:

/**
 * Supported styled import patterns:
 * - Default imports: import styled from "@emotion/styled"
 * - Named imports with alias: import { default as styled } from "@emotion/styled"  
 * - CommonJS: const styled = require("@emotion/styled")
 */

Import Pattern Examples:

// Default import
import styled from "@emotion/styled";
const Button = styled.button`color: blue;`; // ✓ Transformed

// Named import with alias
import { default as styled } from "@emotion/styled";
const Card = styled.div`padding: 16px;`; // ✓ Transformed

// CommonJS
const styled = require("@emotion/styled");
const Header = styled.h1`font-size: 24px;`; // ✓ Transformed

Styled Component Element Types

The plugin supports all HTML element types and custom components.

/**
 * Supported element patterns:
 * - HTML elements: styled.div, styled.button, styled.input, etc.
 * - Function calls: styled('div'), styled('button'), etc.  
 * - Custom components: styled(MyComponent)
 */

Element Type Examples:

// HTML elements
const Div = styled.div`display: block;`;
const Button = styled.button`cursor: pointer;`;
const Input = styled.input`border: 1px solid #ccc;`;

// Function call syntax
const Section = styled('section')`margin: 16px;`;
const Article = styled('article')`padding: 24px;`;

// Custom component styling
const MyComponent = (props) => <div {...props} />;
const StyledMyComponent = styled(MyComponent)`
  background: white;
  border-radius: 8px;
`;

Error Handling in Styled Transformations

The plugin gracefully handles various edge cases in styled component usage.

/**
 * Error handling scenarios:
 * - Invalid element types: Skipped transformation
 * - Missing imports: No transformation applied
 * - Malformed template literals: Original structure preserved
 * - Complex interpolations: Maintained as-is in output
 */

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