Versioning

This page discusses how individually versioned components work in React Spectrum.

Introduction#

For most applications, we recommend installing the @adobe/react-spectrum package, which includes all stable components in React Spectrum. Using this package ensures that your app includes only a single version of each component, and that all components are compatible with one another.

However, there are some cases where it may be useful to use separate packages for some components. For example, you may need to temporarily upgrade a single component to a newer version without upgrading another. Or you may wish to test out a pre-release version of a component, or a brand new component that's not yet stable. In these cases, you can use the individually versioned packages that we publish for each component in addition to the mono-package. Please see our pre-releases section for more information.

Installing individual packages#

All of the individually versioned component packages are published under the @react-spectrum scope on npm.

You can install any React Spectrum package using a package manager like npm or yarn.

yarn add @react-spectrum/button

By default, this will get you the latest stable version of the component. If you'd like a pre-release version, then you'll need to specify a version to install:

yarn add @react-spectrum/button@3.0.0-rc.2

Using individual packages#

Once you've installed an individual component package, you can update the imports for that component in your app to point to that package instead of the mono-package.

For example, you'd replace:

import {Button} from '@adobe/react-spectrum';

import {Button} from '@adobe/react-spectrum';

import {Button} from '@adobe/react-spectrum';

with:

import {Button} from '@react-spectrum/button';

import {Button} from '@react-spectrum/button';

import {Button} from '@react-spectrum/button';

Considerations#

Using individually versioned packages does have some downsides that you should consider to ensure your application works correctly and avoids bloat.

Manual upgrades#

You must manage versioning yourself. Unlike the mono-package, individually versioned packages must be manually upgraded to ensure compatibility between components. Upgrading a component that depends on another component may require that component to also be updated to ensure compatibility. We suggest using a lock file to ensure versions of dependencies between components are controlled. See yarn lockfiles or NPM lockfiles.

Avoid duplicate versions#

You should ensure that you do not unintentionally introduce multiple versions of the same component into your app. While this does technically work, it will cause your application to include more code than necessary, so it should only be used as a temporary fix if at all.

Provider version#

You must ensure that the version of the Provider component and the theme that you use is greater than or equal to the newest version of any component in your app.

The theme provides the CSS variables that each component depends on, so if you have an old theme that's missing a variable from a newer component somewhere in your app, it will likely not look correct. This case should be rare since variables are added infrequently, but it's good practice to ensure the theme is up to date whenever you install an individually versioned component.

Breaking changes#

While we try to avoid them as much as we can, sometimes breaking changes to components are necessary. React Spectrum strictly follows semver. When a breaking change occurs, it will be done in a major version release to avoid breaking existing applications depending on the old version.

In order to enable applications to upgrade to the latest major versions of components incrementally, the major version will first be published to an individually versioned package for that component. Teams can choose to upgrade this component in their applications when they are ready, without being forced to upgrade all components at once.

Every six months, if there are any major versions of components that have been released, a new major version of the mono-package will be released including all of the latest versions. At this point, applications should upgrade to the latest mono-package and remove any individually versioned packages they had upgraded to in the meantime.

This strategy strikes a balance between enabling applications to upgrade to new versions of components immediately as needed, while not requiring them to upgrade all components at once.