apps/public-docsite-v9/src/Concepts/Migration/GettingStarted.mdx
import { Meta } from '@storybook/addon-docs/blocks';
<Meta title="Concepts/Migration/Getting Started" />If you are considering migrating to Fluent UI React version 9 then we would first like to thank you and let you know how excited we are for you to experience all the improvements and features we have been working on.
In previous versions, styles were created and applied at runtime. Components used a theme object on React.Context to create styles.
In v9, styles are created at build time to define class names. Components apply these class names at runtime based on state. A theme object is used to set CSS variables in the DOM which component styles reference.
Griffel, a CSS-in-JS framework, provides build-time transforms, atomic CSS, and type-safe styles for v9.
Build-time styles significantly improve rendering performance and can be optimized to reduce bundle size.
In previous versions, the theme defined properties specific to component, component part, and state. For example, inputTextHovered or buttonBorderDisabled.
In v9, the theme properties are defined from the design tokens names. Design tokens are specific to neutral/brand, usage, and state. For example, colorNeutralForeground2Hover, colorBrandForegroundLinkPressed, or spacingVerticalXL.
The Fluent 2 design language provides a practical number of tokens useful to all components without degrading performance. As new components are added, new tokens are not required. This makes each theme less fragile and allows components to depend on token values being defined.
In previous versions, components had props that accepted data objects or arrays. It was the component's responsibility to render each child based on the data. Components often exposed callbacks so callers could override rendering children.
For example, v8's ContextualMenuButton menuProps prop would be passed a hierarchy of menu items to render.
In v9, most components support declaring the children as TSX/JSX elements. Component children are responsible for rendering themselves.
For example, MenuList can have MenuItem, MenuDivider, MenuItemRadio, etc. as children.
Declarative children provide idiomatic React development.
In previous versions, components would expose render callback props. These allowed callers to customize how a component part (e.g. header, footer, item, content) were rendered.
In v9, components define slots that allow callers to replace a component part with their own. Slot props are like the previous callbacks but more powerful; they support literals, TSX/JSX, or render functions. See the Customizing Components with Slots topic for more details.
As a core part of the v9 architecture, slots provide a consistent extensibility mechanism across components. Components no longer need to define their own unique render prop callbacks. Slots provide greater flexibility as they accept literals, TSX/JSX, or render functions.
There will be challenges to overcome during migration. The good news is Fluent UI React v9 was designed to be adopted incrementally and used side-by-side with v0/v8 components.
Think of migration as a process of incrementally adopting components from a new library and phasing out old components rather than as a version bump upgrade from v0 or v8.
Fluent 1 design (v0, v8) and Fluent 2 design (v9) look different. The differences are subtle, but noticeable. You may decide you are okay living with some visual differences during migration.
Alternatively, you can make everything look like Fluent 1 or Fluent 2, but it takes some extra effort. We've provided some techniques and tools. See Keeping Design Consistent.
Version 9 components no longer have a custom styles prop, a runtime theme object on React context, or default SASS support. If you have deeply customized the styles of components from previous versions, it will require effort to bring them forward.
We strongly recommend using the default component styles of Fluent 2 and leave custom styles behind. The default styles provide a high-performance, consistent, accessible, and familiar experience across products.
In v9, component props differ from previous versions. You will need to update code to use new components. We recommend you make the necessary updates in your codebase directly. We have provided some shim components you can consider using temporarily to migrate faster.
You may need to adjust your build dependencies to support multiple versions of Fluent UI React. You may also need to make change to take advantage of tree-shaking, CSS bundling and minification, and browser-matrix compatibility.
During migration you will likely depend on both v9 and previous versions. This can increase the bundle size of your application. As you retire old components, tree shaking will reduce your bundle size. Since v9 components tend to be smaller than previous versions, you should see a bundle size reduction when migration is complete.
If you have a large codebase, it will be helpful to break up your plan into stages.
Read the documentation, try using several components, and inspect the resulting HTML and CSS. Take a look at our roadmap to understand when new v9 components will be shipping vs. which previous components you will need to continue using for now.
Analyze your codebase to measure how many places you use Fluent UI, how much custom styling you do, how much complex data binding you do, and what architectural abstractions you have in place.
Consider how you might flight new components to vet them in your application.
Decide if you want to migrate your entire codebase at once, migrate a single component type (i.e. horizontal migration), or migrate all components in a single experience or page (i.e. vertical migration).
Plan out some milestones where you can verify all your tests pass, you meet your performance benchmarks, and you can confidently ship using new components.
We recommend migrating Button as your first component. It tends to be used across an application, has a straightforward interface, and provides performance improvements. Updating ContextualMenuButton to MenuButton will expose you to converting from data structures to declarative children.
Record how much effort each replacement requires and use this information when planning out future component migrations. Monitor bundle size, build time, and render performance as you adopt v9.
If you are adding new experiences and features to your product, we strongly recommend building them with v9, rather than incurring additional migration debt.
Plan out a rinse-and-repeat plan to migrate your core experiences to v9. From previous stages, you should feel confident handling any migration challenges.
Build a list of the remaining v8 components and check against the roadmap to see when there will be v9 replacements.
Consider building a placeholder component using the v9 hooks composition model and new styling system. Fluent UI React is open source and welcomes contributions!
We'll use Button as an example.
Locate all the usages of Button you want to replace (e.g. ActionButton, PrimaryButton, SplitButton).
Add @fluentui/react-components to associated package.json files.
Update import statements for Button from @fluentui/react to @fluentui/react-components
At each place you use Button, update the props to match v9.
For example, <PrimaryButton> would be replaced with <Button appearance="primary"/>.
Wherever you are using ThemeProvider, add FluentProvider and set the theme (e.g. webLightTheme).
Build and test
You can reference each component's migration documentation to determine which props are carried forward, were changed, or were deprecated/removed.