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 section to learn more about the purpose of this file
   • Example structure:

     // 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

   # 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:

     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

   # 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

# 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
• link - Migrate Link 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:

<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