Orbiter to Hopper Codemod

This codemod automates the migration of components from Orbiter to the Hopper design system.

Examples

Before Migration

import { Div } from "@workleap/orbiter-ui";

export function App() {
  return <Div width="100px"/>;
}

After Migration

import { Div } from "@hopper-ui/components";

export function App() {
  return <Div UNSAFE_width="100px"/>;
}

Usage Guide

Running Migrations

Migrate All Components

npx codemod workleap/orbiter-to-hopper

Or explicitly specify all components:

npx codemod workleap/orbiter-to-hopper -c all

Migrate Layout Components Only

Migrate layout related components only (Flex, Grid, Div, ...). You can see the list in layoutComponents.ts file.

npx codemod workleap/orbiter-to-hopper -c layout

Migrate a Single Component Only

npx codemod workleap/orbiter-to-hopper -c Div

Target a Specific Path

Run the command in the desire path or pass the target path with the -t argument.

npx codemod workleap/orbiter-to-hopper -t /app/users

Additional Options

For more configuration options, refer to the Codemod CLI options documentation.

Analyzing Component Usage

To generate a report of Orbiter component usage patterns, use the following command:

npx codemod workleap/orbiter-to-hopper -a orbiter-usage.json -n 1

⚠️ Important: The -n 1 flag limits execution to a single thread, which ensures accurate output collection.

This command generates a JSON file (orbiter-usage.json) containing usage statistics ordered by frequency. The output format prioritizes frequently used components and their properties:

{
  "Div": {
    "usage": 5,
    "props": {
      "backgroundColor": {
        "usage": 5,
        "values": [
          "\"neutral-weakest\"",
          "\"neutral-disabled\"",
          "style.backgroundColor"
        ]
      }
    }
  }
}

Contributing

Setup

1. First, install the codemod CLI globally.

2. Make your modifications to the codebase.

Publishing

To publish a new version:

pnpm publish

Local Testing

To test changes locally before publishing:

codemod --source /path/to/your/local/copy

[!TIP] To run the latest modifications, the cdmd_dist folder should not exist. If you use the pnpm deploy:codemod, this folder is getting deleted after each deployment automatically.

Simple Modifications

Modify the mappings.ts for simple mappings. Just add the components and props to map.

{
  sourcePackage: "@workleap/orbiter-ui",
  targetPackage: "@hopper-ui/components",
  components: {
    Span: "Span",
    Text: "Text",    
    Div: {
      to: "Div",
      props: {
        mappings: {
          width: "UNSAFE_width",
          height: "UNSAFE_height",
          maxWidth: (oldValue) => {
              return {
                  to: "UNSAFE_maxWidth"
                  value: oldValue,
              }
          }
        }
        additions: { //add these prop/values to the mapped component
          "display" : "block"
        }
      },
    },
  },
};