Frontend Playbook

Frontend Playbook

What You Probably Got Wrong

"I'll use `yarn chain`." Wrong. yarn chain gives you an empty local chain with no protocols, no tokens, no state. yarn fork --network base gives you a copy of real Base with Uniswap, Aave, USDC, real whale balances — everything (verified addresses: addresses/SKILL.md). Always fork.

"I deployed to IPFS and it works." Did the CID change? If not, you deployed stale output. Did routes work? Without trailingSlash: true, every route except / returns 404. Did you check the OG image? Without NEXT_PUBLIC_PRODUCTION_URL, it points to localhost:3000.

"I'll set up the project manually." Don't. npx create-eth@latest handles everything — Foundry, Next.js, RainbowKit, scaffold hooks. Never run forge init or create Next.js projects from scratch.

---

Fork Mode Setup

Why Fork, Not Chain

yarn chain (WRONG)              yarn fork --network base (CORRECT)
└─ Empty local chain            └─ Fork of real Base mainnet
└─ No protocols                 └─ Uniswap, Aave, etc. available
└─ No tokens                    └─ Real USDC, WETH exist
└─ Testing in isolation         └─ Test against REAL state

Setup

npx create-eth@latest          # Select: foundry, target chain, name
cd <project-name>
yarn install
yarn fork --network base       # Terminal 1: fork of real Base
yarn deploy                    # Terminal 2: deploy contracts to fork
yarn start                     # Terminal 3: Next.js frontend

Critical: Chain ID Gotcha

When using fork mode, the frontend target network MUST be `chains.foundry` (chain ID 31337), NOT the chain you're forking.

The fork runs locally on Anvil with chain ID 31337. Even if you're forking Base:

// scaffold.config.ts during development
targetNetworks: [chains.foundry],  // ✅ NOT chains.base!

Only switch to chains.base when deploying contracts to the REAL network.

Enable Block Mining

# In a new terminal — REQUIRED for time-dependent logic
cast rpc anvil_setIntervalMining 1

Without this, block.timestamp stays FROZEN. Any contract logic using timestamps (deadlines, expiry, vesting) will break silently.

Make it permanent by editing packages/foundry/package.json to add --block-time 1 to the fork script.

---

Deploying to IPFS (Recommended)

IPFS is the recommended deploy path for SE2. Avoids Vercel's memory limits entirely. Produces a fully decentralized static site.

Full Build Command

cd packages/nextjs
rm -rf .next out  # ALWAYS clean first

NEXT_PUBLIC_PRODUCTION_URL="https://yourapp.yourname.eth.link" \
  NODE_OPTIONS="--require ./polyfill-localstorage.cjs" \
  NEXT_PUBLIC_IPFS_BUILD=true \
  NEXT_PUBLIC_IGNORE_BUILD_ERROR=true \
  yarn build

# Upload to BuidlGuidl IPFS
yarn bgipfs upload out
# Save the CID!

Node 25+ localStorage Polyfill (REQUIRED)

Node.js 25+ ships a built-in localStorage object that's MISSING standard WebStorage API methods (getItem, setItem). This breaks next-themes, RainbowKit, and any library that calls localStorage.getItem() during static page generation.

Error you'll see:

TypeError: localStorage.getItem is not a function
Error occurred prerendering page "/_not-found"

The fix: Create polyfill-localstorage.cjs in packages/nextjs/:

if (typeof globalThis.localStorage !== "undefined" &&
    typeof globalThis.localStorage.getItem !== "function") {
  const store = new Map();
  globalThis.localStorage = {
    getItem: (key) => store.get(key) ?? null,
    setItem: (key, value) => store.set(key, String(value)),
    removeItem: (key) => store.delete(key),
    clear: () => store.clear(),
    key: (index) => [...store.keys()][index] ?? null,
    get length() { return store.size; },
  };
}

Why `--require` and not `instrumentation.ts`? Next.js spawns a separate build worker process for prerendering. --require injects into EVERY Node process (including workers). next.config.ts polyfill only runs in the main process. instrumentation.ts doesn't run in the build worker. Only --require works.

IPFS Routing — Why Routes Break

IPFS gateways serve static files. No server handles routing. Three things MUST be true:

1. `output: "export"` in next.config.ts — generates static HTML files.

2. `trailingSlash: true` (CRITICAL) — This is the #1 reason routes break:

