The dog didn’t eat our homework, so we’re here to show you what we’ve been up to over the past year. We are proud to announce Uppy 5.0! Our faithful file-uploading companion has been attending all the training courses and is now equipped with the most requested feature of all time: truly composable, headless UI components. For years, developers have found themselves stuck between Dashboard’s kitchen-sink approach and the bare-bones drag-drop plugin, with little room to build something that fits just right.

This major release brings headless components and hooks to address those needs. Everything has been backported to 4.0 as well, so you can get going without the need to upgrade.

With Uppy 5.0 , you can finally build the exact upload experience your users deserve – modular, accessible, and tailored to your needs. Whether you need a simple file picker or a complex multi-source interface, Uppy’s got the building blocks to make it happen.

Building your UI: the need for something new​

One size fits no one​

Until now, developers starting with Uppy were forced to choose between either the full-featured, bundle-size-heavy, and non-customizable dashboard or the overly barebones drag-drop.

After years of talking to developers on GitHub and the community forum, and feedback from Transloadit customers, the reality seems to be that the needs of the majority of people fall somewhere in between dashboard and drag-drop. Countless issues have been posted about users wanting mostly X, but doing Y differently for their use case.

@uppy/dashboard has tried to accommodate some of these requests over the years, which introduced overly specific “toggles”, such as showLinkToFileUploadResult, showProgressDetails, hideUploadButton, hideRetryButton, hidePauseResumeButton, hideCancelButton, hideProgressAfterFinish, showRemoveButtonAfterComplete, disableStatusBar, disableInformer, and disableThumbnailGenerator.

Continuing down this path is not maintainable, nor will we ever reach a set of toggles at this level of granularity to support a wide range of use cases and unique requirements.

Fake promises of modular UI components​

We built status-bar, progress-bar, image-editor, thumbnail-generator, informer, and provider-views as separate plugins. At first glance, these look to be standalone components, but they are tightly coupled to dashboard. It’s not impossible to use them separately, but there is little flexibility.

Modern expectations​

Since Uppy’s conception ten years ago, the front-end landscape has changed significantly. Uppy is even built with a “vanilla-first” approach, because that was still popular at the time over front-end frameworks.

These days, developers have high expectations when it comes to choosing a library. In a world where everything is component driven, OSS UI libraries are expected to offer truly composable building blocks that are light on bundle size, and ideally keep accessibility in mind.

If Uppy is to stay relevant in the coming years, a major change is needed in the way we let users build their uploading UI.

Create the UI of your dreams using headless components and hooks​

Uppy 5.0 introduces composable UI components and hooks that provide granular control without sacrificing first-class framework support. These components are designed to be lightweight, accessible, and fully customizable, while maintaining compatibility with React, Vue, and Svelte.

Uppy now offers three ways to build user interfaces:

1. Pre-composed, plug-and-play components. Nothing new here. These are the old <Dashboard /> and <DragDrop />. The downside of this option is that you cannot customize the UI.
2. Headless components 🆕 These new components are smaller, with styles that are easier to override. You can compose these together with your own components.
3. Hooks 🆕 Use hooks to attach our logic to your own components. There are no restrictions. Enjoy the freedom to create a truly tailor-made UI.

When using the new components or hooks, you can use the <UppyContextProvider /> to provide the Uppy instance to the components and hooks.

import { useState } from 'react';
import Uppy from '@uppy/core';
import { UppyContextProvider } from '@uppy/react';

function App() {
	const [uppy] = useState(() => new Uppy());

	return <UppyContextProvider uppy={uppy}>{/* ... */}</UppyContextProvider>;
}

<template>
	<UppyContextProvider :uppy="uppy">
		<!-- ... -->
	</UppyContextProvider>
</template>

<script setup lang="ts">
	import Uppy from '@uppy/core';
	import { UppyContextProvider } from '@uppy/vue';
	import { computed } from 'vue';

	const uppy = computed(() => new Uppy());
</script>

<UppyContextProvider {uppy}>
	<!-- ... -->
</UppyContextProvider>

<script lang="ts">
	import Uppy from '@uppy/core';
	import { UppyContextProvider } from '@uppy/svelte';

	const uppy = new Uppy();
</script>

New components​

All components come with sensible defaults, but expose data attributes for complete styling control. This approach delivers the flexibility developers need, while maintaining the plug-and-play experience Uppy is known for.

Styling component states​

Components expose their internal state through data attributes, enabling precise CSS targeting.

button[data-uppy-element='upload-button'][data-state='init'] {
	background-color: #3b82f6;
}

button[data-uppy-element='upload-button'][data-state='uploading'] {
	background-color: #f59e0b;
	cursor: wait;
}

button[data-uppy-element='upload-button'][data-state='complete'] {
	background-color: #10b981;
}

button[data-uppy-element='upload-button'][data-state='error'] {
	background-color: #ef4444;
}

New hooks​

Examples are shown in React, but the same hooks are available in Vue and Svelte.

• useDropzone
• useFileInput
• useRemoteSource
• useWebcam
• useScreenCapture

Here is an example that uses hooks to exactly mimic the <Dropzone /> component.

import clsx from 'clsx';
import { useDropzone } from '@uppy/react';

type DropzoneProps = {
	note?: string;
	noClick?: boolean;
};

export function Dropzone({ note, noClick }: DropzoneProps) {
	const { getRootProps, getInputProps } = useDropzone({ noClick });

	return (
		<div data-uppy-element="dropzone" role="presentation">
			<input
				{...getInputProps()}
				tabIndex={-1}
				name="uppy-dropzone-file-input"
				className="hidden"
			/>
			<div
				{...getRootProps()}
				tabIndex={0}
				className={clsx(
					'border-2 border-dashed border-gray-300',
					'rounded-lg p-6 bg-gray-50',
					'transition-colors duration-200',
					{
						'cursor-pointer hover:bg-blue-50': !noClick,
					},
				)}
			>
				<div className="flex flex-col items-center justify-center h-full space-y-3">
					<p className="text-gray-600">Drop files here or click to add them</p>
				</div>
				{note ?
					<div className="text-sm text-gray-500">{note}</div>
				:	null}
			</div>
		</div>
	);
}

Putting it all together​

Here you can play around with the new components and hooks in all three frameworks. These examples are also available on Uppy’s GitHub.

Give feedback​

It is still early days with the new components and hooks and we are looking for feedback to improve. Don’t hesitate to reach out to us!

Export maps for all packages​

All packages now have export maps. This is a breaking change in two cases:

1. The css imports have changed from @uppy[package]/dist/styles.min.css to @uppy[package]/css/styles.min.css
2. You were importing something that wasn’t exported from the root, for instance @uppy/core/lib/foo.js. You can now only import things the packages explicitly export.

Changed imports for React, Vue and Svelte​

Some components, like Dashboard, require a peer dependency to work. However, since all components were exported from a single file, you were forced to install all peer dependencies – even if you never imported, for instance, the status bar component.

Every component that requires a peer dependency has now been moved to a subpath, such as @uppy/react/dashboard. As a result, you only have to install the peer dependencies you need.

Before:

import { Dashboard } from '@uppy/react';

Now:

import Dashboard from '@uppy/react/dashboard';

Deprecations​

Merged UI plugins​

@uppy/status-bar and @uppy/informer have been merged into @uppy/dashboard. These components have always been tightly coupled to @uppy/dashboard and with the advent of the new headless components and hooks, we want to go all-in those components and remove the confusing, inflexible ones.

Old plugins​

