87 lines
2.4 KiB
Markdown
87 lines
2.4 KiB
Markdown
# 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
|
|
|
|
1. **Initial Setup**
|
|
```bash
|
|
pnpm setup
|
|
```
|
|
This script will:
|
|
- Install all dependencies
|
|
- Build the core packages
|
|
- Set up Panda CSS
|
|
- Run type checks
|
|
|
|
2. **Development**
|
|
```bash
|
|
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
|
|
|
|
1. **TypeScript Bindings**: The web app calls Python directly through TypeScript bindings, not via a FastAPI server.
|
|
|
|
2. **Styling**: Uses Panda CSS instead of Tailwind. Run `pnpm panda` in the web app to regenerate styles.
|
|
|
|
3. **Monorepo**: Built packages must be available before the web app can use them. The setup script handles this automatically.
|
|
|
|
4. **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. |