• trailingSlash: false (default) → generates debug.html
• trailingSlash: true → generates debug/index.html
• IPFS gateways resolve directories to index.html automatically, but NOT bare filenames
• Without trailing slash: /debug → 404 ❌
• With trailing slash: /debug → debug/ → debug/index.html ✅

3. Pages must survive static prerendering — any page that crashes during yarn build (browser APIs at import time, localStorage) gets skipped silently → 404 on IPFS.

The complete IPFS-safe next.config.ts pattern:

const isIpfs = process.env.NEXT_PUBLIC_IPFS_BUILD === "true";
if (isIpfs) {
  nextConfig.output = "export";
  nextConfig.trailingSlash = true;
  nextConfig.images = { unoptimized: true };
}

SE2's block explorer pages use localStorage at import time and crash during static export. Rename app/blockexplorer to app/_blockexplorer-disabled if not needed.

Stale Build Detection

The #1 IPFS footgun: You edit code, then deploy the OLD build.

# MANDATORY after ANY code change:
rm -rf .next out                     # 1. Delete old artifacts
# ... run full build command ...     # 2. Rebuild from scratch
grep -l "YOUR_STRING" out/_next/static/chunks/app/*.js  # 3. Verify changes present

# Timestamp check:
stat -f '%Sm' app/page.tsx           # Source modified time
stat -f '%Sm' out/                   # Build output time
# Source NEWER than out/ = STALE BUILD. Rebuild first!

The CID is proof: If the IPFS CID didn't change after a deploy, you deployed the same content. A real code change ALWAYS produces a new CID.

Verify Routes After Deploy

ls out/*/index.html                  # Each route has a directory + index.html
curl -s -o /dev/null -w "%{http_code}" -L "https://GATEWAY/ipfs/CID/debug/"
# Should return 200, not 404

---

Deploying to Vercel (Alternative)

SE2 is a monorepo — Vercel needs special configuration.

Configuration

1. Root Directory: packages/nextjs 2. Install Command: cd ../.. && yarn install 3. Build Command: leave default (next build) 4. Output Directory: leave default (.next)

# Via API:
curl -X PATCH "https://api.vercel.com/v9/projects/PROJECT_ID" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rootDirectory": "packages/nextjs", "installCommand": "cd ../.. && yarn install"}'

Common Failures

Decision Tree

Want to deploy SE2?
├─ IPFS (recommended) → yarn ipfs / manual build + upload
│   └─ Fully decentralized, no memory limits, works with ENS
├─ Vercel → Set rootDirectory + installCommand
│   └─ Fast CDN, but centralized. May OOM on large projects
└─ vercel --prebuilt → Build locally, push artifacts to Vercel
    └─ Best of both: local build power + Vercel CDN

---

ENS Subdomain Setup

Two mainnet transactions to point an ENS subdomain at your IPFS deployment.

Transaction 1: Create Subdomain (new apps only)

1. Open https://app.ens.domains/yourname.eth 2. Go to "Subnames" tab → "New subname" 3. Enter the label (e.g. myapp) → Next → Skip profile → Open Wallet → Confirm 4. If gas is stuck: switch MetaMask to Ethereum → Activity tab → "Speed up"

Transaction 2: Set IPFS Content Hash

1. Navigate to https://app.ens.domains/myapp.yourname.eth 2. "Records" tab → "Edit Records" → "Other" tab 3. Paste in Content Hash field: ipfs://<CID> 4. Save → Open Wallet → Confirm in MetaMask

For updates to an existing app: skip Tx 1, only do Tx 2.

Verify