• @uppy/store-redux can be recreated by consumers, should they need it.
• @uppy/redux-dev-tools is no longer needed.
• @uppy/progress-bar, @uppy/drag-drop, @uppy/file-input and are superseded by the new components and hooks.
• @uppy/aws-s3-multipart has been merged in @uppy/aws-s3 for over a year now.

Overhauled tooling​

As the components started to age, so did our tooling. We put a lot of effort into migrating to a more modern monorepo setup.

A fun example is comparing the before and after of our package.json.

• Instead of global build scripts with lots of conditionals for packages, every package now has its own build script.
• Use the TypeScript compiler instead of Babel for transpiling.
• Introduced Turbo for faster builds.
• Migrated from Cypress to Vitest Browser Mode.
• Migrated from Eslint and Prettier to Biome.
• Migrated from our custom release tooling to Changesets.
• And more smaller clean ups

That’s all we have for you today! We hope you’re excited to play around with this latest version of your favorite file uploading companion that loves to play fetch, and doesn’t chew on your shoes.

Hold on to your leashes, folks! Uppy 4.0 is here, and it’s more exciting than a tennis ball at the dog park! Our beloved Uppy mascot, the adorable coding canine, has been hard at work fetching all the latest updates for you.

From a full TypeScript makeover to shiny new React hooks, and even Google Photos integration – this release is so packed with treats that we’re almost wagging our tails in excitement. Without further a-dog, let’s dig into what makes Uppy 4.0 the goodest of good boys in file uploading!

Migration guide​

This post covers the most exciting new features of Uppy 4.0. We have an accompanying migration guide to help you transition to 4.0.

TypeScript rewrite​

In the year 2024, people expect excellent types from their libraries. We used to author types separately by hand, but they were often inconsistent or incomplete. As of 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.

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 is the new generics on @uppy/core.

import Uppy from '@uppy/core';
// xhr-upload is for uploading to your own back end.
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.body!;

Happy inferring!

Merging the two AWS S3 plugins​

We used to have 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 the internet in general, from what we found – tends to agree that you don’t want to use multipart uploads for files under 100 MB. This sometimes puts users of our libraries in an awkward position, though, as their end users may not exclusively upload very large files, or only small files. In this case, a portion of their users get a subpar experience.

We’ve merged the two plugins into @uppy/aws-s3 with a new shouldUseMultipart option! By default, it switches to multipart uploads if the file is larger than 100 MB. You can pass a boolean or a function to determine this 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-built 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 two 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 read Uppy’s state.

import { useState } from 'react';
import Uppy from '@uppy/core';
import { useUppyState } from '@uppy/react';

// IMPORTANT: passing an initializer function
// to prevent Uppy from being recreated 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 a 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,
);

You can see all the values you can access on the State type.

Using this hook, you can also access the state of any Uppy plugin. For example, in order to access the state of ImageEditor, you would have to look at the types of the plugin.

import type { State } from '@uppy/core';

useUppyEvent(uppy, event, callback)​

Listen to Uppy events in a React component.

The hook returns [results, clear]. results is an array of values from the event. Depending on the event, this can be empty or have up to three values. clear is a function to clear the results array.

Values remain in state until the next event (if that ever comes) or the moment when the state is manually cleared. Depending on your use case, you may want to keep the values in state or clear the state after something else happened.

import { useState } from 'react';
import Uppy from '@uppy/core';
import Transloadit from '@uppy/transloadit';
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', () => {
	// Handle event here.
});

Google Photos​

An often requested feature is finally here: Google Photos support!

@uppy/google-drive and @uppy/google-photos-picker are separate plugins. However, you can use the same OAuth app for both these plugins. Be sure to enable “Photos Library API” in your OAuth app, though!

UX improvements for viewing remote files​

When using Dashboard with any of our remote sources (Google Drive, Facebook, etc.) you use our internal @uppy/provider-views plugin to navigate the folders and select files. In Uppy 4.0, we are making a few quality of life improvements for users. The main changes are described in the table below.

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 returned by the provider API.

Revamped options for @uppy/xhr-upload​

In previous versions, the @uppy/xhr-upload plugin had the options getResponseData, getResponseError, validateStatus and responseUrlFieldName. These were inflexible and too specific. Now we have hooks similar to @uppy/tus:

• onBeforeRequest to manipulate the request before it is sent.
• shouldRetry to determine if a request should be retried. By default, three retries with exponential backoff. After three attempts it will throw an error, regardless of whether you returned true.
• onAfterResponse called after a successful response, but before Uppy resolves the upload.

You could, for instance, use them to refresh your auth token when it expires:

import Uppy from '@uppy/core';
import XHR from '@uppy/xhr-upload';

let token = null;

async function getAuthToken() {
	const res = await fetch('/auth/token');
	const json = await res.json();
	return json.token;
}

new Uppy().use(XHR, {
	endpoint: '<your-endpoint>',
	// Called again for every retry too.
	async onBeforeRequest(xhr) {
		if (!token) {
			token = await getAuthToken();
		}
		xhr.setRequestHeader('Authorization', `Bearer ${token}`);
	},
	async onAfterResponse(xhr) {
		if (xhr.status === 401) {
			token = await getAuthToken();
		}
	},
});

Check out the @uppy/xhr-upload docs for more info.

Simpler configuration for @uppy/transloadit​

To get started with @uppy/transloadit, you would configure assemblyOptions with your auth key, template ID, and other optional values. assemblyOptions can be an object or a function, which is called per file, which returns an object:

{
	"params": {
		"auth": { "key": "key-from-transloadit" },
		"template_id": "id-from-transloadit",
		"steps": {
			// Overruling Template at runtime
		},
		"notify_url": "https://your-domain.com/assembly-status"
	},
	"signature": "generated-signature",
	"fields": {
		// Dynamic or static fields to send along
	}
}

When you go to production, you always want to make sure to set the signature. Not using Signature Authentication can be a security risk. Signature Authentication is a security measure that can prevent outsiders from tampering with your Assembly Instructions.

This means the majority of implementers will write something like this, as recommended:

import Uppy from '@uppy/core';
import Transloadit, { type AssemblyOptions } from '@uppy/transloadit';

new Uppy().use(Transloadit, {
	async assemblyOptions(file) {
		const response = await fetch('/transloadit-params');
		return response.json() as AssemblyOptions;
	},
});

However, now you are making a request to your back end for every file, while the response likely remains the same, unless you are setting dynamic fields per file.

This has now been improved to:

• Only call assemblyOptions() once.
• fields is for global variables in your template.
• All metadata on your files is automatically sent along to Transloadit. This will end up in file.user_meta for you to dynamically access in your Template per file.

You can read more about Assembly Variables in the docs.

Companion​

Streaming uploads by default​

Streaming uploads are now the default in Companion. This comes with greatly improved upload speeds and allows uploading up to hundreds of gigabytes without needing a large server storage. We found that this improves speeds by about 37% for a Google Drive upload of a 1 GB file (source). This feature was also available before, but we wanted to have more real-world usage before setting it as the default.

With streaming upload disabled, the whole file will be downloaded first. The upload will then start when the download has completely finished.

When streaming upload is enabled, Companion will start downloading the file from the provider (such as Google Drive), while at the same time starting the upload to the destination (such as Tus), and sending every chunk of data consecutively.

For more information, see the Companion docs.

corsOrigins option is now required​

As a security measure, we now require the corsOrigins option to be set.

It serves two purposes: it sets the Access-Control-Allow-Origin header as well as the target origin for window.postMessage(), which is needed to communicate the OAuth token from the new tab you used to log in to a provider back to Companion.

And more​

The 4.0 release contains 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, for users and developers alike.

Ready to upgrade? Be sure to check out the migration guide.

