@uppy/react: deprecate `useUppy` (#4223)

Co-authored-by: Mikael Finstad <finstaden@gmail.com>

packages/@uppy/react/src/useUppy.d.ts

@@ -1,5 +1,8 @@
 import type Uppy from '@uppy/core'
 
+/**
+ * @deprecated Initialize Uppy outside of the component.
+ */
 declare function useUppy(factory: () => Uppy): Uppy
 
 export default useUppy

packages/@uppy/react/src/useUppy.js

@@ -1,6 +1,9 @@
 import { useEffect, useRef } from 'react'
 import { Uppy as UppyCore } from '@uppy/core'
 
+/**
+ * @deprecated Initialize Uppy outside of the component.
+ */
 export default function useUppy (factory) {
   if (typeof factory !== 'function') {
     throw new TypeError('useUppy: expected a function that returns a new Uppy instance')

website/src/docs/react-initializing.md

@@ -1,63 +0,0 @@
----
-title: "Initializing Uppy"
-type: docs
-module: "@uppy/react"
-permalink: docs/react/initializing/
-alias: docs/react/initializing/
-order: 1
-category: "React"
----
-
-When using Uppy’s React components, an Uppy instance must be passed in to the `uppy={}` prop from the outside. This Uppy instance must be initialized before passing it to the desired component, and be cleaned up using `uppy.close()` when you are done with it.
-
-## Functional Components
-
-Functional components are re-run on every render. This could lead to accidentally recreate a fresh Uppy instance every time, causing state to be reset and resources to be wasted.
-
-The `@uppy/react` package provides a hook `useUppy()` that can manage an Uppy instance’s lifetime for you. It will be created when your component is first rendered, and destroyed when your component unmounts.
-
-```js
-import Uppy from '@uppy/core'
-import React from 'react'
-import Tus from '@uppy/tus'
-import { DashboardModal, useUppy } from '@uppy/react'
-
-function MyComponent () {
-  const uppy = useUppy(() => {
-    return new Uppy()
-      .use(Tus, { endpoint: 'https://tusd.tusdemo.net/files' })
-  })
-
-  return <DashboardModal uppy={uppy} />
-}
-```
-
-Importantly, the `useUppy()` hook takes a _function_ that returns an Uppy instance. This way, the `useUppy()` hook can decide when to create it. Otherwise you would still be creating an unused Uppy instance on every render.
-
-## Class Components
-
-A common approach is to create an Uppy instance in your React component’s `constructor()` and destroy it in `componentWillUnmount()`.
-
-> ⚠ Uppy instances are stateful, so the same instance must be used across different renders.
-> Do **NOT** initialize Uppy in a `render()` method!
-
-```js
-import React from 'react'
-import { DashboardModal } from '@uppy/react'
-
-class MyComponent extends React.Component {
-  constructor (props) {
-    super(props)
-    this.uppy = new Uppy()
-      .use(Transloadit, {})
-  }
-
-  componentWillUnmount () {
-    this.uppy.close({ reason: 'unmount' })
-  }
-
-  render () {
-    return <DashboardModal uppy={this.uppy} />
-  }
-}
-```

website/src/docs/react.md

@@ -19,60 +19,40 @@ Install from NPM:
 npm install @uppy/react
 ```
 
-## CSS
-
-Make sure to also include the necessary CSS files for each Uppy React component you are using. Follow links for individual components docs below for details on that.
-
 ## Usage
 
+`@uppy/react` exposes component wrappers for `Dashboard`, `DragDrop`, and all other UI elements.
 The components can be used with either [React][] or API-compatible alternatives such as [Preact][].
 
-Instead of adding a UI plugin to an Uppy instance with `.use()`, the Uppy instance can be passed into components as an `uppy` prop.
-All other props are passed as options to the plugin.
+A couple things to keep in mind when using Uppy with React:
+
+* Instead of adding a UI plugin to an Uppy instance with `.use()`, the Uppy instance can be passed into components as an `uppy` prop.
+* All other props are passed as options to the plugin.
+* The Uppy instance should **not** live inside the component but outside of it.
+* You have to pass the IDs of your `use`d plugins to the `plugins` array prop so Dashboard knows it needs to render them.
+* An Uppy instance can’t be used by more than one component. Make sure you are using a unique Uppy instance per component.
+
+Here is a basic example:
 
 ```js
-import React from 'react'
+import React, { useEffect } from 'react'
 import Uppy from '@uppy/core'
-import Tus from '@uppy/tus'
-import { DragDrop } from '@uppy/react'
-
-const uppy = new Uppy({
-  meta: { type: 'avatar' },
-  restrictions: { maxNumberOfFiles: 1 },
-  autoProceed: true,
-})
-
-uppy.use(Tus, { endpoint: '/upload' })
-
-uppy.on('complete', (result) => {
-  const url = result.successful[0].uploadURL
-  store.dispatch({
-    type: 'SET_USER_AVATAR_URL',
-    payload: { url },
-  })
-})
-
-const AvatarPicker = ({ currentAvatar }) => {
-  return (
-    <div>
-      <img src={currentAvatar} alt="Current Avatar" />
-      <DragDrop
-        uppy={uppy}
-        locale={{
-          strings: {
-            // Text to show on the droppable area.
-            // `%{browse}` is replaced with a link that opens the system file selection dialog.
-            dropHereOr: 'Drop here or %{browse}',
-            // Used as the label for the link that opens the system file selection dialog.
-            browse: 'browse',
-          },
-        }}
-      />
-    </div>
-  )
+import Webcam from '@uppy/webcam'
+import { Dashboard } from '@uppy/react'
+
+const uppy = new Uppy().use(Webcam)
+
+function Component () {
+  return <Dashboard uppy={uppy} plugins={['Webcam']} />
 }
 ```
 
+## CSS
+
+Make sure to also include the necessary CSS files for each Uppy React component you are using. Follow links for individual components docs below for details on that.
+
+## Components
+
 The following plugins are available as React component wrappers (you need to
 install each package separately):