Skip to main content

V0 to V1 Guide

This guide is intended for teams looking to upgrade from Abyss v0 to the latest release of Abyss.

Among the changes are some major architectural changes and updates, including consolidated packages, a new foundational UHC theme, new hooks and components, Figma integration, an upgraded CSS styling tool, and refactored form inputs and validation. We have also improved accessibility compliance, upgraded our application router, and made many performance updates across all areas.

When you install our newest package dependencies, you'll automatically be up to date with the latest version. Abyss takes care of maintaining a robust product development framework so your team can focus on shipping a better product faster.

Version overview​

With Abyss v1.0, we have consolidated the primary areas of application development into three main NPM packages - @uhg-abyss/web, @uhg-abyss/api, and @uhg-abyss/core.

  • @uhg-abyss/web represents the client-side packages, React components, hooks, and tools.
  • @uhg-abyss/api represents the server-side packages, including the GraphQL server, Express middleware, and other libraries.
  • @uhg-abyss/core includes the configurations for ESLint and Babel, which have been consolidated along with the dev and build scripts. This package will be shared with both client and server projects built on Abyss.

Component changes​

Some common UI components have changed for consistency. Below is a table comparing noticeable differences from legacy versions of Abyss to Abyss v1. This is a non-exhaustive list, and components that are not included could likely have styling updates.

Our Brand and Design teams have made strong headway to update our standards since v0. We recommend following theme defaults, but if it is necessary to maintain the exact same design for your product, external styling or theme overrides can be done.

Components unavailable​

The following components are not available in v1.0. Those marked "To Be Implemented" will be part of upcoming releases.

Various hooks are also now deprecated, particularly in relation to forms and styling. Hooks relating to Redux are no longer available.

Branding​

The Abyss Design System now supports branding at a foundational level, with complete UHC, UHG, and Optum themes.

A theme is comprised of several core parts that create the building blocks of the design system. See the Brand section of our docs site for brand colors, fonts and typography settings, icon libraries, and several brand-associated logos. Simply by using Abyss as a launch point for your project, you will be fully aligned with all enterprise digital brand standards and assets, with no additional setup required.

Design integration​

To help teams quickly build and adapt a beautiful user interface, we've streamlined design and development for the Abyss Design System. We're excited to announce the addition of a dedicated design team implementing best practices on components and tools for the Abyss Design System in Figma.

With this addition, your entire product team has the power to make updates and adjustments with ease, utilizing both developer docs and design guidelines that now live in one place. On each docs page, simply press the “View Design” button in the header that links directly to the ADS in Figma. Even more so now, design and development collaboration provides an on-brand, elevated, cohesive experience.

CSS/styling tools​

There are multiple approaches teams can take for styling. Styling can be supported inline with the css prop on components, which allows for targeting classes that we have mentioned in the integration tab of any docs page. While we do not explicitly support external stylesheets, teams who already use this approach can continue doing so by applying through a className.

These style customizations are described further on our Theming/styling documentation. However, our own components are built using the styled tool via Stitches.

Stitches​

We have updated our CSS-in-JS library from Styled Components to Stitches. CSS-in-JS libraries have significant advantages over traditional CSS strategies by leveraging reusable variables, functions, and static code analysis.

The Stitches API shares many similarities with Styled Components; however, only object literal syntax is supported. The main benefit of Stitches over all other React CSS strategies is that nearly all CSS is generated at build time rather than runtime. This avoids unnecessary prop interpolations during the render phase, which can add up quickly when building large applications with a dynamic, theme-driven design system.

For detailed examples, review the docs for the styled tool. To see a full migration guide, please read migrating from Styled Components to Stitches.

Note:

  • In a future release of Abyss, we will be switching from Stitches to Emotion.

Routing​

We base our routing off of react-router-dom. Check out their migration guide from v5 to v6, or our own routing overview.

  • router.push() should now be router.navigate()
  • If deploying on AWS look at this stack overflow post with deployment issues with routing
  • Use the baseRoute in .abyss/settings.json if needed
"baseRoute": "/YOURBASEPATH"

State management​

Redux is no longer built into any of our products. It can still be used alongside our products by any consuming team, but we also recommend using Zustand.

Forms refactor​

Our new forms integration is entirely built on top of the react-hook-form library. We have upgraded from the previous Redux implementation to a new FormProvider, which allows child form inputs to consume the form context and methods returned from the upgraded useForm hook. With the addition of useForm functionality, most of our hooks for form management have now been deprecated.

This means form components and their state management could be a large portion of a team's migration efforts. We have not only expanded the collection of form inputs that are supported, but we have also consulted with accessibility experts to create first-class WCAG compliant interactions.

Build​

Teams that are using AWS will need to use browser-static in .abyss/settings.json:

"buildType": "browser-static".

This is instead of the default browser-node.

Abyss Scripts migration guide​

This guide is to help migrate from the old @abyss/scripts package to the new @uhg-abyss/core package. If a team is looking to use Parcels, see our guides for additional information. It is recommended to integrate Parcels by using Path One.

Path one​

Lift and shift the application into a new create-abyss-app

  • This will provide a more up-to-date foundation that will improve development and compatibility in the long run.
  • You can leverage additional Abyss tools like API and Parcels.

1. Create a new Abyss application

2. Bring over the old codebase

  • When bringing over the code, start small and fix errors as they appear.

3. Migrate imports from @abyss/ui web components to @uhg-abyss/web components

  • You can still use the old @abyss/ui, but you may encounter issues. (Support for @abyss/ui has ended)
  • When installing the old @abyss/ui, you must force installation due to React version conflicts.

Notes:

  • @uhg-abyss/web only supports react-router-dom v6.
  • @uhg-abyss/web does not support Redux; use Zustand instead.

Path two​

Migrate @abyss/scripts to @uhg-abyss/core

  • This option will keep you on an outdated tech stack.

1. Install packages

  • npm install @uhg-abyss/core
  • npm install typescript

2. Remove unused @abyss packages:

  • @abyss/babel-preset
  • @abyss/eslint-config
  • @abyss/scripts

3. Add prettier, eslintConfig, and bundleDependencies configs to package.json (You may have to update paths):

4. Add tsconfig.json file to the web app root (You may have to update the "include" path or add additional configurations):

5. Add next.config.js file to the web app root:

6. Add the pages/ directory to the web root:

7. Add the .abyss/ directory to the web root:

Future steps​

Now that your application/product has completed the migration to V1, here are next steps for planning and executing version updates to keep your product current and leverage new functionality released by Abyss. For more information on Abyss' release strategy, review our versioning guide.

Abyss deploys biweekly minor version releases to improve our products and address any defects. It is recommended to keep up with the latest release of Abyss for the best experience.

  • npm i @uhg-abyss/web@latest to upgrade to the latest release
  • npm i @uhg-abyss/web@1.XX.X to upgrade to a specific version of Abyss
Table of Contents