Package Renaming Rule (Emotion 11 Codemods)

The pkg-renaming rule automates migration of package names from Emotion 10 to Emotion 11, handling the comprehensive package restructuring and export changes.

Capabilities

Package Name Migration

Automatically migrates package imports from Emotion 10 naming to Emotion 11 structure.

/**
 * Internal rule for Emotion 11 package migration codemods
 * Handles comprehensive package renaming and export restructuring
 */
interface PkgRenamingRuleConfig {
  name: "pkg-renaming";
  fixable: true;
  schema: never[]; // No configuration options - internal rule
  messages: {
    renamePackage: string;
    exportChange: string;
    emotionTheming: string;
  };
}

Migration Mappings

The rule handles these package migrations:

interface PackageMappings {
  // Core emotion packages
  "@emotion/core": "@emotion/react";
  "emotion": "@emotion/css";
  "emotion/macro": "@emotion/css/macro";
  
  // Styled components
  "@emotion/styled-base": "@emotion/styled/base";
  
  // Testing and tooling
  "jest-emotion": "@emotion/jest";
  "babel-plugin-emotion": "@emotion/babel-plugin";
  "eslint-plugin-emotion": "@emotion/eslint-plugin";
  
  // Server-side rendering
  "create-emotion-server": "@emotion/server/create-instance";
  "create-emotion": "@emotion/css/create-instance";
  "emotion-server": "@emotion/server";
  
  // Theming
  "emotion-theming": "@emotion/react";
}

Usage Examples

Basic Configuration

{
  "rules": {
    "@emotion/pkg-renaming": "error"
  }
}

Package Renaming Examples

Simple package renames:

// Before
import { css } from '@emotion/core';
import styled from '@emotion/styled-base';

// After (auto-fixed)
import { css } from '@emotion/react';  
import styled from '@emotion/styled/base';

Complex migration scenarios:

// Before
import emotion from 'emotion';
import { ThemeProvider } from 'emotion-theming';

// After (auto-fixed)
import emotion from '@emotion/css';
import { ThemeProvider } from '@emotion/react';

Export Structure Changes

The rule handles export restructuring for packages that changed their export patterns:

Default to named export migration:

// Before
import css from '@emotion/css';

// After (auto-fixed)  
import { css } from '@emotion/react';

With custom alias:

// Before
import emotionCss from '@emotion/css';

// After (auto-fixed)
import { css as emotionCss } from '@emotion/react';

Error Messages

• renamePackage: "{{ beforeName }} has been renamed to {{ afterName }}, please import it from {{ afterName }} instead"
• exportChange: "The default export of "{{ name }}" in Emotion 10 has been moved to a named export, `css`, from "{{ replacement }}" in Emotion 11, please import it from "{{ replacement }}""
• emotionTheming: ""emotion-theming" has been moved into "@emotion/react", please import its exports from "@emotion/react""

Migration Details

Core Package Changes

1. @emotion/core → @emotion/react

   • Primary emotion package for React applications
   • Includes jsx, css, and other React-specific features

2. emotion → @emotion/css

   • Vanilla emotion for non-React usage
   • Maintains the same API but new package name

3. emotion-theming → @emotion/react

   • Theming functionality moved into main React package
   • No separate theming package needed

Export Changes

@emotion/css and @emotion/css/macro:

• Default export in v10 → Named css export in v11
• Automatically converts import patterns
• Preserves custom aliases properly

emotion-theming integration:

• All exports now available from @emotion/react
• ThemeProvider, useTheme, etc. included

Server-Side Rendering

// Before
import createEmotionServer from 'emotion-server';
import createEmotion from 'create-emotion';

// After (auto-fixed)
import createEmotionServer from '@emotion/server';  
import createEmotion from '@emotion/css/create-instance';

Complete Migration Example

Before (Emotion 10):

import styled from '@emotion/styled-base';
import { css, keyframes } from '@emotion/core';
import { ThemeProvider, useTheme } from 'emotion-theming';
import emotionCss from 'emotion';
import { matchers } from 'jest-emotion';

After (auto-fixed to Emotion 11):

import styled from '@emotion/styled/base';
import { css, keyframes } from '@emotion/react';
import { ThemeProvider, useTheme } from '@emotion/react';
import { css as emotionCss } from '@emotion/react';
import { matchers } from '@emotion/jest';

When Not To Use

Disable this rule if:

• You're not migrating from Emotion 10 to 11
• You need to maintain Emotion 10 compatibility
• You're using a gradual migration strategy
• Custom build processes handle the package mapping

Migration Strategy

1. Enable the rule: Add to your ESLint configuration
2. Run ESLint with --fix: Auto-fix most migration issues
3. Review changes: Verify all imports work correctly
4. Update dependencies: Install Emotion 11 packages
5. Test thoroughly: Ensure all functionality works as expected

This rule is designed as a comprehensive codemod for the Emotion 10 to 11 migration path.