4.0 blog post

Murderlon · Murderlon · commit 82fa731c7add · 2024-07-08T18:15:50.000+02:00
diff --git a/blog/2024-07-3-uppy-4.0.md b/blog/2024-07-3-uppy-4.0.md
@@ -0,0 +1,238 @@
+---
+title:
+  'New Uppy 4.0 major: TypeScript rewrite, Google Photos, React hooks, and much
+  more.'
+date: 2024-07-03
+authors: [aduh95, evgenia, mifi, murderlon]
+image: 'https://uppy.io/img/blog/3.13-3.21/dog-coding-laptop-mars-christmas-tree-2.jpg'
+slug: 'uppy-4.0'
+published: false
+toc_max_heading_level: 2
+---
+
+Hi ha ho, this is some goofy introduction.
+
+## TypeScript rewrite
+
+In the year 2024 people expect exellent types from their libaries. We used to
+author types separately by hand but they were often inconsistent or incomplete.
+Now Uppy has been completely rewritten in TypeScript!
+
+From now on you’ll be in safe hands when working with Uppy, whether it’s setting
+the right options, building plugins, or listening to events.
+
+```ts
+import Uppy from '@uppy/core';
+
+const uppy = new Uppy();
+
+// Event name autocompletion and inferred argument types
+uppy.on('file-added', (file) => {
+	console.log(file);
+});
+```
+
+One important thing to note are the new generics on `@uppy/core`.
+
+```ts
+import Uppy from '@uppy/core';
+// xhr-upload is for uploading to your own backend.
+import XHRUpload from '@uppy/xhr-upload';
+
+// Your own metadata on files
+type Meta = { myCustomMetadata: string };
+// The response from your server
+type Body = { someThingMyBackendReturns: string };
+
+const uppy = new Uppy<Meta, Body>().use(XHRUpload, {
+	endpoint: '/upload',
+});
+
+const id = uppy.addFile({
+	name: 'example.jpg',
+	data: new Blob(),
+	meta: { myCustomMetadata: 'foo' },
+});
+
+// This is now typed
+const { myCustomMetadata } = uppy.getFile(id).meta;
+
+await uppy.upload();
+
+// This is strictly typed too
+const { someThingMyBackendReturns } = uppy.getFile(id).response;
+```
+
+Happy inferring!
+
+## Merging the two AWS S3 plugins
+
+We used to two separate plugins for uploading to S3 (and S3-compatible
+services): `@uppy/aws-s3` and `@uppy/aws-s3-multpart`. They have different use
+cases. The advantages of multipart uploads are:
+
+- Improved throughput – You can upload parts in parallel to improve throughput.
+- Quick recovery from any network issues – Smaller part size minimizes the
+  impact of restarting a failed upload due to a network error.
+- Pause and resume object uploads – You can upload object parts over time. After
+  you initiate a multipart upload, there is no expiry; you must explicitly
+  complete or stop the multipart upload.
+- Begin an upload before you know the final object size – You can upload an
+  object as you are creating it.
+
+However, the downside is request overhead, as it needs to do creation, signing,
+and completion requests besides the upload requests. For example, if you are
+uploading files that are only a couple kilobytes with a 100ms roundtrip latency,
+you are spending 400ms on overhead and only a few milliseconds on uploading.
+This really adds up if you upload a lot of small files.
+
+AWS, and generally the internet from what we found, tend to agree that **you
+don't want to use multipart uploads for files under 100MB**. But this sometimes
+puts users of our libraries in an awkward position, as their end users may not
+only upload very large files, or only small files. In this case a portion of
+their users get a subpar experience.
+
+---
+
+<!-- TODO: /aws-s3-multipart link should be /aws-s3 (needs site changes) -->
+
+We’ve merged the two plugins into `@uppy/aws-s3` with a new
+[`shouldUseMultipart`](/docs/aws-s3-multipart/#shouldusemultipartfile) option!
+By default it switches to multipart uploads if the file is larger than 100MB.
+You can pass a `boolean` or a function to determine it per file.
+
+## React hooks
+
+People working with React are more likely to create their own user interface on
+top of Uppy than those working with "vanilla" setups. Working with our pre-build
+UI components is a plug-and-play experience, but building on top of Uppy’s state
+with React primitives has been tedious.
+
+To address this we’re introducing to new hooks: `useUppyState` and
+`useUppyEvent`. Thanks to the TypeScript rewrite, we can now do powerful
+inference in hooks as well.
+
+### `useUppyState(uppy, selector)`
+
+Use this hook when you need to access Uppy’s state reactively.
+
+```js
+import Uppy from '@uppy/core';
+import { useUppyState } from '@uppy/react';
+
+// IMPORTANT: passing an initializer function to prevent Uppy from being reinstantiated on every render.
+const [uppy] = useState(() => new Uppy());
+
+const files = useUppyState(uppy, (state) => state.files);
+const totalProgress = useUppyState(uppy, (state) => state.totalProgress);
+// We can also get specific plugin state.
+// Note that the value on `plugins` depends on the `id` of the plugin.
+const metaFields = useUppyState(
+	uppy,
+	(state) => state.plugins?.Dashboard?.metaFields,
+);
+```
+
+<!-- TODO: this permalink to State will get outdated. Maybe put it in a file we can link to? -->
+
+You can see all the values you can access on the
+[`State`](https://github.com/transloadit/uppy/blob/dab8082a4e67c3e7f109eacfbd6c3185f117dc60/packages/%40uppy/core/src/Uppy.ts#L156)
+type. If you are accessing plugin state, you would have to look at the types of
+the plugin.
+
+### `useUppyEvent(uppy, event, callback)`
+
+Listen to Uppy [events](/docs/uppy/#events) in a React component.
+
+Returns an array of which the first item is an array of results from the event.
+Depending on the event, that can be empty or have up to three values. The second
+item is a function to clear the results.
+
+Values remain in state until the next event (if that ever comes). Depending on
+your use case, you may want to keep the values in state or clear the state after
+something else happened.
+
+```ts
+import Uppy from '@uppy/core';
+import { useUppyEvent } from '@uppy/react';
+
+// IMPORTANT: passing an initializer function
+// to prevent Uppy from being recreated on every render.
+const [uppy] = useState(() => new Uppy());
+
+const [results, clearResults] = useUppyEvent(uppy, 'transloadit:result');
+const [stepName, result, assembly] = results; // strongly typed
+
+useUppyEvent(uppy, 'cancel-all', doSomethingElse);
+```
+
+## Google Photos
+
+A long requested feature is finally here: Google Photos support!
+
+:::info
+
+Uppy can bring in files from the cloud with [Companion](/docs/companion/).
+
+Companion is a hosted, standalone, or middleware server to take away the
+complexity of authentication and the cost of downloading files from remote
+sources, such as Instagram, Google Drive, and others.
+
+This means a 5GB video isn’t eating into your users’ data plans and you don’t
+have to worry about OAuth.
+
+:::
+
+<!-- TODO: video of the Google Photos plugin -->
+
+[`@uppy/google-photos`](/docs/google-photos/) is a new plugin so you can use it
+next to your existing [`@uppy/google-drive`](/docs/google-drive/) plugin.
+
+## UX improvements for viewing remote files
+
+When using [Dashboard](/docs/dashboard) with any of our remote sources (such as
+Google Drive) you use our internal `@uppy/provider-views` plugin to navigate and
+select files.
+
+We now made a handful of quality of life improvements for users.
+
+|                Before                 | After |
+| :-----------------------------------: | :---: |
+| ![yeah](/img/blog/3.13-3.21/crop.mov) | yeah  |
+
+<!-- TODO: video of the improvements-->
+
+- **Folder caching**. When naviging in and out of folders, you now no longer
+  have to wait for the same API call — you’ll see the results instantly.
+- **Indeterminate checkmark states**. Before going into a folder we can’t know
+  how many files it contains so checking it immediately will show a traditional
+  checkmark. But when you go into a folder and you only select a subset of the
+  files, we’ll now show the indeterminate checkmark for the folder when you
+  navigate back out. Making it more clear you’re only uploading some of the
+  files in that folder.
+- **Reworked restrictions**. Uppy supports file
+  [restrictions](/docs/uppy/#restrictions), such as max number of files and max
+  file size. It’s now immediately clear in the UI when you are exceeding the max
+  number of files you can select. The error notifications are now also more
+  clear.
+- **Shift-click multi-select fixes**. You can shift-click the checkboxes to
+  select many files at once. This did not always work correctly and it also
+  highlighted the files names, which we now improved.
+
+We’re confident this turns our interface for remote sources into the most
+advanced one out there. We’ve seen some competing libraries not even aggregating
+results beyond the first page API limit of providers.
+
+## Revamped options for `@uppy/xhr-upload`
+
+## Simpler configuration for `@uppy/transloadit`
+
+## Companion
+
+## And more
+
+The 4.0 release contained over 170 contributions, many too small to mention, but
+together resulting in Uppy continuing to grow and improve. We closely listen to
+the community and are always looking for ways to improve the experience.
+
+Since our last blog post other (non-breaking) changes have also been released.
