A simple, easy-to-understand demo showing how to use filecoin-pin to upload files to Filecoin. This single-page React + TypeScript app demonstrates the core upload workflow with progress tracking and wallet integration.
- filecoin-pin#45 for tracking when this will be publicly deployed to pin.filecoin.cloud.
- filecoin-pin-website#77 for tracking "bring your own wallet" support.
This app demonstrates the complete filecoin-pin upload workflow:
graph LR
A[Select File] --> B[Create CAR]
B --> C[Fund Filecoin Pay Account if Necessary]
C --> D[Upload to SP]
D --> E[IPNI Indexing]
E --> F[IPFS Mainnet Retrieval]
D --> G[Onchain Commitment]
G --> H[Direct from SP retrieval]
- Prepare - Create CAR files from user files
- Upload - Execute upload to Filecoin Storage Provider (SP)
- Index - Verify CID indexing and advertising from the SP to IPNI
- Commit - Verify the onchain commitment from the SP to perform proof of data possession (PDP)
- Track - Monitor progress through each step
The core integration logic is in src/hooks/use-filecoin-upload.ts and src/context/filecoin-pin-provider.tsx. Everything else is UI components. See CONTRIBUTING.md for detailed file structure.
- Node.js 18.0+ (Vite supports the active LTS releases)
- npm 9+ (bundled with Node)
npm install
npm run devVisit http://localhost:5173 to see the demo.
Available Scripts:
npm run dev– Start development servernpm run build– Build for productionnpm run lint– Check code qualitynpm run lint:fix– Fix linting issues
For environment configuration and authentication options, see CONTRIBUTING.md.
- Build Tool - Vite for dev server and bundling
- Framework - React 19 with modern JSX runtime
- Language - TypeScript with strict settings
- Code Quality - Biome for formatting, linting, and import hygiene
See CONTRIBUTING.md for source layout and coding guidelines.
This demo currently doesn't support users bringing their own wallet, which is tracked in issue #77. Instead it relies on deployment with a shared session key, allowing multiple users to safely upload files using the same wallet.
How it works:
- Session key authentication – Uses
VITE_WALLET_ADDRESS+VITE_SESSION_KEYinstead of exposing the wallet's private key - Per-user data sets – Each user gets their own data set ID, stored in browser localStorage
- Data set persistence – Returning users automatically reconnect to their existing data set
- Upload history – Users can view their uploaded files (fetched from their data set on-chain)
User isolation:
- All users share the same wallet (via session key)
- Each user's browser stores their unique data set ID
- Users only see pieces from their own data set
Important: This approach relies on browser localStorage for user identity, which is fine for demos but not suitable for production.
During the pre-product development window we hardcode a small allowlist of "known good" storage providers and randomly pick from it when a provider is not specified via the providerId debug parameter. This is an expedient, temporary measure to smooth out early network volatility while we gather feedback and improve automated provider discovery. This allowlist will shift to onchain with filecoin-services#291. Outside the launch period you should remove the hardcoded IDs and rely on normal provider selection logic (inside filecoin-pin and underlying synapse-sdk) instead.
- Issues - Open issues in this repo if you see any problems with the demo dApp
- Community Discussion - Join the conversation in Filecoin Slack's public #fil-foc channel
- Live Demo Walkthrough - Step-by-step guide to using this demo
- Video Demo - Screen recording showing the dApp in action
- filecoin-pin Repository - Core library and CLI
- Filecoin Pin Documentation - Complete guides and tutorials
For contributing to this project, see CONTRIBUTING.md.