From 932ca2e42a5ab2223c4b952ec12886ce21b27077 Mon Sep 17 00:00:00 2001 From: William Wong Date: Wed, 30 Oct 2019 09:57:53 +0800 Subject: [PATCH] Apply suggestions from code review Co-Authored-By: Corina <14900841+corinagum@users.noreply.github.com> --- CHANGELOG.md | 2 +- README.md | 2 +- samples/23.a.hybrid-react-npm/README.md | 38 ++++++++++++------------- 3 files changed, 21 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 37b153bd40..a9f1f1b35e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -118,7 +118,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - [Single sign-on for Microsoft Teams apps](https://microsoft.github.io/BotFramework-WebChat/19.c.single-sign-on-for-teams-apps/), by [@compulim](https://github.com/compulim) in [#2196](https://github.com/microsoft/BotFramework-WebChat/pull/2196) - [Customize Web Chat with Reaction Buttons](https://microsoft.github.io/BotFramework-WebChat/09.customization-reaction-buttons/). Updated reaction handlers to send `messageReaction` activities, by [@tdurnford](https://github.com/tdurnford) in [#2239](https://github.com/microsoft/BotFramework-WebChat/pull/2239) - [Select voice for speech synthesis](https://microsoft.github.io/BotFramework-WebChat/06.g.select-voice/), by [@compulim](https://github.com/compulim), in PR [#2338](https://github.com/microsoft/BotFramework-WebChat/pull/2338) -- [Using different version of React on hosting app via NPM packages](https://microsoft.github.io/BotFramework-WebChat/23.a.hybrid-react-npm/), by [@compulim](https://github.com/compulim), in PR [#2509](https://github.com/microsoft/BotFramework-WebChat/pull/2509) +- [Using different versions of React on a hosting app via NPM packages](https://microsoft.github.io/BotFramework-WebChat/23.a.hybrid-react-npm/), by [@compulim](https://github.com/compulim), in PR [#2509](https://github.com/microsoft/BotFramework-WebChat/pull/2509) ## [4.5.3] - 2019-10-10 diff --git a/README.md b/README.md index b5be3f6794..12a84fa2f1 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,7 @@ There is a breaking change on behavior expectations regarding speech and input h | [`20.a.upload-to-azure-storage`](https://github.com/microsoft/BotFramework-WebChat/tree/master/samples/20.a.upload-to-azure-storage) | Demonstrates how to use upload attachments directly to Azure Storage | [Upload to Azure Storage Demo](https://microsoft.github.io/BotFramework-WebChat/20.a.upload-to-azure-storage) | | [`21.customization-plain-ui`](https://github.com/microsoft/BotFramework-WebChat/tree/master/samples/21.customization-plain-ui) | Advanced tutorial: Demonstrates how to customize the Web Chat UI by building from ground up instead of needing to rewrite entire Web Chat components. | [Plain UI Demo](https://microsoft.github.io/BotFramework-WebChat/21.customization-plain-ui) | | [`22.customization-change-locale`](https://github.com/microsoft/BotFramework-WebChat/tree/master/samples/22.customization-change-locale) | Demonstrates how to change locale when an activity is received from the bot | [Change Locale Demo](https://microsoft.github.io/BotFramework-WebChat/22.customization-change-locale) | -| [`23.a.hybrid-react-npm`](https://github.com/microsoft/BotFramework-WebChat/tree/master/samples/23.a.hybrid-react-npm) | Demonstrates how to use different version of React on hosting app via NPM packages | [Hybrid React Demo](https://microsoft.github.io/BotFramework-WebChat/23.a.hybrid-react-npm) | +| [`23.a.hybrid-react-npm`](https://github.com/microsoft/BotFramework-WebChat/tree/master/samples/23.a.hybrid-react-npm) | Demonstrates how to use different versions of React on a hosting app via NPM packages | [Hybrid React Demo](https://microsoft.github.io/BotFramework-WebChat/23.a.hybrid-react-npm) | # Web Chat API Reference diff --git a/samples/23.a.hybrid-react-npm/README.md b/samples/23.a.hybrid-react-npm/README.md index 02d836a22a..078adc6a69 100644 --- a/samples/23.a.hybrid-react-npm/README.md +++ b/samples/23.a.hybrid-react-npm/README.md @@ -1,8 +1,8 @@ -# Using different version of React for hosting app and Web Chat +# Using different versions of React for hosting an app with Web Chat -Starting from Web Chat 4.6, we are migrating to React Hooks and requiring React 16.8.6 or up. +In Web Chat version 4.6, we migrated to React Hooks, which requires React 16.8.6 and up. -In this sample, we will show how to use Web Chat in an hosting app with React version 16.0.0, instead of the required 16.8.6. +In this sample, we will show how to use Web Chat in a hosting app with React version 16.0.0, instead of the required 16.8.6. There are several key limitations in this sample. They are outlined in [this section](#why-not-to-use-two-versions-of-react). @@ -22,11 +22,11 @@ To run this sample, follow steps below: There are two packages in this [monorepo](https://en.wikipedia.org/wiki/Monorepo): - `app`: the hosting app, created using [`create-react-app`](https://github.com/facebook/create-react-app) - - Depends on `react@16.0.0` and `react-dom@16.0.0` + - Requires on `react@16.0.0` and `react-dom@16.0.0` - `chat-component`: the chat component, which will render Web Chat - - Depends on `react@16.8.6` and `react-dom@16.8.6` + - Requires `react@16.8.6` and `react-dom@16.8.6` -The hosting app will create an [isolated DOM element](https://reactjs.org/docs/integrating-with-other-libraries.html) and pass it to the `chat-component` package. The chat component will control the rendering of the DOM element, while the hosting app control the lifetime. +The hosting app will create an [isolated DOM element](https://reactjs.org/docs/integrating-with-other-libraries.html) and pass it to the `chat-component` package. The chat component will control the rendering of the DOM element, while the hosting app controls the lifetime. The hosting app will tell the chat component when it is time to remove the DOM element from the tree, and the chat component should stop any further rendering. @@ -44,11 +44,11 @@ function renderChatComponent(props, node) { } ``` -> This entrypoint will return a function, when called, would unmount the component. This function call be [called multiple times to update the props](https://reactjs.org/docs/react-dom.html#render). +> This entrypoint will return a function, which, when called, will unmount the component. This function call can be [called multiple times to update the props](https://reactjs.org/docs/react-dom.html#render). ## Hosting app -In the hosting application, we created a new component called `` and save the reference. +In the host application, we created a new component called `` and save the reference. ```jsx class ChatComponentWrapper extends React.Component { @@ -98,7 +98,7 @@ When `` is mounted or updated, we will call `chat-componen } ``` -When it is time to unmount, we will call the `chat-component` to unmount the component. +When it is time to unmount, we will call to the `chat-component` to unmount the component. ```diff import renderChatComponent from 'chat-component'; @@ -135,25 +135,25 @@ When it is time to unmount, we will call the `chat-component` to unmount the com } ``` -# Why using two versions of React +# Why is this sample using two versions of React -Although we recommend you to upgrade your hosting app as soon as you could, we understand your hosting app may need some time to update its React dependencies, especially when your app is huge. +Although we recommend that you upgrade your host app at your earliest convenience, we understand that host app may need some time before its React dependencies are updated, especially in regards to huge applications. -As stated in [this article](https://reactjs.org/warnings/invalid-hook-call-warning.html), React requires all components that use hooks in the same React DOM tree, must use the _same instance_ of React. +As stated in [this article](https://reactjs.org/warnings/invalid-hook-call-warning.html), React requires that all components using hooks exist in the same React DOM tree, and must use the _same instance_ of React. -In this approach, we isolated the DOM element from the React DOM tree. And use another `react-dom` package to continue the rendering. So the React DOM tree is virtually broken into two parts, although they looks contiguous. This approach is a [supported scenario outlined in React docs](https://reactjs.org/docs/integrating-with-other-libraries.html). +In this approach, we isolated the DOM element from the React DOM tree. Then we use another `react-dom` package to continue the rendering. So the React DOM tree is virtually divided into two parts, although they looks contiguous. This approach is a [supported scenario outlined in React docs](https://reactjs.org/docs/integrating-with-other-libraries.html). # Why not to use two versions of React There are several key limitations to this approach: - Increased memory usage and bundle size -- Only props can be passed between two DOM trees, React Context cannot be passed between them without extra work - - It is doable, but will require two different context objects and wire them up manually - - This also includes `` and `connect()` HOC in `react-redux` -- [React-based customizations](https://github.com/microsoft/botframework-webchat#customize-web-chat-ui) added to Web Chat will still requires React 16.8.6 or up - - For example, activity and attachment middleware will be required to use the newer React -- Introduce new package and could increase unnecessary fragmentation in your codebase +- Only `props` can be passed between two DOM trees; React Context cannot be passed between them without extra work + - It is doable, but will require two different context objects and they must be wired up manually + - This includes `` and `connect()` HOC in `react-redux` +- [React-based customizations](https://github.com/microsoft/botframework-webchat#customize-web-chat-ui) added to Web Chat will still require React 16.8.6 or up + - For example, activity and attachment middleware require the newer version of React +- Introducing new package(s), which could increase unnecessary fragmentation in your codebase - The rendering processes between two DOM trees are asynchronous and not guaranteed to complete at the same time # Further reading