Prerequisites
Before running locally, ensure you have:
- Installed all required tools
- Set up PostgreSQL
- Configured environment variables
Quick Start
1. Start PostgreSQL
If PostgreSQL isn’t already running:
2. Start the API
Navigate to the API directory and set up:
Start the development server:
The API will start on http://localhost:3001 with hot-reload enabled.
3. Start the Dashboard
In a new terminal, navigate to the dashboard directory:
Start the development server:
The Dashboard will start on http://localhost:3000.
API Development
Available Scripts
The API (located in api/package.json) provides these npm scripts:
Development
Runs the API in watch mode. The server automatically restarts when you make changes to any TypeScript file.
Start Production
Runs the API once without watch mode (production-style).
Type Checking
Runs TypeScript type checking without emitting files.
Database Operations
API Configuration
The API requires these environment variables in api/.env:
Accessing the API
Once running, you can access:
Dashboard Development
Available Scripts
The Dashboard (located in dashboard/package.json) provides these scripts:
Development
Starts Next.js in development mode with hot-reload.
Build
Creates an optimized production build.
Start Production
Runs the production build (must run build first).
Linting
Runs ESLint to check for code quality issues.
Dashboard Configuration
The Dashboard requires this environment variable in dashboard/.env.local:
Accessing the Dashboard
Once running, open http://localhost:3000 in your browser.
Development Workflow
Typical development workflow:
- Start PostgreSQL (if not running)
- Start API in one terminal (
bun run dev)
- Start Dashboard in another terminal (
pnpm dev)
- Make changes to code - both servers hot-reload automatically
- Run migrations when schema changes:
bun run db:generate && bun run db:migrate
Troubleshooting Common Issues
Port Already in Use
If port 3001 (API) or 3000 (Dashboard) is already in use:
Or change the port in your environment variables.
Database Connection Failed
If the API can’t connect to PostgreSQL:
-
Verify PostgreSQL is running:
-
Check your
DATABASE_URL in api/.env
-
Test the connection:
API Not Found (Dashboard)
If the Dashboard can’t reach the API:
- Verify the API is running on port 3001
- Check
NEXT_PUBLIC_API_BASE_URL in dashboard/.env.local
- Ensure CORS is configured correctly (check
DASHBOARD_ORIGIN in API)
Module Not Found
If you get module not found errors:
Type Errors
Run type checking to see detailed errors:
Migration Issues
If migrations fail or schema is out of sync:
db:reset will delete all data in your database.
Better Auth Errors
If you see authentication errors:
- Verify
BETTER_AUTH_SECRET is at least 32 characters
- Check
BETTER_AUTH_URL matches your API URL
- Ensure
DASHBOARD_ORIGIN matches your Dashboard URL
Solana RPC Issues
If Solana integration fails:
- Verify
SOLANA_RPC_URL is accessible
- Try using a different RPC endpoint:
- Devnet:
https://api.devnet.solana.com
- Mainnet:
https://api.mainnet-beta.solana.com
Bun Watch Mode
Bun’s --watch flag is very fast but sometimes misses changes. If a change isn’t detected, save the file again or restart the server.
Next.js Fast Refresh
Next.js Fast Refresh should work automatically. If it stops working:
- Ensure your components are named exports or default exports
- Avoid anonymous components
- Restart the dev server
Database Queries
In development, Drizzle logs all queries when verbose: true is set in drizzle.config.ts. This helps debug but can be noisy.
Next Steps
Now that you have the application running: