tus-uploady

Tus Uploady

This package is provided as a convenient alternative to the main Uploady package. To be used in case resumable (tus) upload is required.

The package wraps the tus-sender

Additional information about tus functionality can be found at the tus-sender API doc.

The best place to get started is at our: React-Uploady Documentation Website

Installation

#Yarn:
  $ yarn add @rpldy/tus-uploady

#NPM:
  $ npm i @rpldy/tus-uploady

Props

Name (* = mandatory)	Type	Default	Description
version	string	"1.0.0"	The tus server version
featureDetection	boolean	false	whether to query the server for supported extensions
featureDetectionUrl	string	null	URL to query for TUS server feature detection, in case it's different from upload URL
onFeaturesDetected	(string[]) => ?TusOptions	void	callback to handle the extensions the server broadcasts
resume	boolean	true	whether to store information locally on files being uploaded to support resuming
deferLength	boolean	false	defer sending file length to server (protocol)
overrideMethod	boolean	false	whether to use X-HTTP-Method-Override header instead of PATCH
sendDataOnCreate	boolean	false	send first chunk with create request (protocol)
storagePrefix	string	"__rpldy-tus__"	the key prefix to use for persisting resumable info about files
lockedRetryDelay	number	2000	milliseconds to wait before retrying a locked (423) resumable file
forgetOnSuccess	boolean	false	whether to remove URL from localStorage when upload finishes successfully
ignoreModifiedDateInStorage	boolean	false	ignore File's modified date when creating key for storage
resumeHeaders	Record<string, string>	null	Headers to use for the resume check (HEAD) request

In addition, all UploadOptions props can be passed to TusUploady. In order to override configuration passed to the parent Uploady component. See Uploady documentation for detailed list of upload options.

All of the chunked-sender options are supported as well

Params prop that is set on the Destination or upload options is serialized (encoded according to Tus protocol) and sent as the value of the Upload-Metadata header.

Custom headers set on the Destination will be sent (and override existing headers) with the Creation request

TUS Protocol

On top of the Core Protocol, Uploady supports the following extensions:

• Creation (creation)
• Creation with Upload (creation-with-upload)
• Concatenation (concatenation)
• Creation Defer Length (creation-defer-length)

It also supports the Upload-Metadata header and will turn the destination params prop into the metadata key/value.

Hooks

useTusResumeStartListener

Called before the (HEAD) request is issued on behalf of a potentially resumeable upload.

This event is cancellable

Receives an object with:

• url: the URL the resume request will be sent to
• item: the BatchItem being sent
• resumeHeaders: an optional object that was passed to the TusUploady props

May return false to cancel the resume, nothing, or an object with url property to overwrite the URL the request will be sent to. And/Or a resumeHeaders object that will be merged with the optional object passed as a prop to TusUploady.

import React from "react";
import { useTusResumeStartListener } from "@rpldy/tus-uploady";

const MyComponent = () => {
    useTusResumeStartListener(({ url, item, resumeHeaders }) => {
        return cancelResume ? false : {
            resumeHeaders: {
                "x-another-header": "foo",
                "x-test-override": "def"
            }
        }
    });

	//...
};

useClearResumableStore

By default, the tus-sender will store the URLs for uploaded files so it can query the server for their status and skip chunks that are indicated as uploaded.

The URLs are persisted to local storage. This hooks allows you to clear the URLs that were previously persisted.

import React, { useCallback } from "react";
import { useClearResumableStore } from "@rpldy/tus-uploady"; 

const MyComponent = () => {
	const clearResumables = useClearResumableStore();
    
    const onClear = useCallback(() => {
      clearResumables();
    }, [clearResumables]);

    return <button onClick={onClear}>Clear Store</button>;
}; 

Example

 import React from "react";
 import TusUploady from "@rpldy/tus-uploady";
 import UploadButton from "@rpldy/upload-button";
 
 const App = () => (<TusUploady
     destination={{ url: "https://my-tus-server/upload" }}
     chunkSize={2142880}
     sendDataOnCreate>
     <UploadButton/>
 </TusUploady>);