# 1. Onchain content hash matches
RESOLVER=$(cast call 0x00000000000C2e074eC69A0dFb2997BA6C7d2e1e \
  "resolver(bytes32)(address)" $(cast namehash myapp.yourname.eth) \
  --rpc-url https://eth.llamarpc.com)
cast call $RESOLVER "contenthash(bytes32)(bytes)" \
  $(cast namehash myapp.yourname.eth) --rpc-url https://eth.llamarpc.com

# 2. Gateway responds (may take 5-15 min for cache)
curl -s -o /dev/null -w "%{http_code}" -L "https://myapp.yourname.eth.link"

# 3. OG metadata correct (not localhost)
curl -s -L "https://myapp.yourname.eth.link" | grep 'og:image'

Use `.eth.link` NOT `.eth.limo` — .eth.link works better on mobile.

---

Go to Production — Complete Checklist

When the user says "ship it", follow this EXACT sequence.

Step 1: Final Code Review 🤖

• All feedback incorporated
• No duplicate h1, no raw addresses, no shared isLoading
• scaffold.config.ts has rpcOverrides and pollingInterval: 3000

Step 2: Choose Domain 👤

Ask: "What subdomain do you want? e.g. `myapp.yourname.eth` → `myapp.yourname.eth.link`"

Step 3: Generate OG Image + Fix Metadata 🤖

• Create 1200×630 PNG (public/thumbnail.png) — NOT the stock SE2 thumbnail
• Set NEXT_PUBLIC_PRODUCTION_URL to the live domain
• Verify og:image will resolve to an absolute production URL

Step 4: Clean Build + IPFS Deploy 🤖

cd packages/nextjs && rm -rf .next out
NEXT_PUBLIC_PRODUCTION_URL="https://myapp.yourname.eth.link" \
  NODE_OPTIONS="--require ./polyfill-localstorage.cjs" \
  NEXT_PUBLIC_IPFS_BUILD=true NEXT_PUBLIC_IGNORE_BUILD_ERROR=true \
  yarn build

# Verify before uploading:
ls out/*/index.html                        # Routes exist
grep 'og:image' out/index.html             # Not localhost
stat -f '%Sm' app/page.tsx                 # Source older than out/
stat -f '%Sm' out/

yarn bgipfs upload out                     # Save the CID

Step 5: Share for Approval 👤

Send: "Build ready for review: `https://community.bgipfs.com/ipfs/<CID>`" Wait for approval before touching ENS.

Step 6: Set ENS 🤖

Create subdomain (if new) + set IPFS content hash. Two mainnet transactions.

Step 7: Verify 🤖

• Content hash matches onchain
• .eth.link gateway responds with 200
• OG image loads correctly
• Routes work (/debug/, etc.)

Step 8: Report 👤

"Live at `https://myapp.yourname.eth.link` — ENS content hash confirmed onchain, unfurl metadata set."

---

Build Verification Process

A build is NOT done when the code compiles. It's done when you've tested it like a real user.

Phase 1: Code QA (Automated)

• Scan .tsx files for raw address strings (should use <Address/>)
• Scan for shared isLoading state across multiple buttons
• Scan for missing disabled props on transaction buttons
• Verify RPC config and polling interval
• Verify OG metadata with absolute URLs
• Verify no public RPCs in any file

Phase 2: Smart Contract Testing

forge test                    # All tests pass
forge test --fuzz-runs 10000  # Fuzz testing

Test edge cases: zero amounts, max amounts, unauthorized callers, reentrancy attempts.

Phase 3: Browser Testing (THE REAL TEST)

Open the app and do a FULL walkthrough:

1. Load the app — does it render correctly? 2. Check page title — is it correct, not "Scaffold-ETH 2"? 3. Connect wallet — does the connect flow work? 4. Wrong network — connect on wrong chain, verify "Switch to Base" appears 5. Switch network — click the switch button, verify it works 6. Approve flow — verify approve button shows, click it, wait for tx, verify action button appears 7. Main action — click primary action, verify loader, wait for tx, verify state updates 8. Error handling — reject a transaction in wallet, verify UI recovers 9. Address displays — all addresses showing ENS/blockies, not raw hex? 10. Share URL — check OG unfurl (image, title, description)

Phase 4: QA Sub-Agent (Complex Builds)

For bigger projects, spawn a sub-agent with fresh context. Give it the repo path and deployed URL. It reads all code against the UX rules, opens a browser, clicks through independently, and reports issues.

---

Don't Do These

• ❌ yarn chain — use yarn fork --network <chain>
• ❌ forge init — use npx create-eth@latest
• ❌ Manual Next.js setup — SE2 handles it
• ❌ Manual wallet connection — SE2 has RainbowKit pre-configured
• ❌ Edit deployedContracts.ts — it's auto-generated by yarn deploy
• ❌ Hardcode API keys in scaffold.config.ts — use .env.local
• ❌ Use mainnet.base.org in production — use Alchemy or similar

---

Resources

• SE2 Docs: https://docs.scaffoldeth.io/
• UI Components: https://ui.scaffoldeth.io/
• SpeedRun Ethereum: https://speedrunethereum.com/
• ETH Tech Tree: https://www.ethtechtree.com
• BuidlGuidl IPFS: https://upload.bgipfs.com