@pol-studios/storage

Storage utilities for POL applications

Supabase storage integration with hooks for file uploads, URL management, and dropzone functionality. Uses tus-js-client for resumable uploads.

Installation

pnpm add @pol-studios/storage

Peer Dependencies

pnpm add react @tanstack/react-query @supabase/supabase-js react-dropzone @pol-studios/db @pol-studios/utils

Quick Start

import { useUpload, useUrl, useDropzoneUpload, BUCKETS } from "@pol-studios/storage";

function FileUploader() {
  const { upload, isUploading, progress } = useUpload({
    bucket: BUCKETS.documents,
  });

  const handleUpload = async (file: File) => {
    const result = await upload(file, "documents/my-file.pdf");
    console.log("Uploaded:", result);
  };

  return (
    <div>
      <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
      {isUploading && <progress value={progress} max={100} />}
    </div>
  );
}

Subpath Exports

| Path | Description | |------|-------------| | @pol-studios/storage | All exports (hooks, types, config) | | @pol-studios/storage/hooks | Upload hooks (useUpload, useUrl, usePath, useDropzoneUpload) | | @pol-studios/storage/types | TypeScript type definitions | | @pol-studios/storage/config | Bucket configuration (BUCKETS) |

API Reference

Hooks

useUpload

Upload files to Supabase storage.

import { useUpload, useUploadWithEntity } from "@pol-studios/storage/hooks";

const { upload, isUploading, progress, error } = useUpload({
  bucket: "documents",
  onSuccess: (result) => console.log("Uploaded:", result),
  onError: (error) => console.error("Failed:", error),
});

// Upload a file
await upload(file, "path/to/file.pdf");

// Upload with entity association
const { upload: uploadWithEntity } = useUploadWithEntity({
  bucket: "attachments",
  entityType: "project",
  entityId: projectId,
});

useUrl

Get signed URLs for storage objects.

import { useUrl } from "@pol-studios/storage/hooks";

const { getUrl, url, isLoading } = useUrl({
  bucket: "documents",
  path: "files/document.pdf",
  expiresIn: 3600, // 1 hour
});

// Or manually fetch URL
const signedUrl = await getUrl("another/path.pdf");

usePath

Manage storage paths.

import { usePath } from "@pol-studios/storage/hooks";

const { path, setPath, fullPath } = usePath({
  bucket: "uploads",
  basePath: "users/123",
});

useDropzoneUpload

Integrate with react-dropzone for drag-and-drop uploads.

import { useDropzoneUpload } from "@pol-studios/storage/hooks";

function DropzoneUploader() {
  const {
    getRootProps,
    getInputProps,
    isDragActive,
    files,
    upload,
    isUploading,
    progress,
  } = useDropzoneUpload({
    bucket: "uploads",
    accept: { "image/*": [".png", ".jpg", ".jpeg"] },
    maxFiles: 5,
    maxSize: 10 * 1024 * 1024, // 10MB
  });

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      {isDragActive ? (
        <p>Drop files here...</p>
      ) : (
        <p>Drag files here or click to select</p>
      )}
      {isUploading && <progress value={progress} max={100} />}
    </div>
  );
}

Configuration

BUCKETS

Pre-defined bucket names.

import { BUCKETS } from "@pol-studios/storage/config";

// Available buckets
BUCKETS.documents;
BUCKETS.images;
BUCKETS.attachments;
// ... etc

TypeScript Types

import type {
  // Upload types
  StorageUploadMetadata,
  StorageObjectMetadata,
  UploadInput,
  UploadResult,
  UseUploadOptions,

  // Attachment types
  Attachment,
  CachedUrl,

  // Path types
  UsePathOptions,
  UsePathResult,

  // Hook return types
  UseSupabaseUploadOptions,
  UseSupabaseUploadReturn,

  // Config types
  BucketName,
} from "@pol-studios/storage";

Features

Resumable Uploads

Uses tus-js-client for resumable uploads, allowing large file uploads to continue after network interruptions.

const { upload } = useUpload({
  bucket: "large-files",
  resumable: true, // Enable resumable uploads
  chunkSize: 6 * 1024 * 1024, // 6MB chunks
});

Progress Tracking

Track upload progress in real-time.

const { progress, bytesUploaded, totalBytes } = useUpload({
  bucket: "uploads",
  onProgress: ({ percentage, bytesUploaded, totalBytes }) => {
    console.log(`${percentage}% uploaded`);
  },
});

Entity Association

Associate uploads with database entities.

const { upload } = useUploadWithEntity({
  bucket: "attachments",
  entityType: "project",
  entityId: "project-123",
  onSuccess: (result) => {
    // result includes entity association metadata
  },
});

Related Packages

• @pol-studios/db - Database utilities and Supabase client
• @pol-studios/utils - Utility functions
• @pol-studios/ui - UI components including file dropzone

License

UNLICENSED