scaffold-foc
Advanced tools
The fastest way to start building on Filecoin Onchain Cloud — scaffold a Next.js + Synapse SDK app with built-in setup checks
The production starter kit & CLI generator for Filecoin Onchain Cloud (FOC) applications.
Quick Start • Architecture • Script Suite • API Reference • SDK Integration
scaffold-foc is an official developer CLI that scaffolds a full-stack Next.js application pre-wired with Filecoin's Synapse SDK v1.x (@filoz/synapse-sdk).
Building decentralized storage apps on Filecoin traditionally requires complex wallet configuration, token deposits, operator approvals, gas management, and storage provider negotiations. scaffold-foc eliminates this boilerplate by generating a complete, production-ready environment with built-in diagnostic and setup tooling—allowing you to store, retrieve, and verify data on Filecoin in minutes.
foc:*): Diagnostic scripts that verify RPC health, wallet balances, operator approvals, gas limits, and execute one-transaction wallet onboarding.AGENTS.md): Embedded architectural documentation designed for AI coding assistants (Antigravity, Cursor, Copilot) to ensure accurate code generation.Run the CLI command in your terminal:
npx scaffold-foc my-foc-app
Navigate to your generated directory:
cd my-foc-app
Open .env.local and add your Filecoin Calibration wallet private key:
FOC_PRIVATE_KEY=0x...your_private_key_here...
FOC_NETWORK=calibration
FOC_APP_NAME=my-foc-app
(Need testnet funds? Links to tFIL gas and tUSDFC storage faucets are included inside .env.local)
Execute the built-in diagnostic and setup sequence:
# 1. Verify wallet balance, RPC connection, and approval status
npm run foc:check
# 2. Deposit USDFC and grant operator approval in one transaction
npm run foc:setup
# 3. Test end-to-end file upload and retrieval against live storage
npm run foc:test-upload
# 4. Start your local development server
npm run dev
Visit http://localhost:3000 to interact with your application.
The scaffolded application is structured around clean separation of concerns between client components, server-side API routes, and Synapse SDK initialization:
my-foc-app/
├── app/
│ ├── api/
│ │ ├── download/ # GET /api/download?cid=... (Retrieves file bytes from Filecoin)
│ │ ├── status/ # GET /api/status (Account summary, balances, & data sets)
│ │ └── upload/ # POST /api/upload (Uploads File/Blob to Filecoin storage)
│ ├── globals.css # Modern dark-mode styling system
│ ├── layout.tsx # Root application layout
│ └── page.tsx # Interactive upload, retrieve, and telemetry dashboard UI
├── lib/
│ └── synapse.ts # Centralized Synapse SDK client initialization
├── scripts/
│ ├── check.ts # Environment, wallet, & provider diagnostic engine (npm run foc:check)
│ ├── setup.ts # Gas & operator allowance setup script (npm run foc:setup)
│ ├── status.ts # Account, proof, and PDP status reporter (npm run foc:status)
│ └── test-upload.ts # End-to-end storage verification script (npm run foc:test-upload)
├── .env.example # Environment template
├── .env.local # Local secrets configuration (gitignored)
└── AGENTS.md # Context documentation for AI coding tools
foc: Script SuiteEvery project scaffolded by scaffold-foc includes specialized command-line utilities in ./scripts to manage storage operations and wallet states:
| Command | Primary Function | Details |
|---|---|---|
npm run foc:check | Diagnostic Engine | Inspects private key format, Calibration RPC reachability, tFIL gas balance, tUSDFC wallet balance, Filecoin Pay deposits, storage provider selection, and operator approval allowances. Outputs actionable fixes for any failing line. |
npm run foc:setup | Auto-Provisioner | Onboards fresh wallets in one transaction. Deposits USDFC into Filecoin Pay and approves the default storage operator via EIP-2612 permit authorization. |
npm run foc:test-upload | Integration Test | Executes a full round-trip storage cycle: uploads a test payload to storage providers, retrieves the stored bytes, verifies checksum hash equality, and records FOC_TEST_PIECE_CID. |
npm run foc:status | Telemetry & PDP Health | Displays Filecoin Pay account health (deposited funds, active lockup, monthly burn rate), active data sets, and Provable Data Possession (PDP) verification status for any Piece CID or Data Set ID. |
npm run foc:upgrade | SDK & Dependencies Upgrader | Upgrades @filoz/synapse-sdk and FOC core dependencies in your project to the latest stable release. |
The scaffold includes production-grade Next.js App Router API endpoints that interface with the Synapse SDK on the server:
POST /api/uploadFormData containing a file field.Uint8Array, computes piece commitment, uploads to warm storage providers via Synapse SDK, and returns storage metadata.{
"success": true,
"pieceCid": "bafkzcib...",
"size": 1048576,
"dataSets": [ ... ]
}
GET /api/download?cid=<PIECE_CID>synapse.storage.download().GET /api/status{
"walletBalance": "100.0 USDFC",
"depositedBalance": "50.0 USDFC",
"accountSummary": { ... },
"dataSets": [ ... ]
}
scaffold-foc standardizes Synapse SDK usage via lib/synapse.ts.
lib/synapse.ts)import { Synapse, chain } from '@filoz/synapse-sdk'
export function getSynapse() {
const privateKey = process.env.FOC_PRIVATE_KEY
if (!privateKey) throw new Error('FOC_PRIVATE_KEY is missing in environment')
const targetChain = process.env.FOC_NETWORK === 'mainnet' ? chain.mainnet : chain.calibration
return Synapse.create({
account: privateKey,
chain: targetChain,
source: process.env.FOC_APP_NAME || 'scaffold-foc-app',
})
}
import { getSynapse } from '@/lib/synapse'
const synapse = getSynapse()
// 1. Upload bytes to Filecoin Storage
const bytes = new Uint8Array(await file.arrayBuffer())
const result = await synapse.storage.upload(bytes)
console.log('Stored Piece CID:', result.pieceCid)
// 2. Download bytes by Piece CID
const downloadedBytes = await synapse.storage.download({ pieceCid: result.pieceCid })
// 3. Query PDP Proof Status
const ctx = await synapse.storage.createContext({ dataSetId: result.copies[0].dataSetId })
const status = await ctx.pieceStatus({ pieceCid: result.pieceCid })
console.log('Next Proof Due:', status.dataSetNextProofDue)
npx scaffold-foc [project-directory] [options]
[project-directory]: Name or path of the directory to create (default: my-foc-app).--no-install: Skip automatic npm install after scaffolding.-h, --help: Display available CLI arguments and options.≥ 20.0.0npm (v10+), pnpm, or yarn--template storage|ai|paywall).foc:doctor): Automated transaction builder to resolve missing allowances directly from diagnostic output.@filoz/synapse-sdk/session for user-signed/user-funded storage authorization.@filoz/synapse-react) for upload progress, PDP status badges, and wallet modal integration.Distributed under the MIT License. See LICENSE for details.
FAQs
The fastest way to start building on Filecoin Onchain Cloud — scaffold a Next.js + Synapse SDK app with built-in setup checks
We found that scaffold-foc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GitHub is tightening GitHub Actions security with new restrictions on privileged pull request workflows. Here's what changes and how maintainers are affected.
Security News
/Application Security
A practical guide to securing GitHub Actions against supply chain attacks, covering malicious pull requests, credential theft, dependency risks, and release pipelines.
Security News
Composer 2.11 adds dependency cooldowns, joining package managers that delay new releases to reduce supply chain risks while allowing urgent security updates.