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

Global JSX Transformations

Name: tessl/npm-swc--plugin-emotion
Author: tessl

Transformations for emotion Global JSX components, converting styles attributes to optimized array format with source map integration.

Capabilities

Global JSX Component Transformation

Transforms emotion Global JSX components by optimizing the styles attribute format.

/**
 * Transforms Global JSX component styles attributes
 * Input: <Global styles={cssValue} />
 * Output: <Global styles={[cssValue, "sourcemap"]} />
 */

Transformation Examples:

// Input
import { Global, css } from "@emotion/react";

const globalStyles = css`
  body { margin: 0; padding: 0; }
  * { box-sizing: border-box; }
`;

function App() {
  return (
    <div>
      <Global styles={globalStyles} />
      <main>Content</main>
    </div>
  );
}

// Output (with sourceMap: true)
function App() {
  return (
    <div>
      <Global styles={[
        globalStyles,
        "/*# sourceMappingURL=data:application/json;base64,... */"
      ]} />
      <main>Content</main>
    </div>
  );
}

Global Literal Styles Transformation

Transforms Global components with inline literal styles.

/**
 * Transforms Global with literal CSS styles
 * Input: <Global styles="css-string" />
 * Output: <Global styles={["css-string", "sourcemap"]} />
 */

Literal Styles Examples:

// Input with string literal
function ResetStyles() {
  return (
    <Global styles="body { margin: 0; } html { font-family: sans-serif; }" />
  );
}

// Output
function ResetStyles() {
  return (
    <Global styles={[
      "body { margin: 0; } html { font-family: sans-serif; }",
      "/*# sourceMappingURL=... */"
    ]} />
  );
}

Global Expression Container Transformation

Transforms Global components with JSX expression container styles.

/**
 * Transforms Global with JSX expression containers
 * Input: <Global styles={expression} />
 * Output: <Global styles={[expression, "sourcemap"]} />
 */

Expression Container Examples:

// Input with expression container
import { Global } from "@emotion/react";

const themeColors = {
  primary: '#007bff',
  secondary: '#6c757d'
};

function ThemedApp() {
  return (
    <div>
      <Global styles={{
        body: {
          backgroundColor: themeColors.primary,
          color: 'white'
        }
      }} />
      <main>Content</main>
    </div>
  );
}

// Output
function ThemedApp() {
  return (
    <div>
      <Global styles={[
        {
          body: {
            backgroundColor: themeColors.primary,
            color: 'white'
          }
        },
        "/*# sourceMappingURL=... */"
      ]} />
      <main>Content</main>
    </div>
  );
}

Global Array Styles Handling

Handles Global components that already have array-format styles.

/**
 * Handles existing array-format styles by appending source map
 * Input: <Global styles={[style1, style2]} />
 * Output: <Global styles={[style1, style2, "sourcemap"]} />
 */

Array Styles Examples:

// Input with existing array
import { Global, css } from "@emotion/react";

const resetStyles = css`* { margin: 0; padding: 0; }`;
const fontStyles = css`body { font-family: Arial, sans-serif; }`;

function App() {
  return (
    <Global styles={[resetStyles, fontStyles]} />
  );
}

// Output
function App() {
  return (
    <Global styles={[
      resetStyles, 
      fontStyles,
      "/*# sourceMappingURL=... */"
    ]} />
  );
}

Namespace Global Transformation

Transforms Global components imported via namespace imports.

/**
 * Transforms Global from namespace imports
 * Input: <emotion.Global styles={value} />
 * Output: <emotion.Global styles={[value, "sourcemap"]} />
 */

Namespace Import Examples:

// Input with namespace import
import * as emotion from "@emotion/react";

function Layout() {
  return (
    <div>
      <emotion.Global styles={emotion.css`
        html, body { height: 100%; }
        #root { min-height: 100%; }
      `} />
      <header>Header</header>
    </div>
  );
}

// Output
function Layout() {
  return (
    <div>
      <emotion.Global styles={[
        emotion.css`
          html, body { height: 100%; }
          #root { min-height: 100%; }
        `,
        "/*# sourceMappingURL=... */"
      ]} />
      <header>Header</header>
    </div>
  );
}

Global JSX Member Expression Transformation

Transforms Global components accessed via member expressions.

/**
 * Transforms Global via JSX member expressions
 * Handles patterns like <namespace.Global styles={...} />
 */

Member Expression Examples:

// Input with member expression
import * as Emotion from "@emotion/react";

const Layout = () => {
  return (
    <div>
      <Emotion.Global styles={Emotion.css`
        .app { padding: 20px; }
        .container { max-width: 1200px; margin: 0 auto; }
      `} />
      <div className="app">
        <div className="container">Content</div>
      </div>
    </div>
  );
};

// Output
const Layout = () => {
  return (
    <div>
      <Emotion.Global styles={[
        Emotion.css`
          .app { padding: 20px; }
          .container { max-width: 1200px; margin: 0 auto; }
        `,
        "/*# sourceMappingURL=... */"
      ]} />
      <div className="app">
        <div className="container">Content</div>
      </div>
    </div>
  );
};

Global Source Map Generation

Source map generation for Global JSX component transformations.

/**
 * Source maps for Global transformations map to JSX element positions
 * Enables debugging of global styles within React DevTools
 * Only generated when sourceMap option is enabled
 */

Source Map Details:

// Input at line 45, column 8
<Global styles={globalCSS} />

// Generated source map data points to:
// - file: "src/App.tsx"  
// - line: 45
// - column: 8
// - element: JSX opening element position

Global Transformation Conditions

The plugin only transforms Global components when specific conditions are met.

/**
 * Transformation conditions for Global components:
 * 1. Global must be imported from @emotion/react
 * 2. Must have a styles attribute/prop
 * 3. sourceMap option must be enabled for source map injection
 * 4. Plugin must recognize the import pattern
 */

Conditional Examples:

// ✓ Transformed - Named import from @emotion/react
import { Global } from "@emotion/react";
<Global styles={css`body { margin: 0; }`} />

// ✓ Transformed - Namespace import from @emotion/react  
import * as emotion from "@emotion/react";
<emotion.Global styles={emotion.css`padding: 0;`} />

// ✗ Not transformed - Wrong import source
import { Global } from "some-other-library";
<Global styles={css`margin: 0;`} />

// ✗ Not transformed - No styles attribute
import { Global } from "@emotion/react";
<Global className="global-component" />

// ✗ Not transformed - sourceMap disabled
// (with plugin config: { sourceMap: false })
<Global styles={css`padding: 16px;`} />

Supported Global Import Patterns

The plugin recognizes these import patterns for Global transformation:

/**
 * Supported Global import patterns:
 * - Named imports: import { Global } from "@emotion/react"
 * - Namespace imports: import * as emotion from "@emotion/react"
 * - Mixed imports: import { Global, css } from "@emotion/react"
 */

Import Pattern Examples:

// Named import
import { Global } from "@emotion/react";
<Global styles={someStyles} />; // ✓ Transformed

// Namespace import
import * as emotion from "@emotion/react";  
<emotion.Global styles={someStyles} />; // ✓ Transformed

// Mixed import
import { Global, css } from "@emotion/react";
<Global styles={css`margin: 0;`} />; // ✓ Transformed

Error Handling in Global Transformations

The plugin handles various edge cases gracefully during Global transformations.

/**
 * Error handling scenarios:
 * - Missing styles attribute: No transformation
 * - Invalid JSX structure: Original structure preserved
 * - Source map generation failure: Styles transformed without source map
 * - Unrecognized import patterns: No transformation applied
 */

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

tessl/npm-swc--plugin-emotion