izSend is a simple, self-hostable file sharing app with:
- Upload (max 50MB)
- Share via random slug link, short code, or QR
- Optional passcode (protects link, code, and QR)
- Auto-expiration after 7 days (expired objects are deleted from storage)
- Live site:
https://izsend.vercel.app/
- Features
- How it works
- Tech stack
- Repository layout
- Prerequisites
- Getting started (local dev)
- Configuration
- Scripts
- API reference
- Rate limiting
- Cleanup job (auto-delete)
- Deployment notes
- Troubleshooting
- Contributing
- License
- 3 share modes
- Slug link:
/f/:slug - Short code page:
/c/:code - QR code (encodes the slug link)
- Slug link:
- Optional passcode
- If set during upload, it is required to generate a download link (presigned URL)
- Passcodes are stored as a bcrypt hash (plaintext is never stored)
- Storage TTL
- File records expire after 7 days
- A background cleanup job deletes expired objects from S3-compatible storage
- Anti-spam
- IP-based rate limits on upload, metadata reads, and presign requests
- User uploads a file to the Fastify API (
POST /api/files). - The API streams the bytes to S3-compatible storage and stores metadata in Neon Postgres.
- The UI shows:
- Slug link (
/f/:slug) - Short code (
/c/:code) - QR code (points to
/f/:slug)
- Slug link (
- On the download page, the browser requests a presigned URL from the API (
POST /api/files/:id/presign). - The API validates expiration + passcode (if required) and returns a short-lived presigned URL.
- The browser downloads the file directly from S3-compatible storage.
This keeps the API lightweight for downloads while still allowing passcode enforcement at the “create download link” step.
- Backend: Node.js + TypeScript + Fastify
- Database: Neon Postgres (
pgclient) - Object storage: S3-compatible (AWS S3 / Cloudflare R2 / MinIO)
- Frontend: React + Vite + React Router
- QR:
qrcode.react
.
├─ apps/
│ ├─ api/ # Fastify API (upload, metadata, presign, cleanup job)
│ └─ web/ # React UI (upload page, download pages)
├─ docs/ # Design notes
├─ .env.example # Backend env example (repo root)
└─ README.md
- Node.js 20+ (Node 22 recommended)
- An S3-compatible bucket (AWS S3 / Cloudflare R2 / MinIO)
- A Neon Postgres connection string
npm installThe API reads environment variables from repo root .env.
cp .env.example .envThen edit .env (see Configuration).
npm run db:initThis runs apps/api/scripts/dbInit.ts and executes apps/api/sql/schema.sql on your Neon database.
npm run dev- Web:
http://localhost:5173 - API:
http://localhost:3000
Copy .env.example to .env and fill in the values:
| Variable | Required | Default | Description |
|---|---|---|---|
API_PORT |
no | 3000 |
API port |
WEB_ORIGIN |
no | http://localhost:5173 |
Allowed CORS origin for the web app |
PRESIGN_TTL_SECONDS |
no | 300 |
Presigned download URL TTL (seconds) |
FILE_TTL_DAYS |
no | 7 |
File expiration (days) |
CLEANUP_INTERVAL_MINUTES |
no | 60 |
Cleanup job interval (minutes) |
AWS_ACCESS_KEY_ID |
yes | - | S3 credentials |
AWS_SECRET_ACCESS_KEY |
yes | - | S3 credentials |
AWS_REGION |
yes | - | S3 region (or auto for some providers) |
S3_BUCKET |
yes | - | Bucket name |
S3_ENDPOINT |
no | - | Custom S3 endpoint (R2/MinIO) |
S3_FORCE_PATH_STYLE |
no | false |
Use path-style addressing (often required for MinIO) |
NEON_CONNECTION_STRING |
yes | - | Neon Postgres connection string |
Upload size limit: hard-capped at 50MB in apps/api/src/env.ts.
In production you typically do not ship a .env file. Set environment variables in your host (e.g. Render).
- Production template:
.env.production.example(do not put secrets in git) - The API code reads
process.envand will work without a.envfile
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=ap-southeast-1
S3_BUCKET=your-bucket
S3_ENDPOINT=
S3_FORCE_PATH_STYLE=falseAWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=auto
S3_BUCKET=your-bucket
S3_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com
S3_FORCE_PATH_STYLE=trueAWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_REGION=us-east-1
S3_BUCKET=izsend
S3_ENDPOINT=http://localhost:9000
S3_FORCE_PATH_STYLE=trueCopy apps/web/.env.example if needed:
cp apps/web/.env.example apps/web/.env| Variable | Required | Default | Description |
|---|---|---|---|
VITE_API_BASE_URL |
no | http://localhost:3000 |
Base URL for the API |
On Vercel, set:
VITE_API_BASE_URL= your deployed API URL (Render)
Production template: apps/web/.env.production.example
From repo root:
| Command | What it does |
|---|---|
npm run dev |
Runs API + Web together |
npm run dev:api |
Runs only the API |
npm run dev:web |
Runs only the web app |
npm run db:init |
Initializes Postgres schema (Neon) |
npm run build |
Builds API + Web |
npm run start |
Starts the API from apps/api/dist |
Base URL: http://localhost:3000
Multipart form:
file(required)passcode(optional, 4–64 chars)
Response (shape):
{
"id": "uuid",
"slug": "string",
"code": "string",
"originalName": "string",
"contentType": "string",
"sizeBytes": 123,
"expiresAt": "2026-01-01T00:00:00.000Z",
"requiresPasscode": false,
"share": { "slugPath": "/f/...", "codePath": "/c/..." }
}Returns public metadata for the file (404 if not found, 410 if expired).
Returns public metadata for the file by short code (code is uppercased server-side).
Request:
{ "passcode": "optional" }Response:
{ "url": "https://..." }Common errors:
401 { "error": "Passcode required" }403 { "error": "Invalid passcode" }410 { "error": "Expired" }404 { "error": "Not found" }
The API uses @fastify/rate-limit and applies limits per route:
POST /api/files: 10/min (stricter)GET /api/files/*: 120/minPOST /api/files/:id/presign: 60/min
You can adjust limits in apps/api/src/routes/files.ts.
The API runs a periodic cleanup job (apps/api/src/jobs/cleanupExpired.ts) that:
- Finds records where
expires_at < now()anddeleted_at IS NULL - Deletes the object from S3-compatible storage
- Sets
deleted_at = now()
It runs once on startup and then every CLEANUP_INTERVAL_MINUTES (default: 60).
This repo does not include Docker manifests yet. A common setup is:
- Backend on Render:
apps/api - Frontend on Vercel:
apps/web - S3-compatible object storage + Neon Postgres
Minimum production checklist:
- Keep
.envout of git (already in.gitignore) - Use a dedicated S3 bucket with least-privilege credentials
- Set
WEB_ORIGINto your real frontend URL (Vercel origin) - Consider tightening rate limits
- Deploy API to Render
- Build:
npm ci && npm run build --workspace apps/api - Start:
npm run start --workspace apps/api - Set env vars (see
.env.production.example)
- Deploy Web to Vercel
- Root directory:
apps/web - Set
VITE_API_BASE_URLto your Render API URL - Ensure SPA rewrites are enabled for React Router (this repo includes
apps/web/vercel.json)
- Update API CORS
- Set Render
WEB_ORIGINto your Vercel URL
Tip: you can keep a personal deploy checklist in
docs/DEPLOY_PRIVATE.md(gitignored).
The API reads .env from the repo root. Ensure .env exists and is populated.
If S3 upload fails, the API will not insert a DB record. Check API logs first.
This usually means region/endpoint mismatch.
- AWS S3: verify
AWS_REGIONmatches the bucket region - R2/MinIO: set
S3_ENDPOINTand oftenS3_FORCE_PATH_STYLE=true
Upload is capped at 50MB (Fastify multipart limit).
The API returns 403 Invalid passcode. The UI surfaces this as an error message on the download page.
Issues and PRs are welcome. Keep changes focused and avoid adding secrets to the repo.
No license file is included yet. If you’re open-sourcing this, add a LICENSE (MIT/Apache-2.0/GPL/etc.) and reference it here.


