Files

Thomas Hallock bda5bc6c0e fix: prevent database imports from being bundled into client code

**Problem:**
- player-ownership.ts imported drizzle-orm and @/db at top level
- When RoomMemoryPairsProvider imported client-safe utilities, Webpack bundled ALL imports including database code
- This caused hydration error: "The 'original' argument must be of type Function"
- Node.js util.promisify was being called in browser context

**Solution:**
1. Created player-ownership.client.ts with ONLY client-safe utilities
   - No database imports
   - Safe to import from 'use client' components
   - Contains: buildPlayerOwnershipFromRoomData(), buildPlayerMetadata(), helper functions

2. Updated player-ownership.ts to re-export client utilities and add server-only functions
   - Re-exports everything from .client.ts
   - Adds buildPlayerOwnershipMap() (async, database-backed)
   - Safe to import from server components/API routes

3. Updated RoomMemoryPairsProvider to import from .client.ts

**Result:**
- No more hydration errors on /arcade/room
- Client bundle doesn't include database code
- Server code can still use both client and server utilities

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-10 11:40:46 -05:00

2.4 KiB

Raw Blame History

Development Setup

This document describes how to set up and run the Soroban Flashcard Generator for development.

Architecture

This is a monorepo with the following structure:

.
├── apps/
│   └── web/                 # Next.js web application
├── packages/
│   └── core/
│       └── client/
│           ├── node/        # @soroban/core - Node.js TypeScript bindings
│           └── typescript/  # @soroban/client - TypeScript utilities
└── scripts/                 # Development scripts

Prerequisites

Node.js 18+
pnpm 8+
Python 3.8+
Typst (for PDF generation)
qpdf (optional, for PDF optimization)

Quick Start

Initial Setup
```
pnpm setup
```
This script will:
- Install all dependencies
- Build the core packages
- Set up Panda CSS
- Run type checks
Development
```
pnpm dev
```
This starts all development servers in parallel using Turborepo.

The web app will be available at: http://localhost:3000

Available Scripts

pnpm setup - Full development environment setup
pnpm dev - Start all development servers
pnpm build - Build all packages
pnpm type-check - Run TypeScript checks
pnpm lint - Run linting
pnpm test - Run tests
pnpm clean - Clean build artifacts

Packages

@soroban/core

Node.js TypeScript bindings that call the Python generator directly via child_process. Located in packages/core/client/node/.

@soroban/web

Next.js web application with beautiful UI built using:

Panda CSS for styling
TanStack Form for form management
Radix UI primitives for accessibility
Lucide React for icons

Development Notes

TypeScript Bindings: The web app calls Python directly through TypeScript bindings, not via a FastAPI server.
Styling: Uses Panda CSS instead of Tailwind. Run pnpm panda in the web app to regenerate styles.
Monorepo: Built packages must be available before the web app can use them. The setup script handles this automatically.
Asset Storage: Generated files are temporarily stored in memory. In production, use Redis or a database.

Troubleshooting

TypeScript errors: Run pnpm type-check to see detailed errors.

Build issues: Try pnpm clean then pnpm setup to rebuild everything.

Python errors: Ensure Python 3, Typst, and qpdf are installed and accessible in PATH.

2.4 KiB Raw Blame History