@gw-intech/upload-it

UploadIt

A flexible and reusable file upload library with support for S3 and filesystem storage.

Features

• 📤 Direct client-side uploads to S3
• 💾 Local filesystem support
• 🔒 Secure server-side credential handling
• 📊 Upload progress tracking
• 🔄 Automatic URL refreshing
• ⚛️ React components and hooks
• 📱 Next.js integration
• 🔌 Provider-based architecture
• 📂 File management utilities
• 📑 Intuitive file listing with icons

Latest Updates (v0.3.6)

• 🎨 Enhanced FileList component with file type icons - Beautiful visual indicators for different file types
• 🖼️ Option to display file icons instead of image previews - More consistent UI and better performance
• 🗂️ File management utilities - Easy-to-use functions for listing, fetching, and deleting files
• 🔄 Improved filesystem integration - Better fallbacks for direct filesystem operations

Installation

npm install @gw-intech/upload-it
# or
yarn add @gw-intech/upload-it
# or
pnpm add @gw-intech/upload-it

Browser Compatibility

The library is designed to work in both browser and Node.js environments:

• S3 Provider: Fully supported in browsers
• Filesystem Provider: Only for server-side use (Node.js)

When using the library in client-side applications (like Vite, Create React App, etc.), you should:

1. Use the S3 provider for direct client-side uploads
2. Or set up server endpoints for secure uploads

// ✅ Works in browsers
import { UploadButton } from '@gw-intech/upload-it';

function App() {
  return (
    <UploadButton
      provider='s3'
      s3={{
        region: 'us-east-1',
        bucket: 'my-bucket',
        credentials: {
          // For development only! Use server mode in production
          accessKeyId: '...',
          secretAccessKey: '...',
        },
      }}
    />
  );
}

// ❌ Won't work in browsers - filesystem requires Node.js
import { UploadButton } from '@gw-intech/upload-it';

function App() {
  return (
    <UploadButton
      provider='filesystem' // ⚠️ This won't work in browsers
      filesystem={{
        uploadDir: './public/uploads',
        publicPath: '/uploads',
      }}
    />
  );
}

Usage

Basic Usage with React Component

import { UploadButton } from '@gw-intech/upload-it';

function MyApp() {
  return (
    <UploadButton
      provider='s3'
      s3={{
        region: 'us-east-1',
        bucket: 'my-bucket',
        credentials: {
          /* For development only! See secure usage below */
        },
      }}
      onUploadComplete={(files) => console.log('Uploaded files:', files)}
      multiple={true}
      accept='image/*,.pdf'
    />
  );
}

Secure Usage with Next.js

When using Next.js, you'll need to import the server-specific routes from the /server subpath:

1. Create API routes for uploads:

// app/api/upload/presigned/route.ts
import { presignedUrlRoute } from '@gw-intech/upload-it/server';
export { presignedUrlRoute as POST };

// app/api/upload/complete/route.ts
import { completeUploadRoute } from '@gw-intech/upload-it/server';
export { completeUploadRoute as POST };

// app/api/upload/url/[fileKey]/route.ts
import { getFileUrlRoute } from '@gw-intech/upload-it/server';
export { getFileUrlRoute as GET };

2. Configure environment variables:

UPLOAD_IT_S3_REGION=us-east-1
UPLOAD_IT_S3_BUCKET=my-bucket
UPLOAD_IT_S3_ACCESS_KEY=your-access-key
UPLOAD_IT_S3_SECRET_KEY=your-secret-key
UPLOAD_IT_S3_FOLDER=uploads

3. Use the component with server mode:

import { UploadButton } from '@gw-intech/upload-it';

function MyApp() {
  return (
    <UploadButton
      provider='s3'
      server={{
        mode: 'server',
        endpoints: {
          getUploadUrl: '/api/upload/presigned',
          completeUpload: '/api/upload/complete',
          getAccessUrl: '/api/upload/url',
        },
      }}
      onUploadComplete={(files) => console.log('Uploaded files:', files)}
    />
  );
}

Using with Vite or non-Next.js environments

When using Vite or other build systems, you only need to import from the main package:

import {
  UploadButton,
  useUploader,
  createUploader,
} from '@gw-intech/upload-it';

The Next.js specific routes are isolated in the /server subpath to avoid dependency conflicts.

Using the React Hook

import { useUploader } from '@gw-intech/upload-it';
import { useState } from 'react';

