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