Skip to main content

Migration Guide

Guide for migrating to new versions of WorkPayCore Frontend utilities and best practices for upgrading existing code.

Overview​

This guide helps developers migrate from older versions of utilities to newer implementations, ensuring smooth transitions and minimal breaking changes.

Version History​

v2.0.0 - Latest​

Breaking Changes​

  • Axios Configuration: Moved from libraries to core-utils
  • EOR Portal Integration: New parameter structure
  • Authentication: Updated token management system

Migration Steps​

  1. Update Imports:

    // Old
    import { httpV2 } from '@/libraries/axios-config';

    // New
    import { httpV2 } from '@/api/axios';

  2. EOR Portal Parameters:

    // Old
    const eorParams = { company_id: id };

    // New
    const eorParams = getDefaultEorPortalParams();

  3. Feature Flag Helpers:

    // Old
    import { checkFeatureFlag } from '@/utils/feature-flags';

    // New
    import { isFeatureFlagEnabled } from '@/utils/helpers/feature-flag';

v1.5.0​

New Features​

  • Enhanced phone number validation
  • Country helpers with timezone support
  • HR payroll metrics formatting

Migration Steps​

  1. Phone Number Validation:

    // Old
    const isValid = validatePhone(number);

    // New
    const validation = validatePhoneNumber(number, 'US');
    const isValid = validation.isValid;

  2. Country Data:

    // Old
    const country = getCountry('US');

    // New
    const country = getCountryByCode('US');

v1.0.0​

Initial Release​

  • Core utilities for string, number, and object manipulation
  • Basic authentication helpers
  • Pagination and browser utilities

Common Migration Patterns​

1. Import Path Updates​

Most utilities have moved to more organized directories:

// Old paths
import { helper } from '@/utils/helpers';
import { config } from '@/config/axios';

// New paths
import { helper } from '@/utils/helpers/general-helpers';
import { httpV2 } from '@/api/axios';

2. Function Signature Changes​

Some functions have updated signatures for better type safety:

// Old
const result = formatCurrency(amount);

// New
const result = formatCurrency(amount, 'USD', { showSymbol: true });

Automated Migration Tools​

Testing Migration​

  1. Update Test Imports:

    // Update all test files to use new import paths
    import { validatePhoneNumber } from '@/utils/helpers/phone-number';

  2. Mock Updates:

    // Update mocks for new function signatures
    jest.mock('@/utils/helpers/analytics', () => ({
      analyticsTrackEvent: jest.fn(),
    }));

  3. Type Checking:

    # Run type checking after migration
    npm run type-check

Getting Help​

  • Check the Best Practices guide
  • Review individual utility documentation
  • Contact the frontend team for migration assistance

Rollback Instructions​

If you need to rollback a migration:

  1. Revert Package Version:

    npm install @workpay/frontend-utils@1.5.0

  2. Restore Old Imports:

    git checkout HEAD~1 -- src/utils/

  3. Update Configuration:

    # Restore old environment variables
    cp .env.backup .env

For specific utility migration guides, see the individual documentation pages.