Welcome to Bleverse. This guide walks you through creating an account and taking your first steps on the platform.

1. Visit Bleverse

Go to bleverse.com and create an account.

2. Create Your Profile

Set up your profile with a display name and any information you want to share. Profile visibility is under your control: you decide what others can see.

3. Personalization Options

During onboarding, you can choose your preferences. Personalization is explicit and user-controlled: nothing happens without your consent. You can change these settings at any time.

4. Explore

Once your account is set up, you can:

Add projects to your profile
Adjust visibility and privacy settings
Optionally enable the feed: it's not required
Connect with others who share your interests

Next Steps

Learn about features: profile, projects, feed, and visibility
Understand our philosophy: principles behind Bleverse
Read about privacy and consent: how your data is handled

Getting Started with Bleverse

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

What is Bleverse?

Bleverse 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

bleverse/
├── apps/                    # Applications
│   ├── web/                 # Web applications
│   │   ├── bleverse/        # 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/bleverse.git
cd bleverse

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:bleverse    # 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-bleverse

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-bleverse)

The main web application built with TanStack Router:

apps/web/bleverse/
├── 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 | Bleverse" }],
  }),
});

// 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.

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 Bleverse

On this page