It’s this time of the year again! Make yourself cozy by the fire, and let us help you unwrap the gifts Uppy has prepared for you.

We proud of all the improvements and amazing new features and bug fixes we were able to introduce this year. The highlights being: conditional S3 multipart and signing S3 uploads on the client, speedy handling of 10-50k file uploads, refresh tokens (useful when the token expires mid-upload for a large amount of files / slow connections), server-sent events and new assemblyOptions for the Transloadit plugin, Dashboard Single File mode (singleFileFullScreen), improved ETA in the Status Bar, a bunch of new languages, including Hindi, Mexican Spanish and Catalan.

This one, however, is a recent Uppy updates post, covering releases from 3.13.0 to 3.21.0: announcing the switch to Typescript, Dashboard can now auto-install plugins, support for Catalan language, a heap of bug fixes for Tus, Companion, AWS S3, and more.

Typescript​

We are excited to announce that we are working hard to refactor Uppy Core and all plugins source files to TypeScript. We have a build setup in place that temporarily supports both .ts and .js files in our monorepo. And a helper utility that takes a package name and does the initial renaming and Typescript config. Then we go through the list of plugins one by one. We begun with @uppy/utils and @uppy/core, since most other packages depend on those. Now we are moving to the rest, one by one.

This work so far is only affecting Uppy internals. In published packages we are using the manually crafted d.ts files, as before. We are planning to flip the switch and introduce some breaking changes in the next Uppy major, due to be released in the first quater of 2024.

Core​

• Allow duplicate files with onBeforeFileAdded.
• FixedonBeforeFileAdded with Golden Retriever.
• Simplify types with class generic and type more events.

Image Editor​

We have a whole separate blog post about the recent rotation improvements in the Image Editor, so please read that, if you are interested. Other changes include:

• Fixed labels on all buttons, centered the rotation slider label.
• Limited cropbox movements.
• Fixed to respect cropperOptions.initialAspectRatio.
• Change the checkered background color, make it semi-transparent.
• Fixed granular rotation: [-45, 45] instead of [-45, 44].
• Removed 1px black lines.
• Made file-editor:cancel event fire when the Image Editor’s “cancel” button is pressed.

Dashboard​

Dashboard can now automatically discover and install compatible plugins without target option. This lets you use a much more condense syntax:

const uppy = new Uppy()
	.use(ImageEditor)
	.use(Dashboard)
	.use(Webcam)
	.use(GoogleDrive);

Bug fixes:

• Remove .uppy-Dashboard-isFixed CSS class when uppy.close() is invoked.
• When showAddFilesPanel: true, aria-hidden should be the opposite.
• Don’t cancel all files and Assemblies when clicking “done”.
• Update Dashboard’s blue color to meet WCAG contrast requirements.

AWS S3​

• Fixed TypeError, fixed uploadURL when using PUT.
• Pass signal as separate arg for backward compat; pass the uploadURL back to the caller.
• Refresh file before calling user-defined functions.
• Made sure we retry signature request.
• Use uppercase HTTP method names.
• Call #setCompanionHeaders in setOptions.

Companion​

One of the most notable changes in Companion is on the client side, we’ve made authentication optional, allowing for more provider types, with publicly accessable links, for example.

In Companion Client we were able to drop the now unnecessary preflight requests, improving upload speeds and latency yet again.

Other notable changes and fixes:

• Allow dynamic S3 bucket.
• Companion+client stability fixes, error handling and retries.
• Catch “invalid initialization vector” instead of crashing.
• Added Onedrive refresh tokens.
• Fixed authProvider property inconsistency.
• Fixed accelerated endpoints for presigned POST.
• Fixed double tus uploads.
• Fixed onedrive pagination.
• Fixed Redis key default TTL.
• Fixed Uploader.js metadata normalisation.
• Make CSRF protection helpers available to providers.
• Refactor getProtectedHttpAgent to make TS happy.
• Unify redis initialization.
• Use deferred length for tus streams.
• Fixed a refresh token race condition.
• Fixed edge case for pagination on root.
• Fixed instagram/facebook auth error regression; uploadRemoteFile undefined; ProviderView error on empty plugin.icon.
• Added getBucket metadata argument.
• Added missing credentialsURL for box.
• Added test endpoint for dynamic oauth creds.
• Added Companion OAuth Key type.
• Aliased “removeListener” as “off” in Redis emitter.
• Use user-defined onSuccess, onError, and onProgress callbacks in @uppy/tus.
• Invoke headers function for remote uploads.
• Send certain Onedrive errors to the user.
• Upgraded Node.js docker version.

Frameworks Integraions​

• Angular: upgraded to Angular 16.x.
• Svelte: Fixed TS build command.
• Vue: added export for FileInput.

Locales​

• Added Catalan locale ca_ES.
• Added missing translations to de_DE.
• Update Farsi.

Transloadit​

• Emit assembly progress events.
• Removed Socket.io — it’s server-sent events with fallback to polling now.

Misc​

• Added Prettier, migrated to Vitest for Uppy core and Uppy plugins.
• Update file.meta.name after compression, becase format/extension might have changed.
• use latest Node.js version for tests.
• Migrate to AWS-SDK V3 syntax.
• Move remote file upload logic into companion-client.

Happy holidays and see you in 2024!

In this blog post, we’ll be taking a peek behind the curtain, as we take a detailed look into the development of this feature, and our thought-process approaching it.

Before we start though, take a look below at a comparison between how Uppy’s Image Editor used to handle image rotations, and how it handles them now.

Without further ado, let’s dive into some of the finer technical details, so you can follow along and implement this feature into your own image editor.

The above UI is present in many image editors - for example, the default image editors on iOS and Android both employ it. Often users expect this behaviour too, leading to some confusion when their images are left with ugly corners after a rotation.

We implemented this in Uppy’s Image Editor last week, and the solution turned out to be non-trivial. Since this is a pretty ubiquitous task to solve for all image editors, we decided to release our solution to the world and write out a post about it, instead of keeping it hidden away as part of internal notes.

3 Steps​

There are 3 steps to our scaling implementation:

1. Ask your designer what scaling on rotation should look like
2. Find the .scale() function
3. Calculating the geometry

1. Trust your designer​

When I first approached this task, my gut-instinct was to go for the “rotated rectangle inscribed within another rectangle” solution so that the largest-area inscription possible is achieved. This route turned out to be an unpleasant user experience, so take this as an important lesson in trusting your designer, and consulting them first on what the user might want.

Alternatively, you can choose to trust our designer’s advice by:

• always rotating the image around the center of the image (intersection of the diagonals)
• just enlarging the image to remove any empty corners

2. Find the .scale() function​

To enlarge the image in a way that covers empty corners, we first need a scaling function. Uppy uses cropperjs v1.x as an image editing library, which exposes the cropper.scale(scalingFactor) function. Most image editing libraries are likely to have a similar function, but of course feel free to code one yourself if you feel up to the challenge.

Importantly, the scaling function should uniformly enlarge the image around its center, where the scalingFactor is determined by desiredHeight/oldHeight.

3. Calculate the geometry​

Now, we want to draw our before-rotation & after-rotation shapes on the same picture, and apply some trigonometry. If you need to brush up on the mathematics behind this, we recommend watching the following Khan Academy lessons on how angles work and how sines and cosines work, as these cover everything you’ll need to follow along.

In the images below, we see what happens on rotation by default. To remove the empty corners, the user would have to drag around the edges of the cropbox. What we can do instead is scale the image (in the directions shown by the <span style={{ color: rgb(127, 194, 65) }}>green arrows) so that these corners disappear.

What happens on rotation

