Todo
Some of this code was taken from my previous upload library. After adding in TS to this as my first TS project, I realize the code can be much better and a refactor needs to be done
Contents
Benefits
This library is the all-in-one react hook for file uploads. It uses XHR so that file upload progress can be used. It supports multiple files at once, and has a built in client for GraphQL uploads. It also has TypeScript definitions for easy debugging.
Install
npm install react-use-upload
Setup
In order to setup the hook, you must first wrap your upload components in an UploadProvider
. This takes the server url, and lets you pass in additional headers with your upload request.
Here's an example around your root app:
Basic Setup
If you are not using GraphQL, do not want to set custom headers for all requests, or set a base api url, you can skip to the basic usage. Adding a top level provider is only required for the features I just mentioned.
import { UploadProvider, createXhrClient } from 'react-use-upload';
<UploadProvider client={createXhrClient({ baseUrl: 'http://localhost:3000' })}>
<App />
</UploadProvider>;
Authentication
import { UploadProvider, createXhrClient } from 'react-use-upload';
const client = createXhrClient({
baseUrl: 'http://localhost:3000',
modifyRequest: request => ({
...request,
headers: {
...request.headers,
authorization: `Bearer ${localStorage.getItem('token')}`,
},
}),
});
<UploadProvider client={client}>
<App />
</UploadProvider>;
When any upload takes place, it will first call modify request, so that you can pass in additional headers or fields.
GraphQL
The graphql client uses the same XHR client under the hood, but it must make additional modifications to the way files are sent to the server. Here's how to do it:
import { UploadProvider, createGraphQLClient } from 'react-use-upload';
const graphQLClient = createGraphQLClient({
baseUrl: 'http://localhost:3000/graphql',
modifyRequest: request => ({
...request,
headers: {
...request.headers,
authorization: `Bearer ${localStorage.getItem('token')}`,
},
}),
});
<UploadProvider client={client}>
<App />
</UploadProvider>;
As you can see, from an end-user perspective, all that is needed is createGraphQLClient
instead of the normal createXhrClient
.
Usage
I tried to make the hook have the simplest api possible in order to support any possible use cases.
Basic Usage
import React, { useState } from 'react';
import { useUpload } from 'react-use-upload';
const NormalUpload = () => {
let [files, setFiles] = useState();
let { loading, progress, error } = useUpload(files, {
path: '/upload',
name: 'test',
fields: { extraData: 'hello!' },
});
return (
<div style={{ marginBottom: 50 }}>
<div>Normal HTTP upload</div>
{loading ? (
<div>Progress: {progress}</div>
) : error ? (
<div>{error}</div>
) : (
<input type="file" onChange={e => setFiles(e.target.files)} />
)}
</div>
);
};
The first argument to the hook is the FileList
array that is given from an input onChange. The second is an object that can contain the following keys:
-
path
the path on the server to upload to. If you setbaseUrl
in the provider tohttp://localhost
, and made the path in the hook/upload
, then the request would be made tohttp://localhost/upload
-
name
the name to use for the files when sending to the server -
fields
additional data to send along with the request -
headers
extra headers to send
GraphQL Usage
import React, { useState } from 'react';
import { useUpload } from 'react-use-upload';
import gql from 'graphql-tag';
const uploadMutation = gql`
mutation UploadFile($input: UploadFileInput!) {
uploadFile(input: $input) {
name
randomField
}
}
`;
const GraphQLUpload = () => {
let [files, setFiles] = useState();
let { loading, progress, error } = useUpload(files, {
mutation: uploadMutation,
variables: { input: { files, name: 'test' } },
});
return (
<div style={{ marginBottom: 50 }}>
<div>GraphQL Test</div>
{loading ? (
<div>Progress: {progress}</div>
) : error ? (
<div>{error}</div>
) : (
<input type="file" onChange={e => setFiles(e.target.files)} multiple />
)}
</div>
);
};
Using the graphql-tag
library, create or import a mutation that is built for file uploads. You can take a look at our example/server.js to see how this works with Apollo server.
The options for graphql are as follows:
-
mutation
The mutation object resulting from graphql-tag -
variables
The variables that your mutation expects. The files must be inside of here somewhere -
headers
extra headers to send
Signed Uploads
When performing an upload to AWS, Google Cloud, or other hosting provider the process is generally like this:
- Hit your own server, with file metadata, and get back a URL that you should upload to. This would be a direct upload url to a storage bucket
- Perform the upload to the signed url
- Hit your own server again if needed, so that you know the file upload is complete (can be done other ways as well)
Here's how this looks:
import React, { useState, useEffect } from 'react';
import { useUpload } from 'react-use-upload';
const getUrl = async files => {
let response = await fetch('http://localhost:3000/get-url');
let { url } = await response.json();
return url;
};
const NormalUpload = () => {
let [files, setFiles] = useState();
let { loading, progress, error, done } = useUpload(files, {
getUrl,
name: 'test',
});
useEffect(() => {
if (!done) return;
console.log('done uploading, send something to your server if you need to');
}, [done]);
return (
<div style={{ marginBottom: 50 }}>
<div>Signed upload</div>
{loading ? (
<div>Progress: {progress}</div>
) : error ? (
<div>{error}</div>
) : (
<input type="file" onChange={e => setFiles(e.target.files)} />
)}
</div>
);
};
The library adds one small feature to support these usecases. An async getUrl
option that can be passed into the configuration object.
This must be a promise, and the upload will wait for it, and use the url it resolves to do the file upload. After it is done, you can make your own useEffect
if you need to do something afer the upload completes.
React Native
This works using ReactNativeFile
from apollo-upload-client example coming soon.