function MyUploader() {
  const [files, setFiles] = useState([]);

  const uploader = useUploader({
    provider: 's3',
    s3: {
      region: 'us-east-1',
      bucket: 'my-bucket',
      credentials: {
        /* ... */
      },
    },
    onSuccess: (uploadedFiles) => {
      setFiles(uploadedFiles);
    },
  });

  const handleFileChange = async (e) => {
    const selectedFiles = e.target.files;
    if (selectedFiles.length > 0) {
      await uploader.uploadFiles(Array.from(selectedFiles));
    }
  };

  return (
    <div>
      <input type='file' multiple onChange={handleFileChange} />
      {uploader.isUploading && (
        <div>
          Uploading... {Object.values(uploader.progress)[0]?.percentage}%
        </div>
      )}
      {files.map((file) => (
        <div key={file.key}>
          {file.name} -{' '}
          <a href={file.url} target='_blank' rel='noopener noreferrer'>
            View
          </a>
        </div>
      ))}
    </div>
  );
}

Filesystem Storage

import { UploadButton } from '@gw-intech/upload-it';

function MyApp() {
  return (
    <UploadButton
      provider='filesystem'
      filesystem={{
        uploadDir: './public/uploads',
        publicPath: '/uploads',
      }}
      onUploadComplete={(files) => console.log('Uploaded files:', files)}
    />
  );
}

Core API (Non-React)

import { createUploader } from '@gw-intech/upload-it';

const uploader = createUploader({
  provider: 's3',
  s3: {
    region: 'us-east-1',
    bucket: 'my-bucket',
    credentials: {
      /* ... */
    },
  },
  onUploadProgress: (file, progress) => {
    console.log(`${file.name}: ${progress.percentage}%`);
  },
});

async function uploadFile(file) {
  try {
    const result = await uploader.uploadFile(file);
    console.log('File uploaded:', result);
    return result;
  } catch (error) {
    console.error('Upload failed:', error);
  }
}

Component Props

UploadButton Props

The UploadButton component accepts the following props:

Core Configuration

Prop	Type	Required	Description
provider	's3' | 'filesystem'	Yes	Storage provider to use
s3	S3Config	Only with s3 provider	S3 configuration
filesystem	FilesystemConfig	Only with filesystem provider	Filesystem configuration
server	ServerConfig	No	Server configuration for secure mode
maxFileSize	number	No	Maximum file size in bytes
allowedFileTypes	string[]	No	Allowed file types (e.g., ['image/*', '.pdf'])

UI Customization

Prop	Type	Required	Default	Description
className	string	No	''	CSS class applied to the button
buttonText	string	No	'Upload'	Text displayed on the button
children	React.ReactNode	No	null	Content to render inside the button
showProgressDialog	boolean	No	true	Whether to show the progress dialog
dialogTitle	string	No	'Upload File'	Title for the progress dialog

Upload Options

Prop	Type	Required	Default	Description
multiple	boolean	No	false	Allow multiple file selection
accept	string	No	undefined	File type filter (e.g., "image/*,.pdf")
folder	string	No	undefined	Optional folder path for uploaded files

Callbacks

Prop	Type	Required	Description
onSuccess	(files: FileMetadata[]) => void	No	Called when uploads complete successfully
onError	(error: Error) => void	No	Called when an error occurs

Advanced Customization

Prop	Type	Required	Description
renderButton	(props: { onClick: () => void; isUploading: boolean }) => React.ReactNode	No	Custom button rendering
renderDialog	(props: { isOpen: boolean; onClose: () => void; progress: number; isComplete: boolean; hasErrors: boolean; }) => React.ReactNode	No	Custom dialog rendering

Configuration Options

Common Options

Option	Type	Description
provider	's3' | 'filesystem'	Storage provider to use
maxFileSize	number	Maximum file size in bytes
allowedFileTypes	string[]	Allowed file types (e.g., ['image/*', '.pdf'])

S3 Provider Options

Option	Type	Description
region	string	AWS region
bucket	string	S3 bucket name
credentials	{ accessKeyId: string, secretAccessKey: string }	AWS credentials
endpoint	string	Custom endpoint (for S3-compatible storage)
uploadFolder	string	Folder prefix for uploaded files

Filesystem Provider Options

Option	Type	Description
uploadDir	string	Directory to store uploaded files
publicPath	string	Public URL path to access files
createDirIfNotExist	boolean	Create directory if it doesn't exist

Server Options

Option	Type	Description
mode	'client' | 'server'	Whether to use client or server mode
endpoints	{ getUploadUrl?: string, completeUpload?: string, getAccessUrl?: string }	API endpoints for server operations

License

MIT