S3 Presigner

👋 Introduction

Welcome to the documentation for S3 Presigner, a powerful ⚡️ yet user-friendly 🐈 library that simplifies the process of uploading files to Amazon S3. Whether you're a seasoned developer or new to working with S3, this library aims to streamline your file uploading workflow and provide an intuitive API for integrating S3 file uploads into your applications.

🤨 Why

Maybe because you are looking for it 😎

You might be wondering why would you need S3 Presigner library to upload files to Amazon S3. You could directly upload the file to your backend application, process with multer or sharp then save it to Amazon S3 bucket or even to file system! 👉 This is a must read for you

🎉 Features

• Simplified File Upload: With S3 Presigner, you can effortlessly upload files to your Amazon S3 buckets without worrying about the complexities of managing low-level S3 operations. The library handles the authentication, request signing, and multipart upload process, allowing you to focus on building your application.

• Flexible Configuration: Customize your S3 upload behavior by configuring options such as bucket name, key prefix, access control permissions, and more. S3 Presigner provides a range of configurable parameters to suit your specific requirements.

• Minimum Configuration: Most of the time you may not need to customize the default behavior of the library. So, you will need only a few lines of code to get started.

📚 Guide

To implement the library follow the guide below. Both server and client side implementation is necessary for a smoother experience

Server Side Application

🎯 Installation

To get started with S3 Presigner, follow these simple installation steps:

npm install --save @s3-presigner/server

or

yarn add @s3-presigner/server

💅 Usage

You have to setup an endpoint where the client application will call to get the presigned URL and continue uploading the files.

For simplicity purpose we provide an example with REST API, but it is not necessary to be only a REST API, you can implement the library with GraphQL API as well as any other Node.js based framework

// ES6
import { createS3PresignedUrl } from "@s3-presigner/server";
// or, Common JS
const { createS3PresignedUrl } = require("@s3-presigner/server");

router.post('/presigned-url', async (req, res) => {
  // Here you can check whether the user have permission to call the API endpoint
  const { getUploadUrl } = createS3PresignedUrl({
     // To make uploaded files publically available by an url
    acl: "public-read",
    // `bucket` is the only required property
    bucket: "{YOUR_S3_BUCKET_NAME}",
    // `prefix` is used to organize bucket object by folder structure
    prefix: "{PREFIX_FOR_FILES}", // eg: `images` or `videos`
    // `configuration` object is optional if you have global env setup for aws credentials
    configuration: {
      region: "{YOUR_S3_BUCKET_REGION}",
      credentials: {
        accessKeyId: "{YOUR_AWS_ACCESS_KEY_ID}",
        secretAccessKey: "{YOUR_AWS_SECRET_ACCESS_KEY}",
      },
    },
  });
  // req.body contains information about files to be uploaded
  // provided by the client package --👇--
  const data = await getUploadUrl(req.body);

  return res.json({ data });
});

Read the API Documentation

Client Side Application

Works only with React for the time being

🎯 Installation

npm install --save @s3-presigner/client

or

yarn add @s3-presigner/client

💅 Usage

It can be used with any data fetching library or even without any. To make the examples simple, we have used @tanstack/react-query

import * as React from 'react';
import { useMutation } from "@tanstack/react-query";
import { useUploadFiles } from "@s3-presigner/client";

const { data, isLoading, onSelect } = useUploadFiles();

const { mutate } = useMutation({
  mutationFn: onSelect(async (input) => {
    // server api endpoint ---------👇---------
    const response = await fetch("/presigned-url", {
      method: "POST",
      body: JSON.stringify(input),
      headers: {
        "Content-Type": "application/json"
      }
    });
    if(!response.ok) throw new Error("Error msg for client");
    const result = await response.json();
    
    return result.data;
  })
});

const handleChange = (event) => {
  mutate(event.target.files);
};

return (
    <input type="file" multiple onChange={handleChange} />
)

Read the API Documentation

✅ Upcoming

Currently, the library can only handle uploading files to S3 bucket but it is also important to download files by presigned URL. That's the next goal along with some important features listed below

• Notify server after image successfully uploaded

🧑🏻‍💻 Contribution

Feel free to send a pull request for any improvement to the library. Don't forget to add emojies 🙌