diff --git a/sites/reactflow.dev/src/pages/learn/troubleshooting/migrate-to-v12.mdx b/sites/reactflow.dev/src/pages/learn/troubleshooting/migrate-to-v12.mdx index a1ad02bd..09be4f7d 100644 --- a/sites/reactflow.dev/src/pages/learn/troubleshooting/migrate-to-v12.mdx +++ b/sites/reactflow.dev/src/pages/learn/troubleshooting/migrate-to-v12.mdx @@ -27,19 +27,18 @@ Before you start to migrate, you need to install the new package. npm install @xyflow/react ``` -{/* this is a workaround to hide headlines from the TOC */} -{

1. A new npm package name

} +### 1. A new npm package name The package `reactflow` has been renamed to `@xyflow/react` and it's not a default import anymore. You also need to adjust the style import. Before v12, React Flow was divided into multiple packages. That's not the case anymore. If you just used the core, you now need to install the `@xyflow/react` package. -{

Old API

} +**Old API** ```js // npm install reactflow import ReactFlow from 'reactflow'; ``` -{

New API

} +**New API** ```js // npm install @xyflow/react @@ -52,11 +51,11 @@ import '@xyflow/react/dist/style.css'; import '@xyflow/react/dist/base.css'; ``` -{

2. Node measured attribute for measured width and height

} +### 2. Node measured attribute for measured width and height All measured node values are now stored in `node.measured`. Besides the new package name, this is the biggest change. After React Flow measures your nodes, it writes the dimesions to `node.measured.width` and `node.measured.height`. If you are using any layouting library like dagre or elk, you now need to take the dimesions from `node.measured` instead of `node`. If you are using `width` and `height`, those values will now be used as inline styles to specify the node dimensions. -{

Old API

} +**Old API** ```js // getting the measured width and height @@ -64,7 +63,7 @@ const nodeWidth = node.width; const nodeHeight = node.height; ``` -{

New API

} +**New API** ```js // getting the measured width and height @@ -72,11 +71,11 @@ const nodeWidth = node.measured?.width; const nodeHeight = node.measured?.height; ``` -{

3. New dimension handling node.width / node.height vs node.measured.width / node.measured.height

} +### 3. New dimension handling node.width / node.height vs node.measured.width / node.measured.height In order to support server side rendering we had to restructure the API a bit, so that users can pass node dimensions more easily. For this we changed the behaviour of the `node.width` and `node.height` attributes. In React Flow 11, those attributes were measured values and only used as a reference. In React Flow 12 those attributes are used as inline styles to specify the node dimensions. If you load nodes from a database, you probably want to remove the `width` and `height` attributes from your nodes, because the behaviour is slightly different now. Using `width` and `height` now means that the dimensions are not dynamic based on the content but fixed. -{

