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 nowButton
. To facilitate the migration, you can use aliasing likeimport { Button as QtmButton } from '@qtm/react2
. - No More Web-Components Dependency: The
@qtm/react2
package no longer has dependencies on web-components.
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.