Walkthrough: Miniapp Monorepo Integration

Date: January 28, 2026 Duration: ~4 hours Branch: miniapp-integration-finalStatus: ✅ Complete

Context

What We're Accomplishing

Integrate the standalone miniapp-latest codebase into the emerge turbo monorepo, making it follow the exact same patterns used by other monorepo apps (monitor, emprops-studio, api).

Why This Work Is Necessary

Consistency: miniapp-latest was standalone with its own Prisma setup, environment management, and build process
Shared Resources: Need to use the monorepo's shared database client (@emergexyz/db) and environment system
Dependency Management: Multiple apps were using different React versions, causing potential issues
Build Integration: Need to integrate with turbo build system and monorepo scripts

Starting State

apps/miniapp exists (reference implementation using monorepo patterns)
apps/miniapp-latest exists (standalone app, not integrated)
Plan exists in /Users/the_dusky/.claude/plans/rosy-riding-bunny.md
Working branch: miniapp-integration-final

Phase 1: Discovery - React Version Mismatch

The Question

User asked: "is the miniapp using react 18 or 19?"

Investigation:

bash

# Check miniapp
cat apps/miniapp/package.json | grep react
# Result: No direct react dependency (uses @emp/react)

# Check emprops-studio
cat apps/emprops-studio/package.json | grep '"react"'
# Result: No match - checked full file

# Check monitor
cat apps/monitor/package.json | grep '"react"'
# Result: "react": "^19.1.2"

Discovery: Different apps had different React versions, and the existing @emp/react package only had type definitions, not the actual React dependency!

Decision Point: Shared React Package Strategy

Options Considered:

Let each app manage its own React version
Create a shared package that re-exports React
Use pnpm workspace catalog feature

Decision: Option 2 - Shared React Package

Enforces single React version across monorepo
Provides single source of truth
Prevents version drift
Can extend with shared hooks/contexts later

Phase 2: Create Shared React Package

Step 1: Update Package Manifest

Command:

bash

# Edit packages/react/package.json

Changes Made:

json

{
  "name": "@emp/react",
  "version": "0.0.0",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "dependencies": {
    "react": "19.2.0",
    "react-dom": "19.2.0"
  },
  "devDependencies": {
    "@types/react": "^19.0.6",
    "@types/react-dom": "^19.0.3",
    "typescript": "^5.7.3"
  }
}

Rationale:

Lock to exact React 19.2.0 version
Include both react and react-dom
Keep type definitions for IDE support

Step 2: Create Re-export Files

File: packages/react/src/index.ts

typescript

export * from "react";
export { default } from "react";

File: packages/react/src/dom.ts

typescript

export * from "react-dom";
export { default } from "react-dom";
export * from "react-dom/client";

Rationale: Simple barrel exports that make React usage transparent to consumers

Step 3: Update App Dependencies

Apps Updated:

apps/miniapp/package.json
apps/monitor/package.json
apps/emprops-studio/package.json

Pattern Applied:

json

{
  "dependencies": {
    "@emp/react": "workspace:*",
    // Removed: "react": "x.x.x"
    // Removed: "react-dom": "x.x.x"
  },
  "devDependencies": {
    // Removed: "@types/react"
    // Removed: "@types/react-dom"
  }
}

Step 4: Install Dependencies

Command:

bash

pnpm install

Output: Success - all dependencies resolved correctly

Step 5: Type Check

Command:

bash

pnpm typecheck:miniapp

Result: ✅ All types resolve correctly from @emp/react

Phase 3: Fix DaimoPay Configuration

Problem Discovered

While reviewing miniapp code, noticed manual chain configuration for DaimoPay:

typescript

// Old approach - manual chain list
const wagmiConfig = createConfig({
  connectors: [farcasterMiniApp()],
  chains: [arbitrum, base, bsc, celo, /* ... 12 chains */],
  transports: { /* manual transport config */ },
  ssr: true,
});

The Issue

DaimoPay supports many chains (including HyperEVM, Monad) but manual configuration can fall out of sync.

Solution Applied

File: apps/miniapp/app/providers.tsx

Change:

typescript

import { getDefaultConfig } from "@daimo/pay";

const wagmiConfig = createConfig(
  getDefaultConfig({
    appName: "EmProps Mini App",
    connectors: [farcasterMiniApp()],
    ssr: true,
  })
);

Benefits:

Automatically includes ALL Daimo-supported chains
Stays in sync with @daimo/pay updates
Eliminates maintenance burden
Prevents missing chain errors

Phase 4: Fix Prisma Type Usage

Problem Encountered

Error in: apps/miniapp/app/api/collections/[id]/generations/route.ts

typescript

// This doesn't work!
const JsonValue = Prisma.JsonValue;

interface CollectionGeneration {
  input_data?: JsonValue | null;  // Type error
}

Error: Prisma.JsonValue is a type, not a value that can be assigned to a const.

Solution

Correct Usage:

typescript

import { Prisma, prisma } from "@/lib/prisma";

interface CollectionGeneration {
  input_data?: Prisma.JsonValue | null;
  token_metadata: Prisma.JsonValue | null;
  friends: Prisma.JsonValue | null;
}

Lesson: TypeScript types vs values distinction matters. Use Prisma.JsonValue directly as a type annotation, don't try to extract it to a const.

Phase 5: Commit Strategy

Decision: Organized Commits

Rather than one monolithic commit, organized work into logical commits:

Shared React Package - Infrastructure change
DaimoPay Config - Feature improvement
Type Fixes - Bug fix
Documentation - Changelog addition
Miniapp Application - Application code (if needed)