So, to cover up these checkered corners, we will need to scale the image. If we cover up the larger corner, the smaller corner will get covered up automatically, so our code takes the form of scale(Math.max(scalingFactor1, scalingFactor2)). These two scaling factors are calculated very similarly, so we’ll only focus on calculating only one of them in this tutorial (although the full solution is given in the conclusion).

In the images below, the <span style={{ color: rgb(127, 194, 65) }}>green rectangle represents the desired dimensions of our image after it’s scaled. Our scaling function (and hopefully yours) is defined in such a way that if we have the image of height h, and we want to scale it up to height H, we need to execute .scale(H/h). Since we already know h, as it’s the height of our image, we only need to find H to complete our scaling function.

We want to find H

For the rest of the tutorial, the following steps are then automatic - as we know all the angles in the image, we know the image’s width and height, and we know to find H.

The easiest way to go about it, is to first annotate the image with all the relevant angles. We’ll be using blue for the rotation angle α, and pink for 90 - α:

Color all angles

We can then find H, by adding the two outer sides of these triangles.

Add two triangle sides: H = sin(α - 90) * h + sin(α) * w

So, now we have our desired H! We know one of our scaling factors is H/h. Now, we just need to find our other scaling factor, which is W/w. This follows a similar process, and you can find the calculations as part of the full solution below.

scalingFactor
= max(scalingFactor1, scalingFactor2)
= max(H/h, W/w)
= max(
  (sin(α - 90) * h + sin(α) * w) / h,
  (sin(α) * h + sin(α - 90) * w) / w
)

Conclusion​

In Uppy, our code ended up looking like this:

function getScalingFactor(w, h, rotationAngle) {
	const α = Math.abs(toRadians(rotationAngle));

	const scalingFactor = Math.max(
		(Math.sin(α) * w + Math.cos(α) * h) / h,
		(Math.sin(α) * h + Math.cos(α) * w) / w,
	);

	return scalingFactor;
}
const image = cropper.getImageData();
const scaleFactor = getScalingFactor(image.width, image.height, rotationAngle);
cropper.scale(scaleFactor);

You can see the full version on GitHub.

Bonus content: our founder’s (Tim Koschuetzki) initial scribbled notes with the solution

This is a big Uppy update post, covering releases from 3.3.0 to 3.13.0!

In this issue: the long-awaited unified S3 plugin which can switch between regular and multipart uploads, improved performance when adding and validating 10k+ files, and stability improvements and bug fixes. The Transloadit plugin is now also easier to configure and leaner in bundle size, since we removed socket.io-client in favor of Server-Sent Events.

Please make a cup of something tasty ☕️ (in a non-spillable container), as this will be quite a ride.

AWS S3​

Merging of the plugins​

After years of separating regular non-multipart uploads and multipart uploads, we are finally merging the two sibling plugins: @uppy/aws-s3 and @uppy/aws-s3-multpart. Here’s the brief version of what you need to know, with details to follow in the next section:

• @uppy/aws-s3-multipart is deprecated. You should use @uppy/aws-s3 and set the shouldUseMultipart: true option to get the same “multipart always enabled” behavior. We plan to keep @uppy/aws-s3-multipart around as an alias for the next major cycle and add a warning at the install when Uppy 4.0.0 will be released.
• @uppy/aws-s3 now hosts two plugins:
  • the legacy one, untouched, to guarantee backward compatibility. We plan to get rid of it in the next major, we recommend moving away from it and report if you see something missing in the new plugin.
  • the new merged plugin, available if you pass shouldUseMultipart option.

Our plan for this merge is to maintain the backward compatibility until the next major, while also providing forward compatibility so you can try our new plugin and give us some feedback before we remove the old code for good.

Conditional Multipart Explained​

Multipart and “regular” uploads 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.

So now you can use just one plugin, the @uppy/aws-s3, and enable multipart conditionally, even per-file:

uppy.use(AwsS3, {
	shouldUseMultipart(file) {
		// Use multipart only for files larger than 100MiB.
		return file.size > 100 * 2 ** 20;
	},
});

or

uppy.use(AwsS3, {
	shouldUseMultipart: true,
});

Please see the new shouldUseMultipart: boolean | function option for details.

Signing on the client​

By default, when you upload to S3 with Uppy, every file, or every chunk in case of Multipart, needs to be signed on the server. For many small files or files with many chunks this means a few additional requests per file/chunk of the upload.

To address this issue and speed up the uploads by roughly 20%, we are introducing a new option: getTemporarySecurityCredentials: boolean | function. When true, both S3 and S3 Multipart uploads will be signed on the client using the AWS Security Federation Token, created once per user (until it expires) on your backend rather than a unique signed URL for every single chunk.

Stability and bug fixes​

• We’ve improved the internal handling of RateLimitedQueue to make retries more robust and increased priority of abort and complete requests.
• While we were at it, we’ve also fixed resuming in single-chunk uploads, and improved chunk size calculation.
• Golden Retriever integration with S3 Multipart was fixed.

Additionally, we’ve disabled pause-resume buttons in the UI for remote S3 Multipart uploads — they are not supported on Companion, so the UI now reflects that.

Core​

Performance of adding and uploading big batches of files has (yet again) been greatly improved with refactors in both Uppy Core and Provider Views (that’s what we internally call all remote UIs: Instagram, Unsplash, Dropbox).

We’ve been able to achieve this by refactoring out totals validation for Restrictions (maxTotalFileSize, maxNumberOfFiles): instead of doing it for each file, we perform the check at the end, after all the files have been added/validated. This was confirmed to work with 10k+ files! 🚀

We’ve also fixed an issue with delayed throttled progress events, which could lead to incorrect progress.

Transloadit​

assemblyOptions​

We’ve introduced a new option called assemblyOptions: object | function, which replaces the getAssemblyOptions, params and fields (those are now deprecated and will be removed in the next major).

Here’s how you can use the new option as an object:

uppy.use(Transloadit, {
	assemblyOptions: {
		params: {
			auth: { key: 'key-from-transloadit' },
			template_id: 'id-from-transloadit',
			steps: {
				// Overruling Template at runtime
			},
		},
		signature: 'generated-signature',
		fields: {
			// Dynamic or static fields to send along
		},
	},
});

And here’s an example with a function, to be able to set meta fields per-file, for instance:

uppy.use(Transloadit, {
	assemblyOptions(file) {
		return {
			params: {
				auth: { key: 'TRANSLOADIT_AUTH_KEY_HERE' },
				template_id: 'xyz',
			},
			fields: {
				caption: file.meta.caption,
			},
		};
	},
});

Server-sent events​

Historically Transloadit supported progress updates via Socket.io. It is a robust and stable package, but came with a “price-tag” in the form of bundle size: 38.3 kB Minified. So it’s been on our minds for a while to replace it with something more lightweight, without breaking backwards-compatibility for the older clients (so simply removing Socket.io on the server in favor of plain WebSockets is not desireable).

The answer — Server-sent events. It’s a simple low-overhead one-way connection from Transloadit servers to @uppy/transloadit. As was the case with Socket.io, we fall back to HTTP polling every 2 seconds if SSE connection fails for some reason.

Socket.io is still around in @uppy/transloadit, but will be removed soon, once SSE proves itself in production.

Bug fixes​

• Reset tus key in the file on error, so retried files are re-uploaded.
• Clean up event listener to prevent cancelled assemblies.
• Make sure fields is not nullish when there are no files in Assembly.

Companion​

Refresh tokens​

We’ve implemented refresh tokens for Dropbox and Google Drive to solve issued where tokens would expire in the middle of a long upload and then the upload would fail.

Here’s how it’s implemented in Companion:

