Welcome to Reliverse. This guide walks you through setting up the monorepo and taking your first steps with the developer tools ecosystem.

Quick Setup

1. Clone the Repository

Clone the Reliverse monorepo from GitHub.

2. Install Dependencies

Use Bun to install all workspace dependencies.

3. Configure Environment

Copy the example env file and configure your local variables.

4. Run Development

Start the apps and packages you need. Use bun dler for orchestration.

Next Steps

Learn about features: CLIs, libs, and tooling
Understand our philosophy: principles behind Reliverse
Read about privacy: how your data is handled

Getting Started with Reliverse

Welcome to the Reliverse monorepo! This guide will help you understand our codebase structure and get up and running quickly.

What is Reliverse?

Reliverse is a modern full-stack monorepo built with:

Bun - Fast JavaScript runtime and package manager
Turborepo - High-performance build system for monorepos
TypeScript - Type-safe JavaScript
TanStack Router - File-based routing for React
Tailwind CSS - Utility-first CSS framework

Project Structure

reliverse/
├── apps/                    # Applications
│   ├── web/                 # Web applications
│   │   ├── reliverse/        # Main web app (TanStack Router + Vite)
│   │   └── kitchen/         # Kitchen sink/demo app
│   ├── expo/                # React Native apps
│   │   └── kitchen/         # Expo demo app
│   ├── api/                 # Backend API (Elysia.js)
│   └── docs/                # Documentation (Fumadocs)
├── packages/                # Shared packages
│   ├── env/                 # Environment configuration
│   ├── auth/                # Authentication utilities
│   ├── convex/              # Database schema (Convex)
│   ├── drizzle/             # Database utilities
│   └── tailwind/            # Shared Tailwind config
└── turbo.json               # Turborepo configuration

Prerequisites

Before getting started, ensure you have:

Bun installed (curl -fsSL https://bun.sh/install | bash)
Git for version control
Node.js 18+ (for some tools)
VS Code with recommended extensions

Installation

1. Clone the repository

git clone https://github.com/blefnk/reliverse.git
cd reliverse

2. Install dependencies

bun install

This installs all dependencies for all workspaces using Bun's fast package manager.

3. Set up environment variables

Copy the example environment file and configure your variables:

cp .env.example .env
# Edit .env with your configuration

See Environment Variables for detailed configuration guidance.

Development Workflow

Running Applications

Use our convenient scripts for development:

# Run all apps in development mode
bun run dev

# Run specific apps
bun run dev:web          # All web apps
bun run dev:native       # All native apps

# Run individual apps (legacy scripts)
bun run deprecated:web:reliverse    # Main web app
bun run deprecated:docs             # Documentation
bun run deprecated:api              # Backend API

Building for Production

# Build all apps
bun run build

# Build specific app
bun run dler build --filter @repo/apps-web-reliverse

Code Quality Checks

We use Oxlint for fast linting and formatting:

# Check everything
bun run ck

# Fix formatting and linting issues
bun run ck:fix

# Type checking
bun run typecheck

Understanding the Apps

Web Apps (@repo/apps-web-reliverse)

The main web application built with TanStack Router:

apps/web/reliverse/
├── src/
│   ├── routes/           # Route definitions
│   ├── pages/            # Page components
│   ├── components/       # Reusable UI components
│   └── lib/              # Utilities and configs
├── vite.config.ts        # Vite configuration
└── package.json

Key Features:

File-based routing with TanStack Router
Server-side rendering with TanStack Start
AI chat integration
Modern UI with shadcn/ui components

API (@api)

Backend API built with Elysia.js:

apps/api/
├── src/
│   ├── index.ts          # Main server
│   ├── routers/          # API routes
│   └── context.ts        # Request context
└── package.json

Key Features:

RESTful API with Elysia.js
Type-safe with TypeScript
OpenAPI documentation generation

Documentation (@docs)

This documentation site built with Fumadocs:

apps/docs/
├── content/docs/         # Documentation content (MDX)
├── src/                  # Next.js app
└── fumadocs.config.ts    # Docs configuration

Package Management

Workspace Dependencies

We use Bun workspaces with centralized catalogs:

// package.json (root)
{
  "workspaces": {
    "catalog": {
      "react": "^19.2.3",
      "@typescript/native-preview": "^7.0.0-dev.20260124.1"
      // ... other shared versions
    }
  }
}

Internal Packages

Reference internal packages using workspace protocol:

{
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/auth": "workspace:*",
    "@repo/env": "workspace:*"
  }
}

Development Best Practices

Code Organization

Routes vs Pages: Route files define routing logic, page files contain UI components
Shared Components: Place reusable components in src/components/
Utilities: Keep helper functions in src/lib/
Types: Define TypeScript types near their usage

File Naming Conventions

Route files: route-name.tsx (no prefix for routes)
Page components: page-name.tsx (in pages/ directory)
Components: component-name.tsx
Utilities: utility-name.ts

TanStack Router Patterns

// routes/blog.tsx - Route definition
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/blog")({
  component: () => import("../pages/blog-page").then(({ BlogPage }) => <BlogPage />),
  head: () => ({
    meta: [{ title: "Blog | Reliverse" }],
  }),
});

// pages/blog-page.tsx - Page component
export function BlogPage() {
  return <div>Blog content</div>;
}

Styling with Tailwind

We use Tailwind CSS with custom design tokens:

// Use semantic color classes
<div className="bg-primary text-primary-foreground">
  Primary button
</div>

// Responsive design
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  Responsive grid
</div>

Database & Authentication

Convex (Database)

We use Convex for real-time database operations:

// packages/convex/schema.ts
import { defineSchema, defineTable } from "convex/server";

export default defineSchema({
  users: defineTable({
    email: v.string(),
    name: v.string(),
  }),
});

Better Auth (Authentication)

Authentication is handled by Better Auth:

// packages/auth/src/index.ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  // Configuration
});

Testing

Run tests across all workspaces:

bun run test

We use Vitest for fast, modern testing with jsdom for DOM simulation.

Deployment

Web Apps

Deployed automatically via CI/CD pipelines to Vercel.

API

Deployed to serverless platforms or containerized environments.

Documentation

Built and deployed as a static site to Vercel.

Troubleshooting

Common Issues

Build fails with "Module not found"

Run bun install to ensure all dependencies are installed
Check workspace references in package.json files

TypeScript errors

Run bun run typecheck to see detailed error messages
Check import paths and type definitions

Router not working

Ensure route files don't have - prefix (TanStack Router convention)
Check that page components are properly imported

Getting Help

Check existing issues on GitHub
Read the documentation thoroughly
Ask questions in our community channels

Contributing

See our Contributing Guide for detailed contribution guidelines.

Ready to start building? Check out our API Reference or dive into the source code! 🚀

Getting Started with Reliverse

On this page