@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.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):