Repository: kern/filepizza

Stars: 9999

.cursorrules Copy Chapter

- Use TypeScript.
- Use function syntax for defining React components. Define the prop types inline.
- If a value is exported, it should be exported on the same line as its definition.
- Always define the return type of a function or component.
- Use Tailwind CSS for styling.
- Don't use trailing semicolons.

CLAUDE.md Copy Chapter

FilePizza Development Guide

A peer-to-peer file transfer application built with modern web technologies.

Prerequisites Copy Chapter

- Node.js (v18+)
- pnpm (preferred package manager)

Quick Start Copy Chapter

git clone https://github.com/kern/filepizza.git
cd filepizza
pnpm install
pnpm dev

Available Commands Copy Chapter

Development Copy Section

Building & Testing Copy Section

Code Quality Copy Section

Docker Copy Section

CI Pipeline Copy Section

Tech Stack Copy Chapter

- Framework: Next.js 15 with App Router
- UI: React 19 + Tailwind CSS v4
- Language: TypeScript
- Testing: Vitest (unit) + Playwright (E2E)
- WebRTC: PeerJS
- State Management: TanStack Query
- Themes: next-themes with View Transitions
- Storage: Redis (optional)

Project Structure Copy Chapter

src/
├── app/                    # Next.js App Router pages
├── components/             # React components
├── hooks/                  # Custom React hooks
├── utils/                  # Utility functions
└── types.ts               # TypeScript definitions

Development Tips Copy Chapter

Using pnpm Copy Section

This project uses pnpm as the package manager. Benefits include:
- Faster installs and smaller disk usage
- Strict dependency resolution
- Built-in workspace support

Always use pnpm instead of npm or yarn:

pnpm install package-name
pnpm remove package-name
pnpm update

Code Style Copy Section

- ESLint + TypeScript ESLint for linting
- Prettier for formatting
- Husky + lint-staged for pre-commit hooks
- Prefer TypeScript over JavaScript
- Use kebab-case for files, PascalCase for components

Testing Strategy Copy Section

- Unit tests for components and utilities (tests/unit/)
- E2E tests for critical user flows (tests/e2e/)
- Test files follow *.test.ts[x] naming convention

WebRTC Development Copy Section

For full WebRTC testing with TURN/STUN:

pnpm dev:full

This starts Redis and COTURN containers for testing peer connections behind NAT.

Key Dependencies Copy Chapter

- next - React framework
- tailwindcss - CSS framework
- @tanstack/react-query - Server state management
- peerjs - WebRTC abstraction
- next-themes - Theme switching
- zod - Schema validation
- vitest - Testing framework
- playwright - E2E testing

Run pnpm ci before submitting PRs to ensure all checks pass.

README.md Copy Chapter

<a href="https://xkcd.com/949/"><img src="http://imgs.xkcd.com/comics/file_transfer.png" alt="XKCD 949" width="30%" align="right" /></a> <img src="public/images/wordmark.png" alt="FilePizza wordmark" width="50%" /> <h3>Peer-to-peer file transfers in your browser</h3>

Cooked up by Alex Kern & Neeraj Baid while eating Sliver @ UC Berkeley.

Using WebRTC, FilePizza eliminates the initial upload step required by other web-based file sharing services. Because data is never stored in an intermediary server, the transfer is fast, private, and secure.

A hosted instance of FilePizza is available at file.pizza.

What's new with FilePizza v2 Copy Chapter

* A new UI with dark mode support, now built on modern browser technologies.
* Works on most mobile browsers, including Mobile Safari.
* Transfers are now directly from the uploader to the downloader's browser (WebRTC without WebTorrent) with faster handshakes.
* Uploaders can monitor the progress of the transfer and stop it if they want.
* Better security and safety measures with password protection and reporting.
* Support for uploading multiple files at once, which downloaders receive as a zip file.
* Streaming downloads with a Service Worker.
* Out-of-process storage of server state using Redis.

Development Copy Chapter

$ git clone https://github.com/kern/filepizza.git
$ pnpm install
$ pnpm dev
$ pnpm build
$ pnpm start

Running with Docker Copy Chapter

$ pnpm docker:build
$ pnpm docker:up
$ pnpm docker:down

Stack Copy Chapter

* Next.js
* Tailwind
* TypeScript
* React
* PeerJS for WebRTC
* View Transitions
* Redis (optional)

Configuration Copy Chapter

The server can be customized with the following environment variables:

- REDIS_URL – Connection string for a Redis instance used to store channel metadata. If not set, FilePizza falls back to in-memory storage.
- COTURN_ENABLED – When set to true, enables TURN support for connecting peers behind NAT.
- TURN_HOST – Hostname or IP address of the TURN server. Defaults to 127.0.0.1.
- TURN_REALM – Realm used when generating TURN credentials. Defaults to file.pizza.
- STUN_SERVER – STUN server URL to use when COTURN_ENABLED is disabled. Defaults to stun:stun.l.google.com:19302.
- PEERJS_HOST – Hostname or IP address to the self-hosted PeerJS server. Defaults to 0.peerjs.com.
- PEERJS_PATH – Path to self-hosted PeerJS server. Defaults to /.

FAQ Copy Chapter

How are my files sent? Your files are sent directly from your browser to the downloader's browser. They never pass through our servers. FilePizza uses WebRTC to send files. This requires that the uploader leave their browser window open until the transfer is complete.

Can multiple people download my file at once? Yes! Just send them your short or long URL.

How big can my files be? As big as your browser can handle.

What happens when I close my browser? The URLs for your files will no longer work. If a downloader has completed the transfer, that downloader will continue to seed to incomplete downloaders, but no new downloads may be initiated.

Are my files encrypted? Yes, all WebRTC communications are automatically encrypted using public-key cryptography because of DTLS. You can add an optional password to your upload for an extra layer of security.

License & Acknowledgements Copy Chapter

FilePizza is released under the BSD 3-Clause license. A huge thanks to iblowyourdesign for the pizza illustration.