Skip to main content
🏠Getting StartedUpgrading to Quantum v2.0.0Version: Next

Upgrading to Quantum v2.0.0

Overview

This section provides a detailed guide for migrating your project from Quantum Design System v1 to v2. The primary change in this migration involves moving from Stencil-based React components to native React components, along with the removal of the "Qtm" prefix from component names in the @qtm/react2 library.

Key Change in v2

Native React Support and Component Renaming

  • @qtm/react2: Introduced a new library of native React components. This is separate from the original @qtm/react which is implemented with Stencil. The decision to remove Stencil for the React package was due to numerous issues with DOM manipulation, especially with dynamic changes.
  • Component Renaming: The "Qtm" prefix has been removed from component names in the @qtm/react2 library. For example, QtmButton is now Button. To facilitate the migration, you can use aliasing like import { Button as QtmButton } from '@qtm/react2.
  • No More Web-Components Dependency: The @qtm/react2 package no longer has dependencies on web-components.
info

Start using Quantum @qtm/react2 Storybook implementation, offering fully React-based components library.

Migration Steps

Step 1: Update Dependencies

Update your project's dependencies to the latest versions of Quantum Design System packages. Modify your package.json to reflect the new package names and versions.

Before:

"dependencies": {
"@qtm/react": "^1.0.0",
"@qtm/web-components": "^1.0.0",
"@qtm/tailwind-preset": "^1.0.0",
"@qtm/tokens": "^1.0.0",
// other dependencies
}

After:

"dependencies": {
"@qtm/react2": "^2.0.0-beta.0",
"@qtm/tailwind-preset": "^2.0.0-beta.0",
"@qtm/tokens": "^2.0.0-beta.0",
// other dependencies
}

Run the following command to update your dependencies:

npm install

Step 2: Refactor Component Imports

Refactor your component imports to use the new @qtm/react2 package for native React components and update the component names.

Before:

import { QtmButton } from '@qtm/react';

After:

import { Button as QtmButton } from '@qtm/react2';

Alternatively, you can directly use the new component names without aliasing:

import { Button } from '@qtm/react2';

function App() {
return <Button>Submit</Button>;
}

export default App;

Step 3: Update CSS

Ensure your CSS references are updated to include the necessary styles from the new @qtm/react2 package.

Before:

@import '@qtm/web-components/dist/web-components/web-components.css';

After:

@import '@qtm/react2/dist/style.css';

Step 4: Adjust for API Changes

Review the component API changes and adjust your code accordingly. This might include updating props, event handlers, and other component-specific configurations.

Step 5: Test Your Application

Thoroughly test your application to ensure all components are rendering correctly and there are no regressions. Pay special attention to styles, functionality, and performance.

Contributions and Issues

If you encounter any issues during the migration process, please open an issue or submit a pull request with your suggested changes. For contribution guidelines, consult this documentation.