Old API

} +**Old API** ```js // in React Flow 11 you might used node.style to set the dimensions @@ -91,7 +90,7 @@ const nodes = [ ]; ``` -{

New API

} +**New API** ```js // in React Flow 12 you can used node.width and node.height to set the dimensions @@ -109,11 +108,11 @@ const nodes = [ If you want to read more about how to configure React Flow for server side rendering, you can read about it in the [server side rendering guide](/learn/advanced-use/ssr-ssg-configuration). -{

4. Updating nodes and edges

} +### 4. Updating nodes and edges We are not supporting node and edge updates with object mutations anymore. If you want to update a certain attribute, you need to create a new node / edge. -{

Old API

} +**Old API** ```js setNodes((currentNodes) => @@ -124,7 +123,7 @@ setNodes((currentNodes) => ); ``` -{

New API

} +**New API** ```js setNodes((currentNodes) => @@ -135,7 +134,7 @@ setNodes((currentNodes) => ); ``` -{

5. Rename onEdgeUpdate (and related APIs) to onReconnect

} +### 5. Rename onEdgeUpdate (and related APIs) to onReconnect We renamed the `onEdgeUpdate` function to `onReconnect` and all related APIs (mentioned below). The new name is more descriptive and makes it clear that the function is used to reconnect edges. @@ -147,7 +146,7 @@ We renamed the `onEdgeUpdate` function to `onReconnect` and all related APIs (me - `edge.updatable` renamed to `edge.reconnectable` - `edgesUpdatable` renamed to `edgesReconnectable` -{

Old API

} +**Old API** ```js ``` -{

New API

} +**New API** ```js ``` -{

6. Rename parentNode to parentId

} +### 6. Rename parentNode to parentId If you are working with subflows, you need to rename `node.parentNode` to `node.parentId`. The `parentNode` attribute was a bit misleading, because it was not a reference to the parent node, but the `id` of the parent node. -{

Old API

} +**Old API** ```js const nodes = [ @@ -186,7 +185,7 @@ const nodes = [ ]; ``` -{

New API

} +**New API** ```js const nodes = [ @@ -201,11 +200,11 @@ const nodes = [ ]; ``` -{

7. Custom node props

} +### 7. Custom node props We renamed the `xPos` and `yPos` props to `positionAbsoluteX` and `positionAbsoluteY` -{

Old API

} +**Old API** ```js function CustomNode({ xPos, yPos }) { @@ -213,7 +212,7 @@ function CustomNode({ xPos, yPos }) { } ``` -{

New API

} +**New API** ```js function CustomNode({ positionAbsoluteX, positionAbsoluteY }) { @@ -221,34 +220,34 @@ function CustomNode({ positionAbsoluteX, positionAbsoluteY }) { } ``` -{

8. Handle component class names

} +### 8. Handle component class names We renamed some of the classes used to define the current state of a handle. - `react-flow__handle-connecting` renamed to `connectingto` / `connectingfrom` - `react-flow__handle-valid` renamed to `valid` -{

9. getNodesBounds options

} +### 9. getNodesBounds options The type of the second param changed from `nodeOrigin` to `options.nodeOrigin` -{

Old API

} +**Old API** ```js const bounds = getNodesBounds(nodes: Node[], nodeOrigin) ``` -{

New API

} +**New API** ```js const bounds = getNodesBounds(nodes: Node[], { nodeOrigin }) ``` -{

10. Typescript changes for defining nodes and edges

} +### 10. Typescript changes for defining nodes and edges We simplified types and fixed issues about functions where users could pass a NodeData generic. The new way is to define your own node type with a union of all your nodes. With this change, you can now have multiple node types with different data structures and always be able to distinguish by checking the `node.type` attribute. -{

New API

} +**New API** ```js type NumberNode = Node<{ value: number }, 'number'>; @@ -271,23 +270,23 @@ const onNodesChange: onNodesChange = useCallback((changes) => setNodes( You can read more about this in the [Typescript guide](/learn/advanced-use/typescript). -{

11. Rename nodeInternals

} +### 11. Rename nodeInternals If you are using `nodeInternals` you need to rename it to `nodeLookup`. -{

Old API

} +**Old API** ```js const node = useStore((s) => s.nodeInternals.get(id)); ``` -{

New API

} +**New API** ```js const node = useStore((s) => s.nodeLookup.get(id)); ``` -{

12. Removal of deprecated functions

} +### 12. Removal of deprecated functions We removed the following deprecated functions: @@ -297,7 +296,7 @@ We removed the following deprecated functions: - `getMarkerEndId` - `updateEdge` (replaced by `reconnectEdge`) -{

13. Custom applyNodeChanges and applyEdgeChanges

} +### 13. Custom applyNodeChanges and applyEdgeChanges If you wrote your own function for applying changes, you need to handle the new "replace" event. We removed the "reset" event and added a "replace" event that replaces specific nodes or edges. @@ -305,29 +304,29 @@ If you wrote your own function for applying changes, you need to handle the new Now that you successfully migrated to v12, you can use all the fancy features. As mentioned above, the biggest updates for v12 are: -{

1. Server side rendering

} +### 1. Server side rendering You can define `width`, `height` and `handles` for the nodes. This makes it possible to render a flow on the server and hydrate on the client: [server side rendering guide](/learn/advanced-use/ssr-ssg-configuration). - **Details:** In v11, `width` and `height` were set by the library as soon as the nodes got measured. This still happens, but we are now using `measured.width` and `measured.height` to store this information. In the previous versions there was always a lot of confusion about `width` and `height`. It’s hard to understand, that you can’t use it for passing an actual width or height. It’s also not obvious that those attributes get added by the library. We think that the new implementation solves both of the problems: `width` and `height` are optional attributes that can be used to define dimensions and everything that is set by the library, is stored in `measured`. -{

2. Computing flows

} +### 2. Computing flows The new hooks [`useHandleConnections`](/api-reference/hooks/use-handle-connections) and [`useNodesData`](/api-reference/hooks/use-nodes-data) and the new [`updateNode`](/api-reference/hooks/use-react-flow#update-node) and [`updateNodeData`](/api-reference/hooks/use-react-flow#update-node-data) functions (both are part of `useReactFlow`) can be used to manage the data flow between your nodes: [computing flows guide](/learn/advanced-use/computing-flows). We also added those helpers for edges (`updateEdge` and `updateEdgeData`)! - **Details:** Working with flows where one node data relies on another node is super common. You update node A and want to react on those changes in the connected node B. Until now everyone had to come up with a custom solution. With this version we want to change this and give you performant helpers to handle use cases like this. -{

3. Dark mode and CSS variables

} +### 3. Dark mode and CSS variables React Flow now comes with a built-in dark mode, that can be toggled by using the new [`colorMode`](/api-reference/react-flow#color-mode) prop (”light”, “dark” or “system”): [dark mode example](/examples/styling/dark-mode) - **Details:** With this version we want to make it easier to switch between dark and light modes and give you a better starting point for dark flows. If you pass `colorMode="dark"`, we add the class name "dark" to the wrapper and use it to adjust the styling. To make the implementation for this new feature easier on our ends, we switched to CSS variables for most of the styles. These variables can also be used in user land to customize a flow. -{

4. A better DX with TSDoc

} +### 4. A better DX with TSDoc We started to use TSDoc for a better DX. While developing your IDE will now show you the documentation for the props and hooks. This is a big step for us to make the library more accessible and easier to use. We will also use TSDoc in the near future to generate the documentation. -{

More features and updates

} +### More features and updates There is more! Besides the new main features, we added some minor things that were on our list for a long time: @@ -354,7 +353,7 @@ There is more! Besides the new main features, we added some minor things that we - add `selectable`, `deletable`, `draggable` and `parentId` to `NodeProps` - add a warning when styles not loaded -{

Internal changes

} +### Internal changes These changes are not really user-facing, but it could be important for folks who are working with the internal React Flow store: