v3 upgrade guide

Question

v3 upgrade guide

gwyneplaine opened this issue 5 years ago · comments

The core motivation behind 3.0.0 is to set us up to leverage new tools to make react-select better. We've also made some As such we've made the following changes:

Breaking Changes

Upgrade from Emotion 9 to Emotion 10
UMD builds deprecated
Multiple Entrypoints
React 16.8 required as peer dependencies
Normalized Values #3416

What this means for you

Emotion 10

Moving to the latest major version of emotion affords us zero-config SSR and enabling easier CSP support. Unfortunately this will be a breaking change for consumers who are currently leveraging emotion to build custom components for react-select. For example, you'd previously create an custom Option component with emotion like so:

import { css } from 'emotion'

const customOption = ({ cx, className, getStyles, _ }) => 
  <div 
     classNames={cx(
       css(getStyles('option', props)), 
       {
         'option': true,
         'option--is-disabled': isDisabled,
         'option--is-focused': isFocused,
         'option--is-selected': isSelected,
        },
        className
     )}
     {...}
  >

With react-select 3.0.0, and emotion 10 it would be the following:

/** @jsx jsx */
import { jsx } from '@emotion/core';

const customOption = ({ cx, className, getStyles, _ }) => 
  <div 
    css={getStyles('option', props)}
    classNames={cx(
     {
       'option': true,
       'option--is-disabled': isDisabled,
       'option--is-focused': isFocused,
       'option--is-selected': isSelected,
      },
      className
    )} 
    {...}
  >

Multiple Entrypoints:

v3.0.0 separates removes the following components from the main entry point, and instead exports them as separate entrypoints:

Async (now exported from react-select/async)
Creatable (now exported from react-select/creatable)
Async Creatable (now exported from react-select/async-creatable)
makeAnimated and default animated components (now exported from react-select/animated)

Where you’d previously import them as such

	import { Async } from 'react-select'

Or as:

	import Async from 'react-select/lib/Async'

Now imports look like this:

	import AsyncSelect from 'react-select/async'

This should have no bundle-size impact on react-select consumers currently leveraging tree-shaking. However for consumers who aren’t leveraging tree-shaking, this should help alleviate some of the bundle-weight.

UMD Builds

UMD builds have been removed as of react-select v3.

Peer dependency on React 16.8

We've decided on requiring 16.8 as a peer dependency for react-select 3.0.0. This is motivated by our commitment to leveraging the improvements in recent versions of React such as hooks to make react-select even better.

Normalized Values

At the moment, if no value is specified by the consumer, it's instantiated as a null value, regardless of whether the select isMulti or not.

When isMulti is false this is fine. On selection of an option, the value becomes an object, and on clearing of said value, it returns to being null. (null --> {} --> null)

However when isMulti is true, this becomes more inconsistent. On selection of options, the value becomes an array of options, removing values extricates them from this array, removing the last selected value results in an empty array, instead of the initial base state of null.
(null --> [{}] --> [])

We rectify this in 3.0.0, on removal of all selected values in an isMulti Select, the value passed to onChange is null and not [].

Carl Reid · Answer 1 · Mon May 27 2019 21:38:27 GMT+0800 (China Standard Time)

Would be awesome if you could update typings for this too. Currently don't believe I can import like so:
import AsyncSelect from 'react-select/async'

iraSenthil · Answer 2 · Mon Jun 24 2019 23:48:09 GMT+0800 (China Standard Time)

Is there anyways we could link this in release notes?

I usually look at release notes to figure out breaking changes before upgrading.

Nathan Bierema · Answer 3 · Thu Jun 27 2019 00:10:21 GMT+0800 (China Standard Time)

@carlreid I made a PR to update the types: DefinitelyTyped/DefinitelyTyped#36464.

Nick Zayatz · Answer 4 · Wed Aug 28 2019 21:10:28 GMT+0800 (China Standard Time)

Hey @gwyneplaine @JedWatson, do you guys think you could also update https://github.com/JedWatson/react-input-autosize to be for react 16.8? There are a few issues with the newly deprecated functions (i.e. componentWillReceiveProps)

Issue here:

JedWatson/react-input-autosize#163

samjosephgates · Answer 5 · Thu Aug 29 2019 16:21:58 GMT+0800 (China Standard Time)

Can you explain how CSP support has been added? I can't find any documentation on how to configure the nonce within the control.

Jani Matkala · Answer 6 · Tue Oct 01 2019 19:31:16 GMT+0800 (China Standard Time)

@samjosephgates You need to wrap your selects with NonceProvider, which you can import from react-select. Just provide your nonce to it as a prop. At least that's how I got it working. It's not documented anywhere, tho..

cosminn777 · Answer 7 · Fri Oct 11 2019 05:29:23 GMT+0800 (China Standard Time)

Why were the UMD builds deprecated and how can I run v3 in browser?

Daniil Shurygin · Answer 8 · Mon Nov 18 2019 20:47:04 GMT+0800 (China Standard Time)

is there an approximate release date of a fix? We need this! React 16.12 has a lit bit incompatible changes in typings

In React.16.8 (react-select uses it)


    interface FocusEvent<T = Element> extends SyntheticEvent<T, NativeFocusEvent> {
        relatedTarget: EventTarget;
        target: EventTarget & T;
    }

but in the same time React 16.12

    interface FocusEvent<T = Element> extends SyntheticEvent<T, NativeFocusEvent> {
        relatedTarget: EventTarget | null;
        target: EventTarget & T;
    }

diff in relatedTarget: EventTarget | null;

in principle, I generally can't migrate on React 16.12 due different scheduler react versions

deybith · Answer 9 · Wed Apr 29 2020 06:55:48 GMT+0800 (China Standard Time)

How to use nonce with the new version ? I can't see in anywhere.

@naniantero can you explain how do you do more in detail.

Thanks

Ian Storm Taylor · Answer 10 · Mon Jun 08 2020 05:49:15 GMT+0800 (China Standard Time)

Why did the UMD build gets deprecated? How can you use react-select directly from a CDN like Unpkg now?

Cory Simmons · Answer 11 · Mon Jun 22 2020 23:38:30 GMT+0800 (China Standard Time)

react-select now blows up console with deprecation warnings from react. :(

Tom Walker · Answer 12 · Tue Jun 23 2020 09:03:58 GMT+0800 (China Standard Time)

Hey @corysimmons, we're aiming to get this addressed soon - #4094

Cory Simmons · Answer 13 · Wed Jun 24 2020 01:05:34 GMT+0800 (China Standard Time)

@bladey Awesome, thanks for the update and all your hard work!

Conrad Sollitt · Answer 14 · Tue Oct 20 2020 04:30:05 GMT+0800 (China Standard Time)

Can UMD Version still be kept? Does keeping it cause any problems or prevent new features?

I think having a UMD is still useful. For example I created a demo of using the UMD version at the following site and would like the have the option in the future. If not I'll just plan on linking to the older version before UMD is deprecated.

https://awesome-web-react.js.org/examples/select-controls/react-select.htm

Eric Bonow · Answer 15 · Sat Dec 05 2020 01:25:13 GMT+0800 (China Standard Time)

Greetings everyone. I will be closing this issue. A couple points to close out with...

This issue will remain pinned to make it easier to find until the documentation includes an upgrade guide to v3
I have added this initial post to the v3.0.3 release notes making it hopefully easier to find for those searching through the version changes
It is known that UMD support is a feature request for many and believe that it does belong on the roadmap. There are other existing issues that address this and will likely track this feature here: #4120