feat: add development tooling and comprehensive setup
- Create development setup script for one-command installation - Add parallel development server startup script - Include comprehensive development documentation - Set up type checking, building, and dependency management - Provide troubleshooting guide and architecture overview 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Thomas Hallock
parent
1b7e71cc0d
commit
7ca65bfd59
|
|
@ -0,0 +1,87 @@
|
|||
# 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.
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
#!/bin/bash
|
||||
|
||||
# Development startup script for Soroban Flashcard Generator
|
||||
# This script starts all development services concurrently
|
||||
|
||||
set -e
|
||||
|
||||
echo "🚀 Starting Soroban Flashcard Generator Development Environment"
|
||||
echo ""
|
||||
|
||||
# Check if we're in the right directory
|
||||
if [ ! -f "package.json" ]; then
|
||||
echo "❌ Please run this script from the project root directory"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Build packages if needed
|
||||
echo "🔨 Building packages..."
|
||||
pnpm turbo run build --filter="@soroban/*" --continue
|
||||
|
||||
# Generate Panda CSS
|
||||
echo "🎨 Generating Panda CSS..."
|
||||
cd apps/web && pnpm panda && cd ../..
|
||||
|
||||
# Start development servers
|
||||
echo "🌟 Starting development servers..."
|
||||
echo ""
|
||||
echo "📝 Available endpoints:"
|
||||
echo " • Web App: http://localhost:3000"
|
||||
echo " • API Health: http://localhost:3000/api/generate"
|
||||
echo ""
|
||||
|
||||
# Use Turborepo to run development in parallel
|
||||
pnpm turbo run dev --parallel
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
#!/bin/bash
|
||||
|
||||
echo "🚀 Setting up Soroban Flashcard Generator Development Environment"
|
||||
echo ""
|
||||
|
||||
# Check for required tools
|
||||
echo "📋 Checking requirements..."
|
||||
|
||||
if ! command -v pnpm &> /dev/null; then
|
||||
echo "❌ pnpm is required but not installed. Please install pnpm first."
|
||||
echo " npm install -g pnpm"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! command -v python3 &> /dev/null; then
|
||||
echo "❌ Python 3 is required but not installed."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ All requirements satisfied"
|
||||
echo ""
|
||||
|
||||
# Install dependencies
|
||||
echo "📦 Installing dependencies..."
|
||||
pnpm install --frozen-lockfile=false
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Failed to install dependencies"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Dependencies installed"
|
||||
echo ""
|
||||
|
||||
# Build core packages
|
||||
echo "🔨 Building core packages..."
|
||||
|
||||
# Build TypeScript client
|
||||
echo " Building @soroban/client..."
|
||||
cd packages/core/client/typescript
|
||||
pnpm build
|
||||
cd ../../../../
|
||||
|
||||
# Build Node client
|
||||
echo " Building @soroban/core..."
|
||||
cd packages/core/client/node
|
||||
pnpm build
|
||||
cd ../../../../
|
||||
|
||||
echo "✅ Core packages built"
|
||||
echo ""
|
||||
|
||||
# Build web app dependencies
|
||||
echo "🎨 Setting up Panda CSS..."
|
||||
cd apps/web
|
||||
pnpm build:css --config
|
||||
cd ../../
|
||||
|
||||
echo "✅ Panda CSS configured"
|
||||
echo ""
|
||||
|
||||
# Final verification
|
||||
echo "🧪 Running type checks..."
|
||||
pnpm turbo run type-check
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
echo ""
|
||||
echo "🎉 Development environment setup complete!"
|
||||
echo ""
|
||||
echo "📋 Next steps:"
|
||||
echo " • Run 'pnpm dev' to start development server"
|
||||
echo " • Run 'pnpm build' to build all packages"
|
||||
echo " • Run 'pnpm turbo run dev' to start all services"
|
||||
echo ""
|
||||
else
|
||||
echo "⚠️ Setup complete but type checks failed. Review the output above."
|
||||
fi
|
||||
Loading…
Reference in New Issue