npm package: @planningcenter/tapestry-migration-cli
Description: CLI tool for Tapestry migrations
Author: Planning Center
Latest version: 3.2.0

# tapestry-migration-cli

A CLI tool to migrate Tapestry React components to Planning Center's Tapestry format.

## Usage

### Recommended Migration Order

For optimal results, migrate components in this order:

1. **Button components first**: `npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js`
2. **Link components second**: `npx @planningcenter/tapestry-migration-cli run link -p ./src/components`

This order ensures that Button components with navigation props are properly handled before Link components are migrated.

### Recommended Process

Consider these steps to safely migrate your components:

1. **Prepare your workspace** (recommended)
   - Commit your current changes or create a new branch
     - This allows you to easily review or revert changes if needed
   - Run your JS/TS code formatter (like Prettier) and commit any formatting changes if needed

2. **Create a theme file** (important for button migrations)
   - Create a CommonJS file called `theme.js` at the root of your project
   - Populate the file with your project's custom theme values using one of these methods:
     - **Option 1**: Copy/paste your project's custom theme values directly into the file (computed values should be ignored or set)
     - **Option 2**: Use `console.log()` to output the raw theme values in your application, then copy/paste the output from the browser console
   - See the [How It Works > Theme File](#theme-file) section to learn more about the purpose of this file
   - Example structure:
     ```javascript
     // theme.js
     exports.theme = {
       button: {
         themes: {
            primary: {
               outline: {
                  color: 'var(--t-text-color)',
                  hover: {
                     backgroundColor:
                     'var(--t-fill-color-button-neutral-outline-hover)',
                  },
                  stroke: 'var(--t-border-color-button-neutral)',
               },
               ...
            },
            ...
         }
         ...
     }
     ```

3. **Consider your scope**

   ```bash
   # Run the migration on a directory (button migrations require --js-theme)
   npx @planningcenter/tapestry-migration-cli run button -p ./src/javascript/components --js-theme ./theme.js

   # Or run the migration on a specific feature
   npx @planningcenter/tapestry-migration-cli run button -p ./src/features/checkout --js-theme ./theme.js

   # Or run migration on a specific page, view, or single file
   npx @planningcenter/tapestry-migration-cli run button -p ./src/components/ButtonExample.tsx --js-theme ./theme.js
   ```

   - Start with a manageable scope to understand the migration changes
   - For button migrations, include `--js-theme ./theme.js` to reference the theme file created in step 2
   - Use `--report-path` to generate a migration report for review (will default to MIGRATION_REPORT.md if not specified)

4. **Review the migration report and changed files**
   - Check the generated migration report (default: `MIGRATION_REPORT.md`)
   - Review the actual file changes using `git diff` or your editor
   - Understand what transformations were applied
     - Use `--verbose` to see `CHANGED` comments in your code indicating what was automatically migrated
   - **Alternative approach**: Run with `--verbose` and `--report-path` to generate a detailed migration report, save the report for planning purposes, then revert the changes (`git stash` or your editor's revert feature). You can re-run the migration later when ready to proceed:
     ```bash
     npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js --verbose --report-path ./migration-plan.md
     ```

5. **Discard or revert changes if needed**
   - If you're not ready to keep the changes, revert to discard the changes
   - You can always re-run the migration later when ready

6. **Review TODO comments**
   - Search for `TODO: tapestry-migration ([scope])` comments in your codebase

   ```bash
   # Example
   TODO: tapestry-migration (href)
   ```

   - These indicate props that need manual migration
   - Each TODO includes guidance on how to handle the unsupported prop

7. **Test your application**
   - Run your test suite
   - Manually verify migrated components work as expected
   - Pay special attention to any components with TODO comments

8. **Format your code**
   - Run your JS/TS code formatter (like Prettier) to ensure consistent code formatting

9. **Commit your changes**
   - Commit the automated migrations
   - Handle unsupported props in separate commits if needed
   - Once comfortable, migrate larger scopes incrementally

### Basic Commands

```bash
# Apply the migration changes (default behavior)
# Button migrations require --js-theme flag
npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js

# Run with verbose output
npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js --verbose

# Generate a migration report
npx @planningcenter/tapestry-migration-cli run button -p ./src/components --js-theme ./theme.js --report-path ./migration-report.md
```

## Available Components

- `button` - Migrate Button components
- `checkbox` - Migrate Checkbox components
- `link` - Migrate Link components
- `radio` - Migrate Radio components
- `toggle-switch` - Migrate ToggleSwitch components

## Required Arguments

- `-p, --path <path>` - **REQUIRED**: Path to the folder or file to migrate

## Optional Arguments

- `-d, --dry-run` - Preview changes without writing to files (default: writes changes)
- `-v, --verbose` - Show detailed output including automated changes
- `-j, --js-theme <path>` - Path to JavaScript theme file
- `-r, --report-path <path>` - Path for migration report (default: MIGRATION_REPORT.md)

## How It Works

The migration tool automatically transforms your components to match Planning Center's current Tapestry specifications. Most property and usage changes are handled automatically, including:

- Converting deprecated props to their modern equivalents
- Updating import statements and component references
- Adjusting prop names and values to match current API

### Theme File

The `theme.js` file (provided via `--js-theme`) is used to retrieve theme values during migration. These theme values are used to transform theme-based values into valid style props. When the migration tool encounters theme values in your components, it references this file to:

- Look up theme tokens and design values
- Convert theme-based styling to appropriate style prop values
- Ensure migrated components maintain visual consistency with your project's design system

The theme file should contain your project's complete theme structure, including all design tokens, colors, spacing, typography, and component-specific theme values that are used in your Tapestry React components.

### Unsupported Props

For properties that cannot be automatically migrated, the tool will:

1. **Keep the prop as-is** - The prop remains in your code but will not work with the new Tapestry component
2. **Add a TODO comment** - Flagging the prop for manual migration

Example of an unsupported prop comment:

```tsx
<Button
  /* TODO: tapestry-migration (propName): 'mediaQueries' is not supported, please migrate as needed.
   * It is recommended to use CSS media queries in a class that you apply to the component.
   */
  mediaQueries={{ mobile: { fontSize: 14 } }}
>
  Click me
</Button>
```

The comment includes guidance on how to handle the unsupported prop. Common recommendations include:

- Using CSS classes for styling instead of props
- Moving state-based styles (hover, focus, active) to CSS selectors
- Applying responsive styles through CSS media queries