docs(v6): write v5 to v6 migration guide - #5059
Conversation
- Replace the TBC placeholder with complete coverage of packaging, theming, typography, accessibility, and per-component breaking changes for the 6.0 alpha, plus a "Planned for 6.0 stable" section for pending PRs.
|
The full migration is not done yet so i've put PRs that are already open in the Planned section so that this can become live document of some sort. Alternatively we can just keep this PR alive until the full migration is done and then update it. |
| ## Installation and packaging | ||
|
|
||
| The Paper 6.x `TextInput` is a complete rewrite with a new API. Import the component the same way, but note that the props and behavior have changed significantly. | ||
| ### New peer dependencies | ||
|
|
||
| #### Types | ||
| Animations now run on Reanimated. Install it and its worklets runtime next to the existing `react-native-safe-area-context` peer: | ||
|
|
||
| ```tsx | ||
| import { TextInput, type TextInputProps } from 'react-native-paper'; | ||
| ```bash npm2yarn | ||
| npm install react-native-reanimated react-native-worklets | ||
| ``` | ||
|
|
||
| #### Variant | ||
| | v5 peer dependencies | v6 peer dependencies | | ||
| | ----------------------------------------------------- | ------------------------------------------------------------------------------------------- | | ||
| | `react`, `react-native`, `react-native-safe-area-context` | `react`, `react-native`, `react-native-safe-area-context`, **`react-native-reanimated >=4.3.0`**, **`react-native-worklets >=0.8.1`** | |
There was a problem hiding this comment.
The guide misses the icon package change, which is the one item here that breaks apps silently rather than at compile time.
In 5.15.1, MaterialCommunityIcon.tsx resolved its icon module through a three-step chain: @react-native-vector-icons/material-design-icons, then @expo/vector-icons/MaterialCommunityIcons, then react-native-vector-icons/MaterialCommunityIcons. On main (src/components/MaterialCommunityIcon.tsx:37-43) only the first is tried; anything else falls through to FallbackIcon, which renders □ and logs a warning. So every Expo app using @expo/vector-icons, and everyone still on the 10.x single package, loses all of its icons on upgrade with nothing in the guide to explain it.
Worth a subsection under "Installation and packaging" saying the only supported renderer is @react-native-vector-icons/material-design-icons, and that the alternative is a custom renderer via PaperProvider settings={{ icon }}. docs/6.x/docs/guides/icons.mdx:34-39 still points people at both dropped packages, which is a separate follow-up but the same root cause.
There was a problem hiding this comment.
will add it, thanks for the review!
3 participants
Replace the TBC placeholder with complete coverage of packaging, theming, typography, accessibility, and per-component breaking changes for the 6.0 alpha, plus a "Planned for 6.0 stable" section for pending PRs.
Motivation
v6 removes and renames public API without deprecation aliases, so the migration guide is the only place users can find out what changed.
docs/6.x/docs/guides/migration.mdwas a "TBC" stub that only coveredTextInput, and its example still imported the removedMD3LightTheme.The new guide is based on a diff of the public surface between
5.15.1(8b6b5e52) andmain:src/index.tsxexports, component statics and every exportedPropstype. It covers:react-native-reanimated/react-native-workletspeers, the ESM-only build and the JesttransformIgnorePatternsentry it needs, removal ofreact-native-paper/react-navigationandcreateMaterialBottomTabNavigator.MD2*themes,theme.version,isV3,mode,colors.accent,configureFonts({ isV3 })), theMD3*→ unprefixed renames (LightTheme,DarkTheme,Palette,Theme,TypescaleKey,Elevation),DefaultTheme,shadow,overlay,backdrop,surfaceDisabled,roundness→shapes,ColorValuetyping.Caption/Headline/Paragraph/Subheading/Title→Textvariants.accessibility*→aria-*/rolemapping, and which components still accept the old names through native prop passthrough.rippleColorremovals,*Variantprops typedTypescaleKey,refno longer part of manyPropstypes.AnimatedFAB→FAB.Extended,FAB.Group→FAB.Menu,HelperText→supportingText,TextInput.Affix,Checkbox.Android/Checkbox.IOS) and prop tables for Appbar, Badge, BottomNavigation, Button, Checkbox, Chip, DataTable, Dialog, FAB, IconButton, Menu, Searchbar, SegmentedButtons, Switch, TextInput and ToggleButton.BottomNavigation→NavigationBar(feat(navigation-bar): modernize to Material Design 3 #5006),SegmentedButtons→ConnectedButtonGroup(feat: add ConnectedButtonGroup component #5028) and the ToggleButton / Button mode removals are not in the alpha yet, so they are listed with links instead of being documented as removed.Structure and formatting follow the v4 → v5 guide:
## Componentswith###/####per component, MD3 names in italics,v5→v6tables anddiffblocks for before / after.Not included:
theming.mdx,fonts.md,getting-started.mdxandtheming-with-react-navigation.mdindocs/6.xstill referenceMD3LightTheme/roundness/version. That needs a followup i guess.Related issue
No existing issue. Part of the v6's great migration to MD3.
Test plan
yarn --cwd docs buildpasses./6.x/docs/guides/migrationlocally and check the tables, diff blocks, callouts and in-page anchors.src/index.tsx, and every replacement is exported or available as a component static.Propstypes between8b6b5e52andmain.