@howells/stow-client

Client-side SDK for Stow file storage. Upload files directly from the browser with progress tracking.

Installation

npm install @howells/stow-client
# or
pnpm add @howells/stow-client
# or
yarn add @howells/stow-client

Quick Start

import { StowClient } from "@howells/stow-client";

const stow = new StowClient("/api/upload");

// Upload a file from a file input
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const result = await stow.uploadFile(file, {
  onProgress: (progress) => {
    console.log(`Upload: ${progress.percent}%`);
  },
});

console.log(result.url);

Important: Server Endpoint Required

This SDK uploads files through your server endpoint, not directly to Stow. Your server should use @howells/stow-server to handle the actual upload. This keeps your API key secure.

Browser → Your Server (/api/upload) → Stow

See @howells/stow-next for easy Next.js integration.

API Reference

new StowClient(config)

Create a new client instance.

// Simple: just pass the endpoint
const stow = new StowClient("/api/upload");

// With config object
const stow = new StowClient({
  endpoint: "/api/upload",
});

uploadFile(file, options?)

Upload a single file with progress tracking.

const result = await stow.uploadFile(file, {
  route: "avatars", // optional folder/route
  onProgress: (progress) => {
    console.log(`${progress.loaded}/${progress.total} bytes (${progress.percent}%)`);
  },
});

// Result:
// {
//   key: "bucket-id/avatars/abc123.jpg",
//   url: "https://stow.sh/files/bucket-id/avatars/abc123.jpg",
//   size: 12345,
//   contentType: "image/jpeg"
// }

uploadFiles(files, options?)

Upload multiple files sequentially.

const results = await stow.uploadFiles(fileInput.files, {
  route: "gallery",
  onProgress: (progress) => {
    console.log(`Current file: ${progress.percent}%`);
  },
  onFileComplete: (result, index) => {
    console.log(`File ${index + 1} complete:`, result.url);
  },
  onFileError: (error, file, index) => {
    console.error(`File ${index + 1} failed:`, error.message);
  },
});

Error Handling

import { StowError } from "@howells/stow-client";

try {
  await stow.uploadFile(file);
} catch (error) {
  if (error instanceof StowError) {
    if (error.code === "ABORTED") {
      console.log("Upload was cancelled");
    } else {
      console.error(`Upload failed: ${error.message}`);
    }
  }
}

TypeScript

Full TypeScript support:

import type {
  StowClientConfig,
  UploadResult,
  UploadProgress,
  UploadOptions,
} from "@howells/stow-client";

Why XHR?

This SDK uses XMLHttpRequest instead of fetch because fetch doesn't support upload progress events. XHR's upload.onprogress is the only way to show real upload progress to users.

License

MIT