About

The S3 File Storage API module provides a secure and efficient solution for storing files of any size directly in an AWS S3 bucket. This module requires an existing AWS account and aims to facilitate seamless integration with minimal configuration.

Installation

To add the S3 File Storage Module to your project, run:

npx vratix add upload-to-s3

.env

Add the following environment variables to your .env file:

• S3_BUCKET_NAME: The S3 bucket where files will be stored
  • Default: None (required)
  • Example: S3_BUCKET_NAME=my-s3-bucket
• S3_BUCKET_REGION: The AWS Region of your S3 bucket
  • Default: None (required)
  • Example: S3_BUCKET_REGION=us-east-1

Dependencies

This module will install the auth-basic API module for user authentication and the protectedRoute middleware.

Usage

To use this module, import the router from @/routes/storeFileS3.js into your entry point file (e.g., server.ts):

import { router as storeFileRouter } from "@/routes/storeFileS3.js";
 
app.use("/store-file", storeFileRouter);

Authentication

Note: Refer to the Node.js AWS SDK documentation for authentication best practices. The module automatically retrieves AWS credentials from your environment.

We reccomend you use AWS IAM Identity Center (SSO) for local development. After you complete the AWS SSO configuration you will need to update the SSO profile name in src/routes/storeFileS3.ts:

const s3Client = new S3Client({
  credentials: fromSSO({ profile: "your-sso-profile" }),
});

File Uploads

The module uses formidable for parsing and streaming files to S3. The file should be sent with multipart/form-data content type.

Each file is stored with a unique key in the format owner:${userId}_name:${fileName} to associate files with the uploading user. Returned file names are simplified to fileName only. You can adjust this logic as needed. NOTE: Make sure to include the file extension when specifying fileName.

Below is an example React component that allows users to upload files directly from a front-end form:

import React, { useState } from "react";
import axios from "axios";
 
function FileUpload() {
  const [file, setFile] = useState<File | null>(null);
 
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!file) return;
    const formData = new FormData();
    formData.append("file", file);
 
    await axios.post("/api/store-file/upload/${file.name}", formData, {
      headers: { "Content-Type": "multipart/form-data" },
    });
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <input
        type="file"
        onChange={(e) => setFile(e.target.files?.[0] || null)}
      />
      <button type="submit">Upload</button>
    </form>
  );
}
 
export default FileUpload;

Endpoints

The S3 File Storage Module exposes the following endpoints:

Errors

Below are common errors with solutions for this module:

Examples

To explore sample requests and responses, download our Postman collection:

API Collection