#
Dev
The QuickDapp development server provides a complete development environment with hot reloading, integrated frontend and backend servers, and comprehensive debugging capabilities.
#
Starting Development Server
#
Basic Usage
Start the development environment:
bun run dev
This command:
- Starts the ElysiaJS backend server on port 3000
- Launches the Vite frontend development server on port 5173
- Initializes worker processes for background jobs
- Sets up database connections and WebSocket support
- Enables hot reload for both client and server code
#
Verbose Mode
Enable detailed startup logging:
bun run dev --verbose
Shows detailed information about:
- Environment variable loading
- Database connection status
- Worker process initialization
- Server startup sequence
- Available endpoints and routes
#
Development Server Architecture
#
Multi-Process Setup
The dev server runs multiple processes in parallel:
┌─────────────────────────────────────────┐
│ Development Environment │
├─────────────────────────────────────────┤
│ Backend (Port 3000) │
│ ├── ElysiaJS Server │
│ ├── GraphQL Endpoint (/graphql) │
│ ├── WebSocket Server (/ws) │
│ └── Static File Serving │
├─────────────────────────────────────────┤
│ Frontend (Port 5173) │
│ ├── Vite Dev Server │
│ ├── React Hot Reload │
│ ├── TypeScript Compilation │
│ └── Proxy to Backend │
├─────────────────────────────────────────┤
│ Worker Processes │
│ ├── Job Processing │
│ ├── Blockchain Monitoring │
│ └── Cron Tasks │
└─────────────────────────────────────────┘
#
Port Configuration
Default port assignments:
- Backend Server: 3000
- Frontend Dev Server: 5173 (proxied through backend)
- WebSocket: Same as backend (3000/ws)
Override ports via environment variables:
PORT=4000 bun run dev # Backend on port 4000
FRONTEND_PORT=3001 bun run dev # Frontend on port 3001
#
Hot Reload System
#
Backend Hot Reload
The backend supports hot reloading for most changes:
Automatic Reload:
- GraphQL resolvers
- Route handlers
- Utility functions
- Configuration changes
- Environment variable updates
Manual Restart Required:
- Database schema changes
- Worker job definitions
- Server bootstrap logic
- Package.json changes
#
Frontend Hot Reload
Vite provides instant hot module replacement:
Instant Updates:
- React components
- CSS/Tailwind classes
- TypeScript files
- Hook dependencies
- GraphQL queries
Browser Refresh Triggered:
- Route changes
- Context provider changes
- Main App component updates
#
Development Configuration
#
Environment Files
Development uses layered environment configuration:
# Load order (later overrides earlier)
.env # Base configuration
.env.development # Development-specific settings
.env.development.local # Personal dev overrides
.env.local # General local overrides
#
Development-Specific Settings
# .env.development
NODE_ENV=development
LOG_LEVEL=debug
WORKER_LOG_LEVEL=debug
# Database
DATABASE_URL=postgresql://postgres:@localhost:5432/quickdapp_dev
# Development wallet (Anvil default)
SERVER_WALLET_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
# Local blockchain
CHAIN=anvil
CHAIN_RPC_ENDPOINT=http://localhost:8545
# Reduced worker count for development
WORKER_COUNT=1
# Enable development features
GRAPHQL_PLAYGROUND=true
#
Debugging Features
#
Server Debugging
Enable debug logging for different components:
# Debug all components
LOG_LEVEL=debug WORKER_LOG_LEVEL=debug bun run dev
# Debug specific modules
DEBUG=graphql,auth,worker bun run dev
#
Database Debugging
Monitor database queries during development:
# Enable query logging
DATABASE_LOG_QUERIES=true bun run dev
# Show slow queries
DATABASE_SLOW_QUERY_THRESHOLD=100 bun run dev
#
Worker Debugging
Debug background job processing:
# Verbose worker logging
WORKER_LOG_LEVEL=debug bun run dev
# Single worker for easier debugging
WORKER_COUNT=1 bun run dev
#
Development Workflow
#
Typical Development Session
Start Services
# Terminal 1: Start local blockchain (if needed) cd sample-contracts && bun devnet.ts # Terminal 2: Start QuickDapp bun run dev --verbose
Make Changes
- Edit React components → Hot reload in browser
- Update GraphQL resolvers → Server restarts automatically
- Modify database schema → Run
bun run db push
Test Changes
- Frontend changes visible immediately
- Backend changes after brief restart
- Use browser dev tools for debugging
#
Database Development
Work with database changes during development:
# Apply schema changes to development database
bun run db push
# Generate migration for schema changes
bun run db generate
# Reset development database (destructive)
bun run db push --force
#
Testing During Development
Run tests alongside development:
# Run tests in watch mode
bun run test --watch
# Run specific test file
bun run test --pattern auth
# Debug test with verbose logging
LOG_LEVEL=debug bun run test
#
Common Development Tasks
#
Adding New Routes
Backend Route
// src/server/start-server.ts app.get('/api/custom', () => { return { message: 'Custom endpoint' } })
Frontend Route
// src/client/App.tsx <Route path="/custom" element={<CustomPage />} />
GraphQL Operation
// src/server/graphql/resolvers.ts export const resolvers = { Query: { customData: () => ({ data: 'Custom data' }) } }
#
Environment Variable Changes
- Update
.env
or.env.development
- Restart dev server to pick up changes
Update TypeScript types if needed:
// src/shared/config/server.ts export const serverConfig = { CUSTOM_SETTING: get('CUSTOM_SETTING').asString() }
#
Adding Dependencies
Install Package
bun add package-name # or for dev dependency bun add -d package-name
Restart Dev Server
# Stop with Ctrl+C, then restart bun run dev
#
Performance Optimization
#
Development Performance Tips
Reduce Worker Count
WORKER_COUNT=1 bun run dev # Instead of default
Limit Database Logging
# Only in .env.development if needed DATABASE_LOG_QUERIES=false
Use Incremental TypeScript
// tsconfig.json { "compilerOptions": { "incremental": true } }
Optimize Vite Configuration
// vite.config.ts export default defineConfig({ server: { hmr: { overlay: false }, // Disable error overlay if needed } })
#
Troubleshooting
#
Common Issues
Port Already in Use
# Kill processes on default ports
lsof -ti:3000 | xargs kill -9
lsof -ti:5173 | xargs kill -9
# Or use different ports
PORT=3001 bun run dev
Database Connection Issues
# Check PostgreSQL is running
brew services list | grep postgresql
# Reset database connection
bun run db push --force
Hot Reload Not Working
# Clear Vite cache
rm -rf node_modules/.vite
# Restart dev server
bun run dev
Worker Process Errors
# Debug worker startup
WORKER_LOG_LEVEL=debug WORKER_COUNT=1 bun run dev
#
Debug Information
Get system information for troubleshooting:
# Check versions
bun --version
# Check database connection
psql -U postgres -c "SELECT version();"
# Check ports in use
lsof -i :3000
lsof -i :5173
The development server in QuickDapp provides a comprehensive environment for building and testing your dapp with excellent developer experience and debugging capabilities.