Local Development

This guide walks you through setting up your local development environment to contribute to the Sayr codebase.

Prerequisites

Before you begin, ensure you have the following tools installed:

Installing Prerequisites

# Install pnpm globally
npm install -g pnpm

# Install Bun (required for backend/worker)
curl -fsSL https://bun.sh/install | bash

# Verify installations
node --version   # Should be 22+
pnpm --version   # Should be 10.6+
bun --version    # Should be 1.0+

Project Structure

Sayr is a Turborepo monorepo with the following structure:

sayr/
├── apps/
│   ├── backend/        # Hono API server (Bun, port 5468)
│   ├── start/          # TanStack Start frontend (port 3000)
│   ├── marketing/      # Astro docs/marketing site (port 3002)
│   └── worker/         # GitHub webhook processor (Bun)
├── packages/
│   ├── auth/           # Better Auth configuration
│   ├── database/       # Drizzle ORM schemas and CRUD
│   ├── storage/        # MinIO S3-compatible client
│   ├── ui/             # Shadcn/ui component library
│   ├── util/           # Shared utilities
│   ├── queue/          # Job queue abstraction
│   └── opentelemetry/  # Tracing utilities
└── ...

Initial Setup

1. Clone the Repository

git clone https://github.com/dorasto/sayr.git
cd sayr

2. Install Dependencies

We recommend using pnpm for all package management tasks:

pnpm install

3. Configure Environment Variables

Copy the environment template to each app that requires it:

cp .env.example apps/backend/.env
cp .env.example apps/start/.env
cp .env.example apps/worker/.env

Edit each .env file with your local configuration. Key variables include:

Database:

DATABASE_URL=postgresql://user:password@localhost:5432/sayr

Storage (MinIO/S3):

STORAGE_URL=http://localhost:9000
STORAGE_BUCKET=sayr
STORAGE_ACCESS_KEY=minioadmin
STORAGE_SECRET_KEY=minioadmin
FILE_SALT=your-random-salt
FILE_CDN=http://localhost:9000/sayr

Frontend:

VITE_URL_ROOT=http://admin.app.localhost:3000
VITE_PROJECT_NAME=Sayr
VITE_ROOT_DOMAIN=app.localhost

4. Set Up the Database

Ensure PostgreSQL is running, then push the schema:

pnpm -F @repo/database db:push

To explore your database with a visual interface:

pnpm -F @repo/database db:studio

5. Start Development

Start all apps simultaneously:

pnpm dev

Or start specific apps:

# Backend API only
pnpm -F backend dev

# Frontend only
pnpm -F start dev

# Marketing/docs site only
pnpm -F marketing dev

Local Domains

Sayr uses subdomain-based routing in development. The primary reason behind this is due to constraints with how cookies are handled in development environments. By using subdomains, we can ensure that cookies are scoped to the correct domain, allowing for seamless authentication and session management.

Development Commands

Common Commands

Database Commands

Testing

Code Style

Sayr uses Biome for linting and formatting. Always run linting before committing:

pnpm lint        # Check for issues
pnpm lint:fix    # Auto-fix issues

For detailed coding conventions including import organization, naming conventions, error handling patterns, and component structure, see the Code Style Guide.

Adding UI Components

Sayr uses Shadcn/ui for the component library. To add a new component:

pnpm dlx shadcn@latest add <component-name>

Troubleshooting

Port Already in Use

If a port is already in use, you can find and kill the process:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

Database Connection Issues

Ensure PostgreSQL is running and the DATABASE_URL in your .env file is correct:

# Check PostgreSQL status
pg_isready -h localhost -p 5432

Bun Not Found

If you get "bun: command not found" errors, ensure Bun is installed system-wide and in your PATH:

# Check Bun installation
which bun
bun --version

# If not found, reinstall
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc  # or ~/.zshrc

Type Errors After Schema Changes

After modifying database schemas, regenerate types:

pnpm -F @repo/database db:push

Next Steps

Once your environment is set up, explore these guides to learn more:

• Architecture Overview — Understand how Sayr's systems connect
• Code Style Guide — Coding conventions and best practices
• Database Guide — Working with Drizzle ORM schemas and queries
• Testing Guide — Writing and running tests with Vitest
• Adding Features — End-to-end guide for implementing new features
• Pull Request Guidelines — PR conventions and review process
• Writing Documentation — Contributing to these docs (no local setup needed!)

Ready to Contribute?

1. Pick an issue from the GitHub Issues
2. Create a feature branch from main
3. Make your changes following our code style guidelines
4. Run pnpm lint and pnpm check-types before committing
5. Submit a pull request following our PR guidelines

Thank you for contributing to Sayr!