Uppy installation is quite user unfriendly

Hey Uppy creators,

I think you’ve done a great job with Uppy. Thank you for it. But we’ve been fighting with it for at least a day already to try to integrate on a production site and I think there are a few places where at least the documentation could be improved.

  1. Start with a dashboard. You go to https://uppy.io/examples/dashboard/ which is like the main central feature, you get the js and you spend a lot of time after that collecting different pieces on what the html should look like. The example is - I have
<div class='DashboardContainer'></div>

yet I still get

Uncaught Error: Invalid target option given to Dashboard.If you meant to target an HTML element, please make sure that the element exists. Check that the <script> tag initializing Uppy is right before the closing </body> tag at the end of the page. (see 
  1. Sometimes you do
const uppy = Uppy.Core
// https://uppy.io/docs/

Sometimes you do

const uppy = Core
// in https://uppy.io/examples/dashboard/

Sometime you do

const uppy = new Uppy
  1. Pollyfills
    They come and go

This has them


This does not


This does

  1. Event

This says

arrays of  `successful`  and  `failed`  files, just like in [ `uppy.upload()` ](https://uppy.io/docs/uppy/#uppy-upload)’s return value.

While at the same time


follows a different api with file and response while in the complete it is successful and failed.

I understand why most of the things are like this, I know that you’ve got to handle cdn and script and webpack scenarios and manu more, but I think the dev experience could be improved with more consistency and complete examples especially at the dashboard and direct upload

  1. I still can not get the dashboard working with direct upload.

  2. At the top of that I can not post because the discourse is configured to allow ‘only 2 links per new user’ - which means I now have to change the links.

  3. The message

Check that the <script> tag initializing Uppy is right before the closing </body> tag at the end of the page.

Is kind of not consistent with defer: true as deferring the scripts becomes more and more the norm. The script tag is there, but does it mean uppy does not support defer? Because I have uppy in the head with defer:true as it is packed with webpack.

  1. Example says 1MB but value is 1 000 000.

Should it be 110241024, because the docs say it should be maximum file size in bytes for each individual file

  1. Can not copy paste options - I go to https://uppy.io/docs/uppy/#allowMultipleUploads-true, because I have made a mistake with the option and type it as ‘allowMultiplesUpload’. So I decide to copy and paste the option. I can not. The site shows me a cursor of the option name and I can not copy paste it. This cursor allows me to click on it, but it is specifically disabling what I could do with the text.

  2. I would also admit that is taking so long as we’ve taken a direct upload example from another blog post (could not remember where) where the developer has tried to make it easier, but eventually has ended up with an example that is not clear - what happens with the input field, how should it be replaced, etc which diverged from the Uppy documentation. I understand this is out of the control of Uppy, but my point is that others have probably found it difficult to move through the documentation.

  3. I did this and I am allowed to upload multiplefiles

const uppy = Uppy({
    debug: true,
    autoProceed: false,
    allowMultipleUploads: false,
    restrictions: {
      maxFileSize: 100*1024*1024,
      // maxNumberOfFiles: 1,
      // minNumberOfFiles: 1,
      // allowedFileTypes: ['image/*', 'video/*']

I would think that If I have allowMultipleUploads: false, than I would be allow to upload only one file. But this is not the case.

  1. Using Direct Upload and after selecting the file I can change the name of the file in the dashboard. This is not the name of the file as it gets uploaded to s3. At the end it has the same name, and I can not find the place describing this “live edits” of the name of the file to see if I have forgotten something there.

I remember when I did a big project with Uppy/TL I came across many of the same questions.
Support was very responsive in helping me figure out, but the docs could be more consistent, along with more use cases illustrating various scenarios. Great tool though, and platform!

1 Like

Thanks a lot for the feedback, this is super valuable!

Besides the inconsistencies in the docs, upload-success and allowMultipleUploads are the result of some poor naming choices in the past. They both refer to a different “upload” concept in Uppy at different points in its history. The former is for a single file being uploaded, while the latter refers to a batch of files in a single upload “operation” (so all the files that are uploaded when the user clicks “Upload”). We should definitely explain that more clearly in the docs, and add a part generally describing the terms that are used, and hopefully we can fix it with renaming in 2.0 :innocent: