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.