v6 to v7 Migration

Migrating from v6 to v7 in React Applications

The migration from v6 to v7 is a significant one, with many changes to the underlying architecture and the way that the system is configured. This guide will help you to understand the changes that have been made and how to migrate your existing code to the new version.

At a high level, the migration to v7 involves:

• Updating and installing new dependencies
• Migrating components to their new APIs
• Migrating icons and glyphs to their new APIs
• Updating the stylesheet references in your HTML
• Re-evaluating the design of your application
• Validating your application’s functionality, including testing
• Deploying your application

To ease the upgrade process, we have created a codemod that will automatically update your code to use the new APIs. This codemod will make the necessary changes to your code and help you to identify any issues that need to be addressed manually.

Package Versions

In DLS v6, there were some inconsistencies between DLS version and NPM semantic version. For example, @americanexpress/dls-react@^1.0.0 is a React implementation of the DLS v6 styles as defined in @americanexpress/dls@^6.0.0.

In DLS v7, all packages which implement DLS v7 styles will have the NPM semantic version ^7.x.x. This will make it clear which version of the DLS styles a given package is using.

See NPM’s documentation for more info on semantic versioning.

Package	DLS v6 NPM Semantic Version	DLS v7 NPM Semantic Version
@americanexpress/dls	^6.a.b	^7.x.y
@americanexpress/dls-react	^1.c.d	^7.x.y
@americanexpress/dls-icons	^1.e.f	^7.x.y

Run the DLS Codemod

The first step in migrating your application to v7 should be to run the DLS codemod. This will automatically update your code to use the new APIs and will help you to identify any issues that need to be addressed manually in your code. To run the codemod, execute the following command in the project you want to migrate:

1npx @americanexpress/dls-codemod@7

Then, follow the prompts in your terminal to complete the migration, specifying which source files you’d like to migrate and which transforms you’d like to run. We recommend executing all available transforms across all source files to ensure that your application is fully migrated.

Once the codemod has completed, you can review the changes that have been made and make any necessary adjustments to your code. If you experience any problems during the migration process, reach out to the DLS team for assistance.

Updating and Installing New Dependencies

The first step in migrating your application to v7 is to update and install the new dependencies that are required by the new version of the DLS.

Updating One App Dependencies

Manual

If you are using One App as your React framework, you may be required to update the @americanexpress/one-app-bundler dependency to the latest version. Recent versions of the One App bundler have been updated with important CSS bundling improvements and important security updates, which resolve quarantines related to Webpack 4. It is important that you update this dependency to the latest version to ensure that your application is secure and up-to-date (DLS v7 specifically requires at least @americanexpress/one-app-bundler@^7.0.6).

The upgrade from the v6 bundler to the v7 bundler is a straightforward upgrade — for more information, refer to the One App guide on upgrading the bundler.

Updating DLS Dependencies

Automatic

If you are using @americanexpress/dls-react or @americanexpress/dls-icons in your application, you will need to update these dependencies to the latest version. If you were previously using icons/glyphs imported from @americanexpress/dls-react without explicitly having @americanexpress/dls-icons installed, you must now install @americanexpress/dls-icons as a separate dependency - icons/glyphs are no longer included in @americanexpress/dls-react directly.

To install these dependencies, run the following command in your project:

1npm install @americanexpress/dls-react@7 @americanexpress/dls-icons@7

If you previously had @americanexpress/dls installed as an actual dependency in your project, in most cases you should be able to remove it - DLS components and styles come from using @americanexpress/dls-react and a DLS stylesheet reference in the head of your HTML file. If you have a specific use case that requires using @americanexpress/dls installed as a dependency, please reach out to the DLS team for guidance.

Migrating to the New APIs

The next step in migrating your application to v7 is to update your code to use the new APIs that have been introduced.

Migrating Components to Their New APIs

Automatic

Component APIs have changed across the board and will need to be updated. This step is best completed by running the DLS codemod, as it will automatically update your components to use the new APIs and will help you to identify any issues that need to be addressed manually. To view a complete list of the changes that the DLS Codemod will make to each component, including potential manual changes, refer to the individual component transform documentation pages.

Migrating Icons and Glyphs to Their New APIs

Automatic

In DLS v7, icons and glyphs are no longer included in @americanexpress/dls-react directly. Instead, they are provided by the @americanexpress/dls-icons package. If you were previously using icons/glyphs imported from @americanexpress/dls-react, you must now install @americanexpress/dls-icons as a separate dependency and update your imports accordingly.

Additionally, updates have been made to the names of icons, glyphs have been replaced with equivalent icons, and new props have been added to icons. The DLS codemod will automatically update your code to use the new APIs and will help you to identify any issues that need to be addressed manually. For more information, check out the transform documentation for the icons transform and the glyphs transform.

Updating the Stylesheet References in Your HTML

Manual

The dls-core stylesheet should be included in your application to ensure that your application has the proper grid, spacing, color, and support for dark mode and surfaces. The stylesheet URL is https://www.aexp-static.com/cdaas/dls/packages/@americanexpress/dls/<version>/stylesheets/dls-core.min.css, where <version> is the DLS v7 version and min indicates that the CSS file is minified.

If using One App or React, you should use React Helmet to include the dls-core stylesheet in your application.

If not using One App or React, you can alternatively include in the <head> of the application:

1<link
2  rel="stylesheet"
3  href="https://www.aexp-static.com/cdaas/dls/packages/@americanexpress/dls/7.12.0/stylesheets/dls-core.min.css"
4/>

Updating Custom Styles

Manual & Automatic

The DLS v7 stylesheet is fully backwards compatible with DLS v6, so any uses of utility classes will continue to work as expected. However, there are two important notes about custom styles to consider:

1. The theme prop has been removed. The Codemod will attempt to automatically convert the theme prop to equivalent DLS utility classes. However, not all styles will be automatically migrated. To re-introduce custom styles that were previously defined using the theme prop, you can use the new className prop to apply custom styles to components, either using DLS utility classes or using custom css.
2. Existing v6 color utility classes are not compatible with surfaces/dark mode. These utility classes will need to be migrated to the new tokenized utility classes, which are mode and surface compatible. For more information, see the implementation section of the docs for Design Tokens and Dark Mode.

Re-evaluating the Design of Your Application

DLS v7 is a complete design overhaul. While the Codemod will update your components to use the new APIs, it is important to review the design of your application to ensure that it is consistent with the new design guidelines. This may involve updating the layout, colors, typography, or adding new components to your application.

This is a good opportunity to communicate with your product and design teams to see what changes they would like to make to the application to make it feel more modern and up-to-date.

Validating Your Application’s Functionality, Including Testing

Once you’ve updated to the new APIs, added the new stylesheet, and reviewed the design of your application, it’s important to validate that your application’s functionality, including any new functionality, is still working as expected. This may involve running your application locally, testing it in different browsers and devices, and updating unit tests to ensure that it is functional, responsive, and accessible.

Deploying your Application

Once you’ve validated your application locally (E0), it’s time to deploy your application and begin evaluating it across your deployment environments (E1, E2, E3). Our general recommendation is to ensure that your entire application is upgraded to DLS v7 before deploying to production, as this will result in the best experience for users. For One App developers, this means upgrading all child modules for a given root module before deploying.

Conclusion

Congratulations! You have successfully migrated your application to v7 of the DLS. If you have any questions or need further assistance, please reach out to the DLS team for help. We are here to support you in your migration journey and to help you to take full advantage of the new features and improvements that have been introduced in the new version of the DLS.