Local Development Guide
This document explains how to develop and debug the Rin project locally.
Quick Start
1. Clone the Project
2. Install Dependencies
3. Configure Environment Variables
4. Start the Development Server
This will automatically:
- ✅ Generate
wrangler.tomlconfiguration file - ✅ Generate
.dev.varssensitive information file - ✅ Run database migrations
- ✅ Start development server (port 11498 - unified frontend and backend)
Visit http://localhost:11498 to start developing!
Environment Variable Configuration
All configurations are centralized in the .env.local file:
Site Configuration
:::tip Site configuration (name, avatar, description, pagination size, etc.) is now served dynamically from the backend and can be modified via the settings page after deployment. Environment variables are only used as default values.
The following environment variables are optional:
Backend Configuration
Sensitive Configuration (Required)
Common Commands
Development Workflow
First-time Setup
- Fork the project repository
- Clone to local
- Install dependencies:
bun install - Configure
.env.local - Run
bun run dev
Daily Development
- Modify code
- Frontend auto-hot reloads, backend restarts automatically on changes
- Test functionality
- Commit code
Database Changes
- Modify
server/src/db/schema.ts - Run
bun run db:generateto generate migration files - Run
bun run db:migrateto apply migrations
Testing
The project uses different testing frameworks for client and server:
Client Testing (Vitest)
Client tests use Vitest with jsdom environment for React component testing.
Test files location: client/src/**/__tests__/*.test.ts
Server Testing (Bun)
Server tests use Bun's native test runner with in-memory SQLite database.
Test files location:
- Unit tests:
server/src/**/__tests__/*.test.ts - Integration tests:
server/tests/integration/ - Security tests:
server/tests/security/
Adding New Tests
When adding new features, please include corresponding tests:
- Client: Add tests in
client/src/**/__tests__/*.test.ts - Server: Add tests in
server/src/**/__tests__/*.test.tsorserver/tests/
API Architecture
Custom API Client
The project uses a custom HTTP client instead of Eden for type-safe API communication:
- Location:
client/src/api/client.ts - Features: Type-safe requests, error handling, auth token management
- Usage: All API calls go through the typed client
Shared Types (@rin/api)
The @rin/api package provides shared TypeScript types for both client and server:
- Location:
packages/api/ - Purpose: End-to-end type safety for API contracts
- Usage: Import types from
@rin/apiin both client and server code
When adding new API endpoints:
- Define types in
packages/api/src/types.ts - Implement server handler in
server/src/services/ - Client automatically gets type safety through shared types
Troubleshooting
Port Already in Use
If ports 5173 or 11498 are occupied, you can modify the configuration in .env.local:
Database Migration Failed
Configuration Files Not Generated
GitHub OAuth Configuration
GitHub OAuth needs to be configured for local development:
- Visit https://github.com/settings/developers
- Create a new OAuth App
- Authorization callback URL:
http://localhost:11498/user/github/callback - Fill Client ID and Client Secret into
.env.local
Project Structure
Production Deployment
Please refer to the Deployment Guide for production deployment procedures.
Getting Help
- 📖 Full documentation: https://docs.openrin.org
- 💬 Discord: https://discord.gg/JWbSTHvAPN
- 🐛 Submit Issue: https://github.com/Bad3r/Rin/issues