Development

Development

Local development setup and contribution guide.

---

Prerequisites

Tool	Version
Go	1.21+
Node.js	20+
pnpm	8+
SQLite3	3.40+
FFmpeg	6+
libvips	8.14+

Quick Start

git clone https://github.com/suryaprakash251201/nexora.git
cd nexora

# Frontend deps
cd web && pnpm install && cd ..

# Generate SQL code (after schema changes)
make sqlc

# Terminal 1: Frontend (Vite HMR)
cd web && pnpm dev

# Terminal 2: Backend
make dev

Access: Frontend http://localhost:5173, Backend http://localhost:8080

Project Structure

nexora/
├── cmd/nexora/           # Main entry point
├── internal/
│   ├── api/              # HTTP handlers + middleware
│   ├── auth/             # JWT, sessions, TOTP
│   ├── database/         # DB connections + migrations
│   ├── storage/          # Local FS + S3 abstraction
│   ├── search/           # FTS5 / tsvector
│   ├── preview/          # Thumbnails, metadata, transcode
│   ├── sharing/          # Share links
│   ├── playlists/        # Audio playlists
│   ├── jobs/             # Background job queue
│   ├── config/           # Configuration
│   └── logger/           # Structured logging
├── migrations/           # SQL migration files
└── web/                  # React frontend
    ├── src/
    │   ├── components/   # UI components
    │   ├── hooks/        # Custom hooks
    │   ├── store/        # Zustand stores
    │   ├── api/          # TanStack Query hooks
    │   ├── lib/          # Utilities
    │   └── types/        # TypeScript types
    └── public/

Common Tasks

# Run migrations
make migrate

# Create new migration
make migrate-create name=description

# Generate SQL code (sqlc)
make sqlc

# Frontend
cd web && pnpm dev          # Dev server
cd web && pnpm build        # Production build
cd web && pnpm typecheck    # TypeScript check
cd web && pnpm lint         # ESLint
cd web && pnpm test         # Tests

# Backend
go test ./... -v
make build                  # Build everything

Development Workflow

Branch Strategy

• main — protected, release branch
• feature/* — short-lived feature branches
• fix/* — bug fix branches

Commit Convention

type(scope): description

feat: New feature
fix: Bug fix
refactor: Code restructuring
docs: Documentation
test: Tests
chore: Build, deps, tooling

PR Checklist

• Tests pass
• Type check passes
• Lint passes
• Build succeeds
• No debug code
• Docs updated

Debugging

Backend (Delve)

go install github.com/go-delve/delve/cmd/dlv@latest
dlv test ./internal/api/...

Frontend (VS Code)

{
  "type": "chrome",
  "request": "launch",
  "name": "Debug Frontend",
  "url": "http://localhost:5173",
  "webRoot": "${workspaceFolder}/web/src"
}

Code Style

• Go: gofmt + golangci-lint
• TypeScript: ESLint + Prettier, strict mode
• React: Functional components + hooks, Tailwind utilities

Adding Features

Backend: New API Endpoint

1. Add handler in internal/api/handlers_<domain>.go
2. Register route in internal/api/server.go
3. Write tests

Frontend: New Page/Component

1. Create component in web/src/components/
2. Add route in web/src/App.tsx
3. Add API hook in web/src/api/

CI/CD

on: [push, pull_request]

jobs:
  backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
      - run: make sqlc && go test ./... && golangci-lint run

  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: cd web && pnpm install && pnpm typecheck && pnpm lint && pnpm test && pnpm build

Related Pages

• Architecture — System design
• Deployment — Production deployment