search

pingdotgg / uploadthing

File uploads for modern web devs
https://uploadthing.com
MIT License
3.95k stars 285 forks source link

[DocBug]: Improve DX by sharing "why" some resctrictions are required #76

Closed mcunha closed 1 year ago

mcunha commented 1 year ago

What happened?

First off all, thanks for uploadthing - love the work! The following is written out of love and with gratitude.

There a few instances in docs where restrictions are placed on developers. It's good to be upfront about those, and it would be better to share reasoning for those limits as well as any potencial side effects [if any].

Developers have different levels of expertise in the stack so doing the above helps with transparency, inclusion and ensuring principle of least surprise for better DX - particularly for people not as deeply familiar with the relevant stacks. Adding some lightweight explanation OR hyperlinking to deeper reasoning could be offered, and if side effects are relevant, disclose those would resolve this.

Examples: [from https://docs.uploadthing.com/nextjs/appdir]

Note: This is the ONLY FILE WHERE THE PATH MATTERS. You need to serve this API from /api/uploadthing on your application.

Fair to ask for path to be frozen because reasons. What are the key drivers for this ? - something like 

We need this so that <a href={url_to_longer_read_if_available}>{concise_reasons}</a>.

would help. [I'm guessing it's related to needing an easily discoverable webhook endpoint to call from your infra - but I'm just guessing].

[from https://docs.uploadthing.com/nextjs/pagedir]

If you're using the pages/ directory in Next still, you HAVE TO DISABLE THE esmExternals FLAG:

Also fair to require this change. What are the key drivers for it ? Does that have side effects for developers that they might need to read about elsewhere and understand ? Is this foreseen to remain this way until Pages are deprecated Next ?

Note: This is the ONLY FILE WHERE THE PATH MATTERS. You need to serve this API from pages/api/uploadthing on your application.

Same note as for appdir above.

[from https://docs.uploadthing.com/solid]

Note: This is the ONLY FILE WHERE THE PATH MATTERS. You need to serve this API from /api/uploadthing on your application.

Same note as for appdir above.

Hope this helps, and thanks again for such a neat solution to annoying uploads.

What did you expect to happen?

Nitpick: More clarity around drivers for limitations

Version

Last updated on May 15, 2023

Reproduction Steps

Open the doc pages listed above

Reproduction Repository

https://docs.uploadthing.com/

Relevant log output

No response

Code of Conduct

t3dotgg commented 1 year ago

https://github.com/pingdotgg/uploadthing/pull/84