ipfs-deployment

IPFS / Decentralized Frontend Deployment

Overview

Deploying a dApp frontend to IPFS ensures censorship resistance and permanence. The frontend is served via IPFS gateways or ENS+IPFS resolution. Critical for truly decentralized protocols.

Building for IPFS

Next.js Static Export

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  trailingSlash: true,  // CRITICAL: IPFS serves directories, needs index.html in each
  images: {
    unoptimized: true,   // No image optimization server on IPFS
  },
  assetPrefix: './',     // Relative paths for IPFS gateway compatibility
};

module.exports = nextConfig;

Why trailingSlash: true is critical: IPFS resolves /about as a file, but /about/ as a directory containing index.html. Without trailing slashes, navigation breaks on IPFS gateways.

Vite Static Build

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  base: './',  // Relative paths
  build: {
    outDir: 'dist',
  },
});

Create React App

{
  "homepage": "."
}

Build and Clean

# ALWAYS clean before building for IPFS
rm -rf out/ dist/ .next/

# Build
npm run build

# Verify the output
ls -la out/  # or dist/
# Should contain index.html and all static assets

IPFS Pinning

Pinata

# Install Pinata CLI
npm install -g @pinata/cli

# Pin a directory
pinata upload ./out

# Or via API
curl -X POST "https://api.pinata.cloud/pinning/pinFileToIPFS" \
  -H "Authorization: Bearer $PINATA_JWT" \
  -F "file=@./out"

// Programmatic pinning
import PinataSDK from '@pinata/sdk';

const pinata = new PinataSDK({ pinataJWTKey: process.env.PINATA_JWT });

const result = await pinata.pinFromFS('./out', {
  pinataMetadata: { name: 'my-dapp-v1.2.0' },
  pinataOptions: { cidVersion: 1 },
});

console.log('IPFS Hash:', result.IpfsHash);
// e.g., bafybeie5gq4jxvzmsym6hjlwxej4rwdoxt7wadqvmmwbqqblsm54ceyaiq