Abyss V2 is finally here! We've worked hard to make the transition from V1 as smooth as possible.

Troubleshooting

If you encounter any issues during the migration process, please post your questions, problems, or findings on GitHub Discussions. This will allow all teams to see, respond to, and benefit from shared solutions. If someone has already asked a similar question, consider adding your insights or upvoting the existing discussion rather than creating a duplicate. This helps keep the conversation organized and makes it easier for everyone to find relevant information.

Go to the V1 → V2 Migration Discussion

Getting started

The steps listed below will guide you through the migration process.

1. Update to the latest V1 version

Make sure your project is running on the most recent V1 release before starting any migration steps. This will help minimize potential issues during the migration process.

2. Update React

In Abyss V2, we have updated our peer dependencies for React and React DOM. Notably, React 16 and 17 are no longer supported in Abyss V2. You should ensure your application is running on React 18 or 19 before migrating to Abyss V2.

// V1
- "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"

// V2
+ "react": "^18.0.0 || ^19.0.0"

3. Update React Native

In Abyss V2, we have updated our peer dependencies for React Native. Notably, React Native versions below 0.70 are no longer supported in Abyss V2. You should ensure your application is running on React Native 0.70 or higher before migrating to Abyss V2.

// V1
- "react-native": ">=0.64.0 <1"

// V2
+ "react-native": ">=0.70.0 <1"

4. Update component usage

It is strongly recommended to replacing your V1 components with their V2 counterparts before updating to Abyss V2. This way, when you move to V2, most of your components will only need to update the import names (e.g., V2Button → Button) instead of making all the prop changes at the same time.

Navigate to the Component Changes guide to see a list of components with breaking changes between V1 and V2, along with details on what has changed for each component.

Note: Some components have breaking changes between V1 and V2 without a V2 counterpart. Please refer to the Component Migration Notes section for more details.

Deprecations

Below is a list of tools, hooks, and components that are no longer available in Abyss V2.

Mobile Deprecations

V1 Abyss	Reason for Deprecation	Migration Path
Name:ArrowImport Path:@uhg-abyss/mobile/ui/Arrow	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:BulletsImport Path:@uhg-abyss/mobile/ui/Bullets	Doesn't align with the Abyss Design system	Nested internally for Carousel.
Name:CellCreatorImport Path:@uhg-abyss/mobile/ui/CellGroup	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:ElevationImport Path:@uhg-abyss/mobile/ui/Elevation	elevation() function was created to be placed inside the style prop	Move to @uhg-abyss/mobile/tools/elevation as a replacement.
Name:FABImport Path:@uhg-abyss/mobile/ui/FAB	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:IconMaterialImport Path:@uhg-abyss/mobile/ui/IconMaterial	Google has deprecated the Material Icons library and instead moved to a font based icon library.	Move to @uhg-abyss/mobile/ui/IconSymbol as a replacement.
Name:LagoonProviderImport Path:@uhg-abyss/mobile/ui/LagoonProvider	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.
Name:NibGroupImport Path:@uhg-abyss/mobile/ui/NibGroup	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:OverlayImport Path:@uhg-abyss/mobile/ui/Overlay	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:ScrollWheelImport Path:@uhg-abyss/mobile/ui/ScrollWheel	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:SearchBarImport Path:@uhg-abyss/mobile/ui/SearchBar	Doesn't align with the Abyss Design system	Pull in the code directly. Build your own component. Find an alternative component.
Name:LagoonFormImport Path:@uhg-abyss/utility/ui/LagoonForm	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.
Name:LagoonProviderImport Path:@uhg-abyss/utility/ui/LagoonProvider	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.
Name:MaelstromProviderImport Path:@uhg-abyss/utility/ui/MaelstromProvider	Maelstrom has been moved out of Abyss	Use alternative authentication methods
Name:lagoonImport Path:@uhg-abyss/utility/tools/lagoon	Lagoon is no longer included inside Abyss	Migrate to Lagoon SDK Lagoon components are now maintained independently of Abyss. Please refer to the Lagoon documentation and the Lagoon SDK implementation guide for migration assistance.

5. Update to the latest V2 version

Now that you've completed all preparation steps, you can update your project to use Abyss V2! Assuming that you have already replaced the deprecated V1 components with their recommended alternatives and switched all other components to their V2 counterparts, the migration to Abyss V2 should be straightforward.

Most of the remaining work should be import renaming rather than large-scale refactoring.

Remove the V2 prefix

We had released a number of V2 components in V1 with a V2 prefix to allow teams to start using them early and ease the migration process. Now that you are migrating to Abyss V2, you will need to remove the V2 prefix from these components in your imports. If you used an alias when importing, make sure to update that as well.

// Before
import { V2Button } from '@uhg-abyss/mobile/ui/Button';
import { V2Coachmark as Coachmark } from '@uhg-abyss/mobile/ui/Coachmark';

// After
import { Button } from '@uhg-abyss/mobile/ui/Button';
import { Coachmark } from '@uhg-abyss/mobile/ui/TextInput';

Updating components with breaking changes

As mentioned above some components have breaking changes between V1 and V2 without a V2 counterpart. Please update these components as needed based on the documentation found in the Component Changes section.

Example of a breaking change:

// V1 (1.X)
<Toast variant="success">
  This is the toast message content
</Toast>
// V2 (2.X)
<Toast variant="success" paragraph="This is the toast message content" />

UHG theme

The UHG theme has been removed in Abyss V2. To learn more about this change and how to migrate, please navigate to the UHG Theme documentation.

Theming

Some values in the overrides provided to the createTheme function have been removed to better align with brand design guidelines. If your project is using any of the following overrides, you will need to remove them.

deprecatedOptumIcons

The deprecatedOptumIcons override has been removed as the old Optum brand icons were not aligned with the Optum brand guidelines. Removing this override will ensure that your application uses the correct icons. No changes to your codebase are necessary beyond removing this override from your theme configuration.

Note that it was also possible to override a single BrandIcon with the useDeprecated prop. This prop is no longer supported in V2 and should be removed from all BrandIcon instances.

AI-Powered Migration Copilot

To help with component migration, we provide an AI context package that works with tools like GitHub Copilot, ChatGPT, or other AI code assistants. This context enables the AI to understand V1 to V2 changes and provide accurate migration assistance.

Using the Migration Copilot

• Download the this zip folder
• Extract the zip to your project root directory:

your-project-root/
├── abyss-migration-ai-context/
│   ├── ABYSS-MIGRATION-ASSISTANT.md
|   └── MigrationData.json
├── package.json
└── src/
    └── ... (your project files)

Add the context to your AI tool of choice (e.g., Copilot, ChatGPT, etc.) referencing the folder location.

Next you can prompt the AI tool with questions like:

Migrate this file from V1 to V2 of Abyss
Migrate the `Button` component from V1 to V2 of Abyss

Here is an example showcasing migrating a file from V1 to V2 of Abyss using the AI tool:

Migrate #file:Mobile.tsx from V1 to V2 of Abyss

Note: This is the result after using the one prompt above. No additional prompts were needed to get the correct result