Merge pull request #1433 from ably/react-hooks

[SDK-3805] feat: move react-hooks into ably-js

.eslintrc.js

@@ -52,6 +52,7 @@ module.exports = {
     "tools",
     "scripts",
     "docs",
+    "react",
     "Gruntfile.js",
   ],
   settings: {

.github/workflows/react.yml

@@ -0,0 +1,20 @@
+name: Test (react hooks)
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 16
+      - run: npm ci
+      - run: npm run format:check
+      - run: npm run test:react

.gitignore

@@ -5,4 +5,5 @@ node_modules
 npm-debug.log
 .tool-versions
 build/
+react/
 docs/generated/

CONTRIBUTING.md

@@ -18,14 +18,15 @@
 2. Create a new branch for the release, for example `release/1.2.3`
 3. Update the CHANGELOG.md with any customer-affecting changes since the last release and add this to the git index
 4. Run `npm version <VERSION_NUMBER> --no-git-tag-version` with the new version and add the changes to the git index
-5. Create a PR for the release branch
-6. Once the release PR is landed to the `main` branch, checkout the `main` branch locally (remember to pull the remote changes) and run `npm run build`
-7. Run `git tag <VERSION_NUMBER>` with the new version and push the tag to git
-8. Run `npm publish .` (should require OTP) - publishes to NPM
-9. Run the GitHub action "Publish to CDN" with the new tag name
-10. Visit https://github.com/ably/ably-js/tags and add release notes to the release (generally you can just copy the notes you added to the CHANGELOG)
-11. For nontrivial releases: update the ably-js submodule ref in the realtime repo
-12. Update the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/)) with these changes (again, you can just copy the notes you added to the CHANGELOG)
+5. Update the version number to the new version in `src/platform/react-hooks/src/AblyProvider.tsx`
+6. Create a PR for the release branch
+7. Once the release PR is landed to the `main` branch, checkout the `main` branch locally (remember to pull the remote changes) and run `npm run build`
+8. Run `git tag <VERSION_NUMBER>` with the new version and push the tag to git
+9. Run `npm publish .` (should require OTP) - publishes to NPM
+10. Run the GitHub action "Publish to CDN" with the new tag name
+11. Visit https://github.com/ably/ably-js/tags and add release notes to the release (generally you can just copy the notes you added to the CHANGELOG)
+12. For nontrivial releases: update the ably-js submodule ref in the realtime repo
+13. Update the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/)) with these changes (again, you can just copy the notes you added to the CHANGELOG)
 
 ## Building the library
 

README.md

@@ -27,6 +27,8 @@ This SDK supports the following platforms:
 **TypeScript:** see [below](#typescript)
 
 **WebWorkers**: We build a separate bundle which supports running in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) context. You can import it like this:
+
+**React (experimental)** We offer a set of react hooks which make it seamless to use ably-js in your react application. See the [react hooks documentation](./docs/react.md) for more details.
 ```js
 import Ably from 'ably/build/ably-webworker.min';
 ```

docs/react-migration-guide.md

@@ -0,0 +1,46 @@
+# React hooks upgrade / migration guide
+
+## Version 2.x to 3.x
+
+### Replacing `configureAbly` with `AblyProvider` 
+
+In versions 1 and 2 of our react-hooks, we exported a function called `configureAbly` which was used to register an Ably client instance to global state.
+This caused a few issues (most notably it made the hooks difficult to use with hot module reloading), so we have replaced the global configuration function with a context provider (`AblyProvider`)
+The simplest way to use the context provider is to create your own ably-js client outside and then pass it as a prop to the `AblyProvider`.
+All child components of the `AblyProvider` will then be able to use the hooks, making use of the provided Ably client instance. For this reason, we recommend putting the `AblyProvider` high up in your component tree, surrounding all components which may need to use Ably hooks.
+
+For example, replace this:
+```jsx
+configureAbly(options);
+```
+
+With this:
+```jsx
+const client = new Ably.Realtime.Promise(options);
+
+return <AblyProvider client={ably}>
+  {children}
+</AblyProvider>
+```
+
+You may also provide the client options directly to the `AblyProvider` so that the client is created automatically. If you use this prop the client will be automatically closed when the `AblyProvider` is unmounted.
+
+```jsx
+return <AblyProvider options={options}>
+  {children}
+</AblyProvider>
+```
+
+If you were already using multiple Ably clients in the same react application, you may pass in an optional `id` prop to the provider, which you can then pass to the hooks to specify which Ably client instance the hook should use:
+```jsx
+const client = new Ably.Realtime.Promise(options);
+
+return <AblyProvider client={ably} id="foo">
+  {children}
+</AblyProvider>
+
+// in a child component:
+useChannel({channelName: 'my_channel', id: 'foo'}, (msg) => {
+  console.log(msg);
+});
+```