• We changed the logic when receiving a 401 from Companion, Uppy will now call a new /:provider/refresh-token endpoint which will give uppy a new access token.
• refresh_token is now stored inside uppy auth token along with access_token (encrypted JWT) for providers that give a refresh token (before only access_token was stored, now we store both as a JSON.stringify’d document).

Bug fixes and improvements​

• Fixed a bug with non-ASCII metadata crashed Companion. The AWS SDK doesn’t encode metadata by itself, so now we do it in Companion.
• Switched from aws-sdk v2 to @aws-sdk/* v3
• Upgraded Grant dependency
• We now send expire info for non-multipart uploads and added connection keep-alive to Dropbox to improve connection stability
• Merged Provider and SearchProvider internal remote source classes.
• Increased max limits for remote file list operations and fixed part listing in S3

Url​

We’ve upgraded the Url plugin to use filename from Content-Disposition header of the file you are importing, instead of relying on the url (but kept the latter as a fallback) (#4489). So now your files have proper names instead of noname.

Dashboard and Status Bar​

Single File Mode has been improved to adapt to height of less than 400px — the UI turns back to grid in this case. We are also not using fit: cover anymore to avoid cropping important parts of the image:

We’ve also added an option to disable the Single File mode, as it can be unwanted in certain use cases: singleFileFullScreen.

If you wrapped Uppy Dashboard in a <form> element, it could be accidentally submitted when a user pressed Enter to save meta fields or entering urls. Now we’ve added a form="" attribute, connected to an empty <form> in document root to prevent the outer form from being submitted.

A bug has been fixed that allowed clicking on buttons and links in Dashboard disabled mode.

Range selection of remote files has been fixed, you can now shift+click to select multiple files again. We’ve added the VirtualList component which is already used in Uppy “selected files” screen to remote file lists. So now scrolling through 10k+ files is breeze 🌬️

Status Bar​

• Fixed ETA when Uppy recovers its state.
• Remove throttled component to fix a bug where state would become shared between multiple status bars on a page.

Locales​

We’ve added support for Hindi and Mexican Spanish. French, Spanish and Chinese locales have been improved.

Uploaders​

• Fixed an issue where sockets were opened right away, ignoring the RateLimitedQueue, which led to bugs in all plugins that handle remote uploads. Additionally, when file is removed (or all are canceled), we call controller.abort on queued requests.
• Fixed a bug with sockets being closed, while the upload was still in progress.
• In XHR Upload we’ve added support for arrays in metadata and an 'upload-stalled' event.

Miscellaneous​

• @uppy/golden-retriever has been refactored refactor to modernize the codebase.
• We’ve switched more non-critical errors to warnings.
• Improved fallbacks for the drag & drop API.
• The React Native example has been modernized and updated.
• uppy.resetProgress() in Core has been fixed.

We hope you’ve enjoyed this update posts and all the fixes and features we’ve worked on! As always, please see the full changelog on GitHub: 3.4.0 — 3.13.0.

We are excited to announce that our new website, documentation and blog are now live out of beta, ready for you to enjoy on Uppy.io! Let us know what you think on twitter.

The first iteration of the Uppy website was built by Artur and Kevin over 7 years ago, using Hexo static site generator as a base. It served us well, but over time Hexo got less maintained, our docs more messy, and quite a few places were collecting dust.

About a year ago Merlijn set on a task to refresh the Uppy documentation experience, rewriting most of the docs from the ground up, with everyone on the team contributing in their area of Uppy knowledge. Docusaurus 🦕 was chosen as one of the top modern tools for documentation.

Most of the plugin’s docs now explain when you should use it (and sometimes when not), followed by how to install, tips and details and links to CodeSandbox samples.

And for desert, we now have a swift website-wide search in the top bar, powered by Algolia, give it a go!

Enjoy the new uppy.io!

🎅🐶 Ho-ho-ho, we are about to wrap up another year for Uppy! Three minor releases ago we’ve introduced Uppy 3.0. It’s time to give you an update on what’s been cooking in the Uppy-Transloadit headquarters (besides cranberry sauce) for the past couple of months.

In short: AWS S3 Multipart stability improvements, Single File Mode for the Dashboard, more tests and bugfixes, new locales.

Safer AWS S3 Multipart uploads on slow connections​

@uppy/aws-s3-multipart has been serving well for people who prefer a client-to_s3 setup with Uppy. However, some uploads could occasionally fail in poor network conditions. It turned out, simultaneously signing and uploading many chunks at once saturated the HTTP/1.1 connection limit, which lead to signatures expiring by the time Uppy started uploading the next chunk.

We’ve refactored our internal queue mechanism to sign chunks right before we begin uploading them to the remote server. When the upload is paused, the queue is emptied and re-populated again on resume. The default limit for this plugin has been set to 6 and the default S3 signature expiry has been lifted from 300 to 800 seconds.

Single File Mode​

Often times people only want to upload a single file (most commonly an image) via Uppy. But the Dashboard UI is tailored to handling many files at once, and it used to display the single image as a small, sad-looking block in the corner. This ends now! (Actually, it ended a few releases ago, figure of speech).

With only one file selected, we’ll display it large and centered, and make sure to re-generate the image preview so it’s 600px wide, looking nice and sleek on modern displays.

See PR #4188 for more screenshots.

Bug fixes and Upgrades​

We’ve upgraded Typescript to v4.8 and Jest to v29, among other tools and packages.

We are now additionally testing that Uppy packages are correctly bundled with the latest Rollup, Webpack, Parcel, Vite, and ESBuild.

Notable bug fixes:

• XHR Upload: Queue requests for socket token for remote files
• Core: Prevent crashes when a file is removed before the upload starts
• Golden Retriever: Fixed upload retries
• AWS S3 and XHR Upload: Fixed Cannot mark a queued request as done in MiniXHRUpload
• Webcam: Set default videoConstraints
• Image Editor: Fix controls in small Dashboard

See the full list in the changelog.

Companion​

And of course, this festive season we are not forgetting Companion under the tree:

• Throttle progress by time
• Added workaround for S3 accelerated endpoints
• Send expire info for non-multipart uploads
• Send expiry time alongside S3 signed requests
• Added support for AbortSignal
• Prevent preflight race condition

Locales​

Uzbek language pack was added, while Polish and Ukrainian language packs were updated.

That’s it for our updates! Stay tuned for more in 2023 and happy holidays (if you are celebrating)! Cheers. In the meantime, we are driving home, driving home for Christmas. Yeah.

For those new to Uppy, coming from Reddit, Hacker News and Product Hunt today: Uppy is a popular open source file uploader for the browser. Pick files from local disk or camera, remote sources like Instagram, Unsplash, Dropbox etc, record audio and screencasts. Crop and tweak images with the image editor plugin. Supports resumable uploads to a tus.io server, AWS S3 (and many others with similar API like DigitalOcean), multipart. Try it!

Uppy is turning three! When you’re counting in dog years – which we most certainly are – that’s 29 already. An age like that signifies proper adulthood. For Uppy, this means it’s ready to stay loyal, but without the silly mistakes (read: bugs). Uppy also underwent (ESM) surgery to keep it strolling by your side in the current ecosystem, and received other behavioral improvements 🐶

TL;DR: ESM transition, native mobile camera, new Remote Sources plugin, sweeping Companion rewrite and streaming support, async/await everything, React 18 and Vue 3 support, all examples rewritten.

ESM surgery​

ECMAScript Modules (ESM) are the future and we’re ready to adopt it. Benefits over CommonJS include: improved security, better tree shaking, and a syntax that can be understood natively by browsers, which can greatly improve the DX if the tools are configured to take advantage of that.

Following in the footsteps of many other packages, we now only ship Uppy core and its plugins as ESM. For Uppy 2.x, we were shipping CommonJS.

If you are already using ESM or the CDN builds, nothing changes for you! If you are using CommonJS, you may have to add extra tooling for everything to work, or consider refactoring your codebase to ESM. Please refer to the Pure ESM package gist for more information and help on how to do that.

Less integration code with the new remote sources preset​

We’ve introduced a new Uppy preset plugin, @uppy/remote-sources, which combines Instagram, Facebook, Google Drive, Box, Unsplash, Dropbox, One Drive, Zoom and any other remote cloud sources that Uppy will support in the future. The plugin only works with Dashboard and allows you to enable all the above sources in a single line.

Before, you had to manually include every cloud provider / remote source:

uppy
	.use(Instagram, {
		companionUrl: COMPANION_URL,
		companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
	})
	.use(GoogleDrive, {
		companionUrl: COMPANION_URL,
		companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
	})
	.use(OneDrive, {
		companionUrl: COMPANION_URL,
		companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
	})
	.use(Instagram, {
		companionUrl: COMPANION_URL,
		companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
	})
	.use(Facebook, {
		companionUrl: COMPANION_URL,
		companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
	})
	.use(Unsplash, {
		companionUrl: COMPANION_URL,
		companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
	});
// ...

After:

uppy.use(RemoteSources, { companionUrl: COMPANION_URL });

To get started, check out the RemoteSources docs.

Robodog ends its service​

Uppy is flexible and extensible through plugins, but the integration code could sometimes prove daunting. This is what brought Robodog to life. It served as an alternative with the same features, but with a more ergonomic and minimal API.

It did, however, come with its own set of new problems:

• Robodog tries to do the exact same thing as Uppy, but looks like an entirely different product.
• Users are faced with a confusing choice between using Robodog or using Uppy directly.
• Robodog is more ergonomic because it’s limited. When hitting such a limit, the user has to refactor everything to Uppy using plugins.

This has now led us to deprecating Robodog and embracing Uppy for its strong suits: modularity and flexibility. At the same time, we’re also introducing something to take away some of the repetitive integration code: @uppy/remote-sources.

Are you using Robodog in your code base? You can check out the migration guide to see how you can transition to Uppy plugins without losing functionality. We have committed ourselves to extending Robodog support for one year to give our users more time to migrate.

Native mobile camera​

As you are probably aware, Uppy’s Webcam plugin provides a nice UI for desktop devices to take pictures and record videos. Up until 3.0, the same UI was utilized on mobile as well.

Since most mobile devices have a system UI for taking pictures and recording videos – which is usually better than any custom solution we can offer – we’ve introduced a new option called mobileNativeCamera for the Webcam plugin:

uppy.use(Webcam, {
	mobileNativeCamera: isMobile({ tablet: true }),
});

By default, it uses the is-mobile package to detect mobile devices, like smartphones and tablets, but you can manually set this option to true or false if you wish. When enabled, instead of the usual Camera/Webcam Uppy UI, users will be presented with buttons that open their device’s native camera interface:

videoConstraints.facingMode is also supported by this option via the capture attribute (in the browsers and devices that respect it).

uppy.use(Webcam, {
	videoConstraints: {
		facingMode: 'user',
	},
});

The same applies to modes, allowing you to enable only video or only photos.

Devotedly stable​

Since the Uppy 2.7.0 release, we’ve fixed over 95 bugs! This includes fixes to bugs that made uploading less stable, documentation corrections, and dependency upgrades.

Companion turns 4.0​

Everyone’s favorite Companion also received some love.

Streaming upload​

Streaming upload can now also be enabled in Companion when using Tus. This comes with greatly improved upload speeds and allows uploading up to hundreds of gigabytes without needing a large server storage. We found that this improves speeds by about 37% for a Google Drive upload of a 1 GB file (source). This feature was also available before Companion 4.0, but it didn’t work with Tus until now.

With streaming upload disabled (default), the whole file will be downloaded first. The upload will then start when the download has completely finished.

When streaming upload is enabled, Companion will start downloading the file from the provider (such as Google Drive), while at the same time starting the upload to the destination (such as Tus), and sending every chunk of data consecutively.

For more information, see the Companion docs.

Event emitter​

Companion now has a server-side event emitter that can be used to detect when uploads start, finish and fail, without having to depend on the client (so it works even when users have closed their browser).

Example code:

const { app, emitter } = companion.app(options);

emitter.on('upload-start', ({ token }) => {
	console.log('Upload started', token);

	function onUploadEvent({ action, payload }) {
		if (action === 'success') {
			emitter.off(token, onUploadEvent); // avoid listener leak
			console.log('Upload finished', token, payload.url);
		} else if (action === 'error') {
			emitter.off(token, onUploadEvent); // avoid listener leak
			console.error('Upload failed', payload);
		}
	}
	emitter.on(token, onUploadEvent);
});

Internal improvements​

Companion’s internal request code and Providers have been rewritten to async/await, which has greatly simplified and reduced the amount of code. This will lead to less bugs and security issues, and make it easier to implement new custom Providers.

We have also replaced the deprecated request library with got. This also removed the need for purest.

And more!​

• Compressor is officially stable. The Compressor plugin for Uppy optimizes images (JPEG, PNG), saving on average up to 60% in size. It has proven itself through extensive battle testing.
• AWS S3 Multipart also became more stable this release, as a result of us hammering out some of the last edge cases with lots of files and/or huge files.
• React 18 is now supported in @uppy/react, Vue 3 is supported for @uppy/vue, and Angular 14 for @uppy/angular.
• Our examples have received a fresh round of updates to keep them relevant.

For more details, see the full changelog and the migration guide.

That’s it from us for now! As you can see, Uppy may be slowly turning into an old dog, but we’re still committed to keep teaching it new tricks. We hope you’ll enjoy this latest major release, and all the features and improvements it includes. We can’t wait to hear your thoughts about it on Twitter!

Compressor​

Some of the most commonly uploaded files on the internet are images — photos, stock images, screenshots, and documents scans. Uppy now includes a new plugin called @uppy/compressor that optimizes images (JPEG, PNG), saving on average up to 60% in size (roughly 18 MB for 10 images). It uses Compressor.js under the hood.

Read the docs and try Compressor in action.

import Uppy from '@uppy/core';
import Compressor from '@uppy/compressor';

const uppy = new Uppy();
uppy.use(Compressor);

@uppy/compressor is also the first plugin that we are releasing as ESM, backwards compatible as CJS, to test out how this works. Please report any issues.

Hosted Companion custom credentials​

It cannot be overstated that our Transloadit-hosted Companion Plugin is the easiest secure way to allow your users pick files from cloud sources like Google Drive, Instagram, Box, etc. via Uppy. Up until now, however, that meant your users had to authenticate their cloud account with Transloadit, preventing you from showing your own logo instead. That has now been fixed! Head to Transloadit Console / Credentials, scroll down to Third-party Credentials, click on Add new Credentials, select Companion OAuth, and voilà!

Try it out with the free Transloadit Community Plan — 5GB / month and access to Companion.

Transloadit rate limiting​

We’ve added rate limiting to Transloadit assembly creation and status polling, and tus retries:

When the remote server responds with HTTP 429, all requests are paused for a while in the hope that it can resolve the rate limiting. Failed requests are now also queued up after the retry delay. Before, they were scheduled for retry without being queued up, which would sometimes end up overflowing the limit option.

As a result of this change, uploading many files at once has become even more robust.

Move to ESM​

The JavaScript ecosystem is moving towards ESM, and we want to follow suit. We are slowly starting to adopt ESM in Uppy packages. To do so, we integrated a plugin into our build system that transpiles ESM source code to CommonJS syntax, which is distributed with the npm package. Nothing will change on your end, though – we know that not everyone is using tooling that support ESM, so we’re holding on to CommonJS for the time being. Our plan is to refactor all official Uppy plugins to ESM before Uppy 3.0 is released, and drop CommonJS in favor of ESM in the npm packages at that point.

For details, see PR 3468.

End to end: move to Cypress​

Uppy has had end to end from the start, but the developer experience was less than ideal with custom Webdriver.io + Selenium. The transition to Cypress allows us to write tests with ease and comfort, backed by great documentation.

Lighter Bundle​

We continue to look for ways to reduce Uppy’s bundle size and modernize our build toolchain. This time, we’ve replaced the Exifr.js legacy bundle with the modern one without IE polyfills. Our Browserify bundler has been replaced with a modern and more efficient ESBuild.

Companion improvements​

• Improved private IP check (#3403)
• Implement periodic ping functionality (#3246)
• Fix broken thumbnails for Box and Dropbox (#3460)
• Fix unpslash author meta, sanitize metadata to strings and improve Companion tests (#3478)

That’s it for today! See the full changelog for more details.

After the release of our latest major version, 2.0.0, we’ve been busy with many things. First of all is the long-awaited Audio plugin to record and upload live audio directly. We then worked on adding a fast and efficient streaming interface to Companion and made Unsplash production ready. Housekeeping was also part of the job: we made Status Bar improvements, moved from npm to Yarn 3, did some refactoring, and updated dependencies.

Last but not least, we got the issue count down from around 110 since 2.0.0 to around 45 now.

Audio plugin​

Uppy now has a new @uppy/audio plugin for recording audio memos, sounds, jingling bells, Christmas carols, and all your holiday cheer. Check it out on the demo page.

@uppy/unsplash is now production ready​

The Unsplash plugin has received an update, providing attribution to the image authors and adding some polish to make it look better. Being fully brand compliant with Unsplash means it’s now production ready. You can demo the plugin on the website or read the docs.

New streaming interface for Companion​

Companion handles the server-to-server communication between your server and file storage providers such as Google Drive, Dropbox, Instagram, and the like. This bypasses the client (so a 5 GB video isn’t eating into your users’ data plans) and files are directly uploaded to the final destination. Companion is made to be effortlessly integrate-able with Uppy.

It used to work by downloading the requested file from a remote provider on the server to then start uploading it to the destination. This did the job, but it’s wasn’t ideal.

We now built streaming support into Companion, which means the download and upload can happen simultaneously. This can result in two times faster uploads, because we no longer have to wait for files to finish downloading before starting the upload process. It’s especially useful for large files and removes the need for a lot of storage space on the server, as data will be buffered in memory.

You can enable this by setting streamingUpload in the Companion options.

NOTE: Streaming is turned off by default. Do not turn it on yet if you’re using TUS for uploads, due to this tus-js-client bug.

Interested in using Companion? You can use Transloadit-hosted Companion on every Plan.

Status Bar error state improvements​

The Status Bar plugin would get confused about upload errors in Uppy, and we’ve addressed this:

• The error state is now shown in case of only one failed file instead of all failed files. The plugin used to get stuck in the uploading state when a single file failed.
• Added “X of X files uploaded” below “Upload failed” for extra context.
• Improved the error details button styling in the Status Bar and the file info card.
• Status Bar state is set to complete if the user manually removes the failed files.

Internal housekeeping​

Yarn v3 instead of npm​

We’ve switched the Uppy repo to Yarn 3 to improve package install performance. With our complex dependency graph and over thirty packages in a monorepo, we are seeing install times reduced by more than a few minutes!

We are using Corepack to make sure all Uppy contributors are using the same version of Yarn. If you are an Uppy contributor, please run the following commands to enable Corepack:

corepack -v || npm i -g corepack # install Corepack if not already installed
yarn -v || corepack enable # install Yarn through Corepack if not already installed
yarn || corepack yarn install # install npm dependencies using yarn

View the PR

Refactor locale scripts & generate types and docs​

This is an internal change, but important nonetheless. Our locales now live in a separate locale.js file for every plugin instead of this.defaultLocale in the class. The docs and types are automatically updated when we add or remove new locale strings.

View the PR.

Automated release scripts​

A lot of things need to happen when we’re publishing a new release. A complete redo of the automation script is now available for quick and secure releases.

Here are some highlights:

• Releaser runs yarn release and will get a series of prompts to set up a release.
• A changelog will be generated.
• The contributions table will be updated.
• GitHub Actions will create a release candidate pull request.
• When approved, GitHub Actions automatically merges, publishes to the npm public registry, and creates CDN bundles.

View the PR.

And more​

• google-drive: plugin has been updated for brand compliance (#3178)
• google-drive: sort Google Drive list by name #3069
• status-bar: now shows all details on mobile when showProgressDetails is true (#3174)
• core: move Uppy class to its own module (#3225)
• angular: fix component crash by loosening package.json version constraints (#3210)
• drop-target: exposed events (#3238)
• companion: add maxFileSize option in companion for safety #3159
• companion: new AWS S3 multipart presigned URL batching endpoint #3056
• companion: improve CORS default headers #3167
• companion: use GET instead of HEAD for getURLMeta for better server compatibility (especially signed S3 URLs) #3048
• companion: deprecate missing uploadUrls option (will be required in the future) #3182
• companion: close window on auth callback error and show error to user #3143
• companion: cut off length of file names to avoid AWS error #3048
• companion: safely escape <script> injected code in Companion’s send-token.js #3101
• companion: upgrade aws-sdk #3334
• companion: improve logging #3103
• companion: change Provider/SearchProvider API to async and use streams instead #3159

Happy Holidays from the Uppy team! Enjoy Christmas and New Year, stay safe, take a walk outside. See you in 2022!

Chow down on all the juicy bits and pieces inside! And make sure to try Uppy live demo.

Uppy is a sleek, modular JavaScript file uploader that integrates seamlessly with any application. It is made for developers who want to provide their users with the ability to see image previews, edit metadata, pick large files directly from Dropbox, restore selected files when a tab was accidentally closed, or crop an image in-browser before sending.

A pup no more​

Ever since the first introduction of Uppy five years ago (or 36 in dog-years), we’ve always referred to our project as ‘the next open source file uploader for web browsers’. The release of Uppy 1.0 a little over two years ago, however, soon led to a steep increase in adoption. Uppy now boasts over 24,000 stargazers on GitHub, making it the undisputed top dog in the world of file uploaders 🌍

With that in mind, we felt it was high time to give Uppy some more much-needed trimming. We want to take this opportunity to break with the past, to make the project leaner – and to pave the way for an even brighter future for Uppy!

Table of Contents​

• Highlights since 1.0
• Smaller bundles
• Faster
• Preact X and upgraded dependencies
• Plugin is replaced with BasePlugin and UIPlugin
• Strict TypeScript types by default
• Batch pre-signing URL's for AWS S3 Multipart
• And more
• What future remains for 1.0?
• That's it

Highlights since 1.0​

A lot of things have happened since we released Uppy 1.0 in April of 2019. In case you have missed some of our 1.x releases, here is a small overview. We have added:

• Official integrations for Vue (3), Angular, and Svelte
• Hooks for the React integration
• Support for picking files from Box, Unsplash, Facebook, and OneDrive
• “Ghost” files, as part of a revamped Golden Retriever plugin, which makes recovering lost files even more intuitive
• Support for 25 more languages (bringing it to a total of 37)
• Dark mode
• an Image Editor
• And four new core team members: @ajkachnic, @mifi, @aduh95, and @murderlon

Smaller bundles​

With 2.0, following in the footsteps of Microsoft, we are dropping support for IE11. As a result, we are able to remove all built-in polyfills, and the new bundle size is 25% smaller! If you want your app to still support older browsers (such as IE11), you may need to add the following polyfills to your bundle:

• abortcontroller-polyfill
• core-js
• md-gum-polyfill
• resize-observer-polyfill
• whatwg-fetch

If you're using a bundler, you need import these before Uppy:

import 'core-js';
import 'whatwg-fetch';
import 'abortcontroller-polyfill/dist/polyfill-patch-fetch';
// Order matters here: AbortController needs fetch, which needs Promise (provided by core-js).

import 'md-gum-polyfill';
import ResizeObserver from 'resize-observer-polyfill';

window.ResizeObserver ??= ResizeObserver;

export { default } from '@uppy/core';
export * from '@uppy/core';

If you're using Uppy from a CDN, we now provide two bundles: one for up-to-date browsers that do not include polyfills and use modern syntax, and one for legacy browsers. When migrating, be mindful about the types of browsers you want to support:

<!-- Modern browsers (recommended) -->
<script src="https://releases.transloadit.com/uppy/v2.0.1/uppy.min.js"></script>

<!-- Legacy browsers (IE11+) -->
<script
	nomodule
	src="https://releases.transloadit.com/uppy/v2.0.1/uppy.legacy.min.js"
></script>
<script type="module">
	import 'https://releases.transloadit.com/uppy/v2.0.1/uppy.min.js';
</script>

Please note that while you may be able to get 2.0 to work in IE11 this way, we do not officially support it anymore.

Faster​

Uppy now loads faster thanks to the decreased bundle size. With Uppy 1.0, adding many files (hundreds or even thousands) used to take dozens of seconds. Uppy 2.0 does the same thing in mere milliseconds! So, at least for this specific use case, we feel comfortable in claiming that you may see your loading times go up to a thousand times faster.

This was made possible by avoiding having to re-render all the file components whenever something changes, using memoize and virtual-list (allowing us to only render what is actually visible on screen). In addition, multiple files are now added to state in one go via uppy.addFiles(Array) as opposed to before, when uppy.addFile(File) + uppy.setState were being called in a loop.

Before optimizations:

And after:

Preact X and upgraded dependencies​

We’ve upgraded almost all of Uppy’s dependencies. This includes the migration to Preact X. All plugins that depend on Preact have been upgraded from 8.2.9 to the latest version 10.5.13. If you’d like your custom plugin to continue working with Uppy 2.0, it also needs to be using latest version of Preact.

Other notable upgrades include browserify to v10, typescript to v4.3, autoprefixer to v10, and lerna to v4.

Plugin is replaced with BasePlugin and UIPlugin​

@uppy/core provided a Plugin class for creating plugins. This was used for any official plugin, but also for users who want to create their own custom plugin. However, Plugin always came bundled with Preact, even if the plugin itself didn't add any UI elements.

As of Uppy 2.0.0, Plugin has been replaced with BasePlugin and UIPlugin. BasePlugin is the minimum you need to create a plugin and UIPlugin adds Preact for rendering user interfaces.

Note: some bundlers will include UIPlugin (and therefore Preact) if you import from @uppy/core. To make sure this does not happen, you can import Uppy and BasePlugin directly:

import Uppy from '@uppy/core/lib/Uppy.js';
import BasePlugin from '@uppy/core/lib/BasePlugin.js';

Interested in creating your own plugin? Check out the “writing plugins” guide.

Strict TypeScript types by default​

Uppy used to have loose types by default and strict types as an opt-in. The default export was a function that returned the Uppy class, and the types came bundled with the default export (Uppy.SomeType).

import Uppy from '@uppy/core';
import Tus from '@uppy/tus';

const uppy = Uppy<Uppy.StrictTypes>();

uppy.use(Tus, {
	invalidOption: null, // this will make the compilation fail!
});

Uppy is now strictly typed by default and loose types have been removed. The default export is the Uppy class and not a function. This means you need to call Uppy with the new keyword when initializing it.

// ...

const uppy = new Uppy();

uppy.use(Tus, {
	invalidOption: null, // this will make the compilation fail!
});

Uppy types are now individual exports and should be imported separately.

import type { PluginOptions, UIPlugin, PluginTarget } from '@uppy/core';

Event types​

@uppy/core provides an .on method to listen to events. The types for these events were loose and allowed for invalid events to be passed, such as uppy.on('upload-errrOOOoooOOOOOrrrr').

Events have received a big update thanks to @Hawxy, making them more strict and accurate.

A breaking change was required to make this happen:

// Before:

type Meta = { myCustomMetadata: string };

// Invalid event
uppy.on<Meta>('upload-errrOOOoooOOOOOrrrr', () => {
	// ...
});

// After:

// Normal event signature
uppy.on('complete', (result) => {
	const successResults = result.successful;
});

// Custom signature
type Meta = { myCustomMetadata: string };

// Notice how the custom type has now become the second argument
uppy.on<'complete', Meta>('complete', (result) => {
	// The passed type is now merged into the `meta` types.
	const meta = result.successful[0].meta.myCustomMetadata;
});

Plugins that add their own events can merge with existing ones in @uppy/core with declare module '@uppy/core' { ... }. This is a TypeScript pattern called module augmentation. For instance, when using @uppy/dashboard:

uppy.on('dashboard:file-edit-start', (file) => {
	const fileName = file.name;
});

Batch pre-signing URLs for AWS S3 Multipart​

The @uppy/aws-s3-multipart plugin can be used to upload files directly to an S3 bucket using S3’s Multipart upload strategy. With this strategy, files are chopped up in parts of 5MB+ each, so they can be uploaded concurrently. It is also very reliable: if a single part fails to upload, only that 5MB chunk has to be retried.

However, in Uppy 1.0, every part had to make the trip to the server to generate a pre-signed URL. This meant that a 1GB file uploaded in 5MB chunks would require two hundred trips to the server.

As of Uppy 2.0.0, we now pre-sign URLs in batches. That same 1GB file now only takes fifty trips to the server (if the limit was four).

This is now the new default. Thanks to @martin-brennan for this contribution!

Do you care about reliable uploads? You could also consider @uppy/tus with a self-hosted or Transloadit Tus server. Tus can resume uploads, supports smaller chunks, and offers increased upload speeds.

And more​

• The .run method on the Uppy instance has been removed. This method was already obsolete and only logged a warning. As of this major version, it no longer exists.
• @uppy/informer now supports showing multiple notifications at the same time. The notifications themselves have also been improved.
• Improved screen reader accessibility for checkboxes and the 'remove file' button for @uppy/dashboard.
• Sort files and folders alphabetically in the Google Drive provider.
• Polished our code base with improved eslint rules, private field methods, and other modern JavaScript features that help us write more intention-revealing and safe code.
• To make Uppy more friendly towards new contributors, we have renamed our master branch to main.

What future remains for 1.0?​

Uppy 1.0 will continue to receive bug fixes for three more months (until 1 December 2021), security fixes for one more year (until 1 September 2022), but no more new features after today. Exceptions are unlikely, but can be made – to accommodate those with commercial support contracts, for example.

That's it!​

We hope you'll waste no time in taking Uppy 2.0 out for a walk. When you do, please let us know what you thought of it on Reddit, HN, ProductHunt, or Twitter. We're howling at the moon to hear from you!

Angular integration​