Simple S3 Upload Util

A simple and lightweight utility for uploading files to AWS S3 with environment variable configuration.

Installation

npm install simple-s3-upload-util

Setup

1. Create a .env file in your project root:

AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here
AWS_REGION=us-east-1
AWS_BUCKET_NAME=your-bucket-name

2. Make sure to add .env to your .gitignore file to keep your credentials secure.

Usage

Basic Usage

const SimpleS3UploadUtil = require('simple-s3-upload-util');

// Initialize with environment variables
const uploader = new SimpleS3UploadUtil();

// Upload a single file
async function uploadExample() {
  const result = await uploader.uploadFile('./path/to/your/file.jpg');
  console.log(result);
}

uploadExample();

Advanced Usage

const SimpleS3UploadUtil = require('simple-s3-upload-util');

// Initialize with custom options (overrides .env)
const uploader = new SimpleS3UploadUtil({
  region: 'us-west-2',
  bucketName: 'my-custom-bucket'
});

// Upload with custom S3 key
const result = await uploader.uploadFile('./image.jpg', 'uploads/my-image.jpg');

// Upload with additional S3 options
const result = await uploader.uploadFile('./file.pdf', 'documents/file.pdf', {
  ServerSideEncryption: 'AES256',
  Metadata: {
    'uploaded-by': 'my-app'
  }
});

Upload Multiple Files

const files = [
  { filePath: './image1.jpg', key: 'images/image1.jpg' },
  { filePath: './document.pdf', key: 'docs/document.pdf' },
  { filePath: './data.json' } // Uses filename as key
];

const results = await uploader.uploadFiles(files);
console.log(results);

API Reference

Constructor

new SimpleS3UploadUtil(options)

Options:

• region (string): AWS region (default: process.env.AWS_REGION or 'us-east-1')
• accessKeyId (string): AWS access key (default: process.env.AWS_ACCESS_KEY_ID)
• secretAccessKey (string): AWS secret key (default: process.env.AWS_SECRET_ACCESS_KEY)
• bucketName (string): S3 bucket name (default: process.env.AWS_BUCKET_NAME)

Methods

uploadFile(filePath, key?, options?)

Upload a single file to S3.

Parameters:

• filePath (string): Local path to the file
• key (string, optional): S3 key for the file. Defaults to filename
• options (object, optional): Additional S3 PutObject parameters

Returns: Promise resolving to upload result object

uploadFiles(files, options?)

Upload multiple files to S3.

Parameters:

• files (array): Array of file objects { filePath, key? }
• options (object, optional): Additional S3 PutObject parameters

Returns: Promise resolving to array of upload results

setBucket(bucketName)

Change the target S3 bucket.

Parameters:

• bucketName (string): New bucket name

Response Format

Successful upload:

{
  success: true,
  key: "uploads/file.jpg",
  bucket: "my-bucket",
  location: "https://my-bucket.s3.us-east-1.amazonaws.com/uploads/file.jpg",
  etag: "\"abc123...\"",
  versionId: "version123" // Only if versioning is enabled
}

Failed upload:

{
  success: false,
  error: "Error message"
}

Requirements

• Node.js 14+
• AWS S3 bucket with appropriate permissions
• AWS credentials with S3 upload permissions

License

MIT