Technical Implementation

Static Export

Setting output: 'export' in next.config.ts outputs static HTML/CSS/JS files. No Node.js server runs at runtime. Required because Capacitor loads files from the device's local filesystem.

What Breaks in Static Export

Dynamic Routes Solution

Each dynamic route uses a server/client split:

• page.tsx — server component with generateStaticParams returning placeholder params
• client.tsx — the actual UI with useParams()

In-app navigation uses client-side pushState (no file lookup). Deep links are intercepted by appUrlOpen before the WebView resolves a file. The only edge case is page refresh on a dynamic route — the placeholder HTML file serves as a shell.

Code Sharing Strategy

The mobile app shares code from apps/web/src/ via webpack aliases:

// apps/mobile/next.config.ts
config.resolve.alias = {
  '@/components': path.join(webSrc, 'components'),
  '@/hooks': path.join(webSrc, 'hooks'),
  '@/stores': path.join(webSrc, 'stores'),
  '@/utils': path.join(webSrc, 'utils'),
  '@/contexts': path.join(webSrc, 'contexts'),
  '@/lib': path.join(webSrc, 'lib'),
  '@/types': path.join(webSrc, 'types'),
  '@web': webSrc,        // for importing web page components
  '@/mobile': mobileSrc, // for mobile-specific code
};

@/app/ is NOT aliased — the mobile app has its own page layer. For importing web page components (re-exports), use @web/app/... which doesn't trigger Next.js route discovery.

Key Technical Decisions

apiUrl() utility

Every fetch('/api/...') call goes through apiUrl() (apps/web/src/utils/api-url.ts). When NEXT_PUBLIC_API_URL is unset (web), it's a no-op. When set (mobile), it prepends the base URL. This was applied to ~190 fetch call sites across ~150 files, including apiFetch(), useSSE, SSEManager, custom wrappers (callApi, apiCall), and direct fetch calls.

Server actions → API routes

3 server action files (_actions/onchain.ts, _actions/nft.ts, _actions/utils.ts) were replaced with API routes:

• POST /api/onchain — handles buy-shares, sell-shares, update-agent-profile via Privy sponsored transactions
• POST /api/nft/mint/execute — full mint flow (prepare → send tx → poll for confirmation with exponential backoff)
• GET /api/profiles/resolve/[identifier] — resolves ambiguous identifiers to canonical profile paths

The 3 calling hooks were rewritten to use fetch(apiUrl(...)) instead of direct server action imports. Minor web perf regression (~1-5ms) but eliminates the @/app/_actions import dependency that would break webpack aliases.

Device tokens

Push notification device tokens are stored in Redis (not a DB table) — they're ephemeral data that changes when users reinstall. Redis hash per user, 90-day TTL, supports multiple devices per user.

Native features

All Capacitor plugins are lazy-loaded via dynamic import(). This means native feature code is never bundled on web, and native calls are no-ops when Capacitor.isNativePlatform() returns false.

File Manifest

New Files Created

Modified Files

~150 files updated with apiUrl() for fetch calls, plus SSE fixes, shared code moves, hook rewrites, Providers update, and middleware CORS update.

Remote URL Alternative

Instead of static export, Capacitor can load from a remote URL:

const config: CapacitorConfig = {
  server: { url: 'https://play.feed.market' },
};

Pros: Zero code changes. Full feature parity. Instant updates. Cons: Requires internet. Slower load. Higher Apple rejection risk. Use for: Dev testing, Android Play Store (less strict), internal TestFlight.