While WunderGraph's main purpose is to deal with structured data, files / blobs are also an important aspect of building applications.
Your users might not only want to upload content in their applications but also images, PDF files, etc...
We've looked into the various solutions that frameworks offer to make file uploads easy alongside your REST or GraphQL APIs. What we found is that most solutions are custom and require some extra work either in the client, the server-side or even both.
Our credo is, developer experience first! For that reason, we've added support for S3 compatible storage providers.
What is S3?
In case you're already familiar, skip this section.
S3 is a protocol established by AWS that allows clients to upload files to so called "Buckets". A bucket is simply a folder, so, S3 allows you to upload files to folders.
However, folders are not really scalable if we're talking about millions of files. For that reason, AWS made an abstraction on top of distributed file systems that gives you "Buckets" which can be accessed over an HTTP API.
Nowadays, there are many Cloud Providers that implemented the S3 protocol, allowing you to use S3 without vendor lock-in.
Additionally, there's also Minio, also a storage service provider, which can be used as a S3 storage on premises or even on your local machine.
WunderGraph generates a type-safe client for your applications. Part of the client is a file upload handler which can talk to multiple buckets. Instead of binding a client to a specific S3 compatible instance, you're able to use different storages depending on the environment, you're running on.
E.g. you can use Minio on localhost and DigitalOcean spaces when running in production.
Additionally, you're able to swap storage providers or buckets without changing the client itself.
Note: Currently, you need to be authenticated to perform file uploads.
How does it work?
- Configure your S3 Bucket (see reference below for more info)
- Use the generated Client to upload files
It's that easy! Here's an example using a generated TypeScript client with React. It contains a basic form with the input type "file". On submit, we're creating a FormData object with all the files submitted and upload them to the S3 bucket you've configured, done. Btw. , this works with any environment that can send FormData using HTTP Requests.
Configuring upload profiles
Additionally, S3 uploads support defining different profiles with limits and an optional metadata schema. Start by adding your profiles to your
After you define profiles for a given storage provider, you must indicate the profile name when performing an upload. For example, to use the
avatar profile use:
When using a profile with required metadata,
upload() argument will also need to include a properly defined
metadata field, accoding to its schema.
Uploads by anonoymous users
By default, WunderGraph requires authentication in order to upload files. However, this requirement can be configured on a per-profile basis. Each profile takes an optional
requireAuthentication field, which defaults to
true. If you want to accept uploads from users without authenticating them first, declare your profile using:
This will allow anonymous users to upload files. If you want to enable this behavior based on some additional logic, set
false and then implement your additional logic using the
preUpload hook documented below.
Upload profiles also allow you to define hooks that will be run before and after the upload. The
preUpload hook will run before the upload, allowing you to perform any required validation as well as defining the path to store the file. There's also a
postUpload hook which runs after the upload completes or fails (the
error argument indicates that). To use upload hooks, define them in your
Learn more on how to configure and use your S3 storage with WunderGraph in the reference.