No accounts. No trackers. Zero friction.
Drag, drop, set auto-expiration, generate QR codes, and share files with cryptographic SHA-256 verification in milliseconds.
Key Features β’ Architecture β’ Directory Structure β’ Getting Started β’ Deployment β’ Keyboard Shortcuts
Ferry is a sleek, privacy-first web application designed for fast, hassle-free ephemeral file transfers. Built with modern web primitives, Ferry bridges the gap between quick scratchpad uploads and enterprise-grade file management without forcing users through a login wall.
Whether sending an APK to an Android TV, sharing a large PDF document with a classmate, or generating a temporary download link with a countdown timer, Ferry handles uploads up to 100 MB with multi-provider redundancy, real-time speed monitoring, cryptographic verification, and instant mobile handoff.
- Zero Registration: Start uploading immediately. No email, password, or OAuth required.
- Up to 100 MB per File: Upload documents, videos, source code archives, firmware, and images.
- Auto-Expiration Policies: Pick custom lifespans:
1 Hour,6 Hours,24 Hours,48 Hours, orForever (β)(provider-dependent).
Ferry integrates with battle-tested storage hosts with automated fallback and provider selection:
tmpfiles.org: Ultra-fast temporary file hosting with automated timed expiration (1h to 48h).OnlyFiles: High-capacity hosting with permanent storage options, 500 uploads/hr, and 5,000 uploads/day limits.
- SHA-256 Fingerprinting: Calculates cryptographic file hashes locally using the Web Crypto API (
crypto.subtle.digest) before and during transmission. - Data Integrity: Guarantees that downloaded content matches the exact byte sequence uploaded.
- Real-time QR Codes: Generates high-contrast QR codes directly in the browser using the
qrcodeengine. - Seamless Cross-Device Sharing: Scan from your phone or tablet camera to instantly trigger the download without copy-pasting long URLs.
- Concurrent Chunked Queue: Queue multiple files simultaneously with distinct lifecycle stages:
QueuedβPreparingβUploadingβDone. - Telemetry & Speed Meter: Live transfer rate calculation (MB/s or KB/s), byte counters, upload progress bars, and ETA calculations.
- Actionable Controls: Cancel in-flight transfers, retry failed uploads, or copy URLs instantly upon completion.
- 100% Client-Side History: Upload history is persisted in
localStorage. Nothing is tracked on external analytics servers. - Metadata & Organization: Add custom labels, markdown notes, tags, and bookmark important files (
Pinned). - Category Auto-Detection: Automatically sorts files into
Image,Video,Audio,Document,Archive,Code, andOther. - Export & Import: Export your full file ledger to JSON or restore it on any device.
- Global modal palette with fuzzy search across all active and historic uploads, quick navigation, provider switching, and batch actions.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Client Browser β
β β
β [File Drop] ββββΊ [Web Crypto API] ββββΊ SHA-256 Digest β
β β β
β βΌ β
β [Upload Queue Manager (XHR + Progress Event)] β
β β β
β ββββΊ Provider: tmpfiles.org (1h - 48h) β
β ββββΊ Provider: OnlyFiles (Permanent / Multi-tier) β
β β
β [Response Parser] βββΊ Direct CDN Download Link β
β β β
β ββββΊ [QR Generator] (Canvas/SVG for mobile) β
β ββββΊ [Local Storage Ledger] (Tags, notes, expiry) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- Local Intake: When files are dropped, Ferry extracts MIME metadata, computes local preview thumbnails (for images/videos), and calculates the SHA-256 checksum in an asynchronous worker thread.
- Streaming Dispatch: Uses native
XMLHttpRequestto allow granular byte-level upload progress tracking, upload speed computation, and network cancellation triggers. - Ledger Update: Upon receiving
200 OK, Ferry registers the remote URL in the local store along with expiration timestamps.
web/Ferry/
βββ public/ # Static public assets & icons
βββ src/
β βββ assets/ # Vector graphics and bundled illustrations
β βββ components/ # Modular UI component tree
β β βββ CommandPalette.tsx # βK power-user search and action menu
β β βββ FileDrawer.tsx # Slide-over inspector for file details, QR & notes
β β βββ FileVisual.tsx # Dynamic file type icons and thumbnail renderer
β β βββ Header.tsx # Navigation bar, live stats badge & palette trigger
β β βββ HowItWorks.tsx # Explanatory onboarding accordion and guide
β β βββ Library.tsx # History view with category tabs, search & filters
β β βββ Stats.tsx # Aggregate usage telemetry (total MB, active files)
β β βββ UploadPanel.tsx # Drag-and-drop zone, expiry selectors & queue view
β βββ lib/ # Core business logic & utilities
β β βββ format.ts # Human-readable file sizes, speeds, countdowns
β β βββ hooks.ts # Custom React hooks (interval timers, keyboard)
β β βββ media.ts # Client-side thumbnail generator & image dimensions
β β βββ providers.ts # Storage provider definitions (tmpfiles, onlyfiles)
β β βββ search.ts # Multi-field filtering and fuzzy search logic
β β βββ store.tsx # React Context & LocalStorage state persistence
β β βββ types.ts # Strong TypeScript interfaces & constants
β β βββ ui.tsx # Toast notifications & theme providers
β β βββ upload.ts # Native XHR file dispatch and progress tracking
β βββ App.tsx # Main layout container and view coordinator
β βββ index.css # Tailwind CSS v4 directives and design tokens
β βββ main.tsx # Application bootstrap entry point
βββ eslint.config.js # ESLint flat config with TypeScript rules
βββ index.html # Single Page Application HTML5 entry point
βββ package.json # Dependencies, scripts and package metadata
βββ tsconfig.json # TypeScript compiler configuration root
βββ tsconfig.app.json # App-specific TS rules
βββ tsconfig.node.json # Node/Vite specific TS rules
βββ vite.config.ts # Vite 7 build configuration with Tailwind plugin
- Node.js:
v20.xor later (tested on Node v22) - Package Manager:
npm,pnpm, orbun
-
Navigate to the project directory:
cd /home/code/projects/web/Ferry -
Install dependencies:
npm install # or pnpm install -
Start the development server:
npm run dev
The application will be live at
http://localhost:5173.
| Command | Description |
|---|---|
npm run dev |
Starts Vite development server with Hot Module Replacement (HMR). |
npm run build |
Compiles TypeScript and builds production-optimized static bundle to dist/. |
npm run preview |
Previews the production build locally via Cloudflare Wrangler dev server. |
npm run lint |
Runs ESLint 9 checks across all source files. |
npm run deploy |
Builds the project and deploys directly to Cloudflare Pages via Wrangler. |
Ferry is pre-configured with @cloudflare/vite-plugin and wrangler for seamless edge hosting.
# 1. Login to Cloudflare
npx wrangler login
# 2. Build and deploy
npm run deployAlternatively, push to GitHub and link the repository in the Cloudflare Pages Dashboard:
- Framework Preset:
Vite - Build Command:
npm run build - Build Output Directory:
dist
| Shortcut | Action |
|---|---|
βK / Ctrl+K |
Open / Close Command Palette |
Esc |
Close slide-over drawer / Command Palette |
U |
Scroll to upload panel & focus file picker |
L |
Jump to files library |
- Ferry does not route files through proprietary proxy servers. Uploads stream directly from the user's browser to the selected hosting provider.
- File records, notes, tags, and pinned statuses live exclusively in the user's local browser storage (
localStorage). Clearing browser cache purges the local ledger completely.