Guide
Step-by-step guide to updating your code from Carbon v10 to v11.
Overview
This guide helps you update your project to Carbon v11. It is broken into
sections based on packages that you are using in your project today. For most
teams using Carbon, you’ll want to use the
carbon-components-react
section.
One of the biggest changes coming to Carbon in v11 is that we are moving to
dedicated packages under the @carbon
scope. What this means for you is that if
you were previously using the following packages:
carbon-components
carbon-components-react
carbon-icons
@carbon/icons-react
You can access all of this work under one single package: @carbon/react
. This
package will re-export all of the styles and icons for Carbon all in one
dependency.
If you were previously using carbon-components
, the styles from this package
are available under @carbon/styles
. They are also re-exported through
@carbon/react
Both the carbon-components
and carbon-components-react
packages will stick
around in v11 but they will only be re-exports of @carbon/styles
and
@carbon/react
respectively.
carbon-components-react
Starting in v11, the React components for Carbon live in the @carbon/react
package.
The @carbon/react
package also includes the styles for Carbon along with
icons.
Step 1: Install @carbon/react
To get started, uninstall the following packages if they exist in your project:
carbon-components
carbon-components-react
carbon-icons
@carbon/icons-react
npm uninstall carbon-components carbon-components-react carbon-icons @carbon/icons-react
Or, with Yarn:
yarn remove carbon-components carbon-components-react carbon-icons @carbon/icons-react
Next, install the @carbon/react
package:
npm install @carbon/react
Or, with Yarn:
yarn add @carbon/react
Step 2: Styles and Dart Sass
If you’re importing styles from carbon-components
, you can now import styles
directly from @carbon/react
or the @carbon/react/scss
folder.
Before you’re able to bring in these styles, you’ll need to make sure your
project is setup to use Dart Sass. Starting in v11, Carbon styles requires Dart
Sass through the sass
package in order to compile. This change comes from our
migration to Sass Modules in order to improve our compilation times and overall
project structure.
If you don’t have this dependency already in your project, you can install it:
npm install sass
Or, with Yarn:
yarn add sass
Similarly, if you currently use node-sass
now is a good time to remove that
dependency from your project. In most situations, Dart Sass is a drop-in
replacement for node-sass
and should require no changes on your end in order
to use it once you install the dependency.
Step 3: Setup Dart Sass for your project
Once you have Dart Sass installed, it’s important that you configure your
project to support resolving imports in Sass from node_modules
. Typically,
this means adding node_modules
to your includePaths
config for Sass in your
bundler or toolchain of choice.
To learn more about how to configure your specific toolchain to support this, read the documentation for configuration here. We also have published a guide over on Medium to help out with common problems that come from this migration.
Step 4: Update style import paths
In v10, you may have been bringing in styles from carbon-components
by either
importing the styles directly with:
@import 'carbon-components/scss/globals/scss/styles.scss';
Or, you imported the styles through specific entrypoints:
// Feature flags$feature-flags: (enable-columns-16: true,);// Options$css--default-type: true;$css--reset: true;// Top-level imports@import 'carbon-components/scss/globals/scss/vars';
If you imported the entrypoint from carbon-components
, you can now do this
directly from @carbon/styles
without any additional paths by writing:
@use '@carbon/react';
If you were providing any configuration options before you imported Carbon you
can now provide them using the with
syntax:
@use '@carbon/react' with ($css--default-type: true, $css--reset: true);
If you were using any feature flags in v10, you can safely remove them in v11.
Note: you can also use @import
to bring in Carbon, if you prefer, although
@use
is recommended.
If you were bringing parts of Carbon, you’ll need to update the paths to reflect
the new paths in @carbon/styles
. In general, most paths moved from
scss/globals/scss/filename
to scss/filename
.
// Configuration@use '@carbon/react/scss/config' with($css--default-type: true, $css--reset: true);// Reset@use '@carbon/react/scss/reset';// Grid@use