Moving forward: On deprecating carbon-components and carbon-components-react
In the interest of making building with the Carbon Design System easier for developers, designers, and for ourselves, we introduced a number of quality-of-life improvements as part of our v11 release last year of which we’re really proud of. Among these changes, we released two brand new packages: @carbon/react and @carbon/styles. As we proposed in September of last year, these packages come to retire their predecessors: carbon-components-react and carbon-components, respectively.
The why
We had so many packages! Chances are if you were/are consuming our packages in v10, you installed all or a subset of the following:
carbon-componentscarbon-components-reactcarbon-icons@carbon/icons-react@carbon/colors@carbon/grid@carbon/layout@carbon/motion@carbon/themes@carbon/type@carbon/elements
In v11 for React-based projects you only need @carbon/react! You get everything out of the box without having to jump through hoops guessing which packages you need in order to get a DataTable to work. One package to rule them all! Simple, is simple, is simple. What is even better, is that you can find all needed guidance in our migration docs as you make your transition into v11.
You may still pick and choose from all the @carbon/* packages individually to fit your needs, of course, but for the most part, @carbon/react is what you’ll want to install when developing React-based applications using Carbon-React.
We also cleaned up a bunch of our styles by offloading all our components’ scss into a @carbon/styles package and setting it as a dependency for @carbon/react. This means, for most projects, you do not need to install @carbon/styles.
Here’s a closer look of how packages fit into each other in the Carbon Design ecosystem as of v11.
The Confusion
As a developer using the Carbon Design System, which package do I install? @carbon/react or carbon-components-react? what is carbon-components? WHY ARE THERE SO MANY PACKAGES?
Having these old packages available in conjunction with the new ones can prove to be a bit daunting and complicated, especially for developers that have never used the design system before. Which is why, with our handy-dandy packages in place, we are moving forward and saying goodbye to our old friends: we’re deprecating carbon-components and carbon-components-react.
Keep reading for further guidance on next steps if you’re still consuming these packages.
The now
We announced a while ago our intent to deprecate the old packages in favor of the newer ones, and we’re executing on that promise.
As of carbon-components-react v8.26.1 and carbon-components v11.26.1, you might see a deprecation warning come up on your screen.
That’s exactly what it is, a deprecation notice. We’re doing everything we can to get the word out there that these packages are going away, for good.
The future
We have recently released our official release schedule, which outlines active, maintenance and end of life period expectations for our current and upcoming packages. Within this release schedule, we are targeting an end of life date of September 2024 for Carbon Design System v10, which is currently under maintenance mode and will continue to be until it’s retirement next year.
While carbon-components and carbon-components-react have not yet been officially deprecated on npm, and an official deprecation date is not yet in place, it is our intention to deprecate these packages in the near future and would highly encourage migration to Carbon Design System v11 in the upcoming months before v10 reaches end of life in September 2024.
With this in mind, the Carbon Design System team is pushing for the adoption of our officially supported packages: @carbon/react, @carbon/styles, and @carbon/web-components.
React
For React-based projects that are currently still consuming carbon-components-react, we encourage you to make plans for a near-future migration to @carbon/react and v11.
Other Projects
For styling, @carbon/react now includes all the styles your React project needs. Similarly, if your project is not React-based and pulling styles from carbon-components, you’re going to want to move to @carbon/styles. Both of these now use Dart sass for sass compilation. You can read more about this change in our blog post from 2021.
Vanilla
Additionally, if you’re using Carbon Design System vanilla through carbon-components, this will no longer be supported past v10 and the deprecation of carbon-components. To migrate to v11, we suggest using the vanilla components’ spiritual successor, @carbon/web-components. More on the new version supporting v11 can be found in our recent announcement post.
Closing thoughts
Migration guides for these and more of our active and deprecated packages can be found in our website, as well as migration docs in our public GitHub repository.
For more information on the deprecation, please visit the GitHub discussion for this topic.
Finally, if you’re thinking of spinning up a new project using all things Carbon Design System, welcome! We’re glad you’re here and greatly encourage you to check our getting started content, which will guide you through installing and using our v11 @carbon/* packages.
Francine Lucca is a Software Engineer based out of Atlanta, GA working on the Carbon Design System. The above article is personal and does not necessarily represent IBM’s positions, strategies, or opinions.
Questions or comments about Carbon? Reach out at carbon@us.ibm.com or tweet us @\_carbondesign.
