Workspace Layout

Understand how the Raypx Turborepo is structured and what each package delivers.

Monorepo at a Glance

Raypx is a pnpm monorepo orchestrated by Turborepo. It contains 3 applications and 12 shared packages that work together to provide a complete full-stack development platform.

src/routes/ # File-based routing

src/components/ # React components

public/ # Static assets

app/ # Secondary application

docs/ # Fumadocs documentation site

packages/ # Shared packages (see below)

scripts/ # Build & dev scripts

turbo.json # Turborepo build pipeline

All packages use the @raypx/* namespace and are consumed as TypeScript source (no build step for packages, only apps).

Applications

App	Description	Port	Tech
web	Main TanStack Start app with auth, UI, and API	3000	TanStack Start, React 19
app	Secondary application	3000	TanStack Start, React 19
docs	Documentation site powered by Fumadocs	3001	Fumadocs, TanStack Start

Packages

Core Infrastructure

Package	Description	Key Features
@raypx/auth	Authentication system powered by Better Auth	OAuth, Magic Link, Email OTP, 2FA ready
@raypx/database	Database layer with Drizzle ORM	PostgreSQL, migrations, vector search
@raypx/rpc	Type-safe API layer	ORPC, procedures, middleware
@raypx/config	Environment variable validation	Zod schemas, type-safe env vars

Services

Package	Description	Key Features
@raypx/email	Email service	Resend, Nodemailer, React Email templates
@raypx/storage	File storage	S3, R2, local filesystem, Sharp image processing
@raypx/logger	Logging utilities	Consola-based logging, structured output
@raypx/observability	Observability tools	Sentry error tracking, OpenTelemetry tracing

UI & Frontend

Package	Description	Key Features
@raypx/design-system	Component library	60+ shadcn/ui components, Tailwind v4
@raypx/seo	SEO utilities	Meta tags, Open Graph, JSON-LD

Utilities

Package	Description	Key Features
@raypx/shared	Shared utilities	Pure functions, constants, types
@raypx/tsconfig	TypeScript configs	Shared tsconfig presets

Package Dependencies

Packages can depend on each other, but follow these rules:

@raypx/shared has zero dependencies (pure utilities)
@raypx/design-system only depends on shared (presentation logic only)
@raypx/auth depends on database, email
@raypx/rpc depends on auth, database for protected procedures
@raypx/email depends on config, logger
@raypx/storage depends on config, logger
@raypx/observability depends on config

Tooling & Configuration

Development Tools

Biome (biome.json) – Replaces ESLint + Prettier for linting and formatting
TypeScript (packages/tsconfig/) – Shared configs with strict mode enabled
Turborepo (turbo.json) – Build orchestration and caching
Vitest – Unit testing framework (jsdom)
Lefthook – Git hooks for pre-commit checks
Knip – Find unused code, exports, and dependencies
Changesets – Version management and changelog generation

Build System

IMPORTANT: Only apps/ have build scripts. All packages/ are consumed as TypeScript source.

✅ apps/web, apps/app, apps/docs – Have build scripts (deployable)
❌ packages/* – NO build scripts (consumed as TS source by apps)

This approach:

Eliminates double-compilation
Provides better type errors in development
Speeds up development server startup

Working with the Monorepo

Running Commands

# Workspace-level commands (all packages)
turbo dev                   # Start all apps
turbo build                 # Build all apps
turbo typecheck             # Check all TypeScript
turbo test                  # Run all tests

# App-specific commands
turbo dev --filter=web      # Just web app
turbo dev --filter=docs     # Just docs

# Package-specific commands (still use pnpm for non-turbo tasks)
pnpm --filter @raypx/database studio       # Drizzle Studio
pnpm --filter @raypx/database migrate      # Run migrations
pnpm --filter @raypx/database push         # Push schema to database
pnpm --filter @raypx/design-system shadcn add button  # Add UI component

# Turborepo filters (for cached tasks)
turbo build --filter=web              # Build web app only
turbo test --filter=...^web           # Test web and its dependencies
turbo build --filter=...^web          # Build web and its dependencies

Adding Dependencies

# Add to specific package
pnpm --filter web add react-query
pnpm --filter @raypx/design-system add -D @types/node

# Add to workspace root (dev tools)
pnpm add -Dw typescript

# Use catalog dependencies (preferred)
# Edit package.json catalog, then:
pnpm install

Catalog Dependencies

This project uses pnpm catalogs (via package.json workspaces.catalog) for centralized version management:

catalog:
  react19: ^19.2.0
  tailwindv4: ^4.1.17

Reference in package.json:

{
  "dependencies": {
    "react": "catalog:react19",
    "tailwindcss": "catalog:tailwindv4"
  }
}

Generated Files

apps/docs/source.generated.ts – Fumadocs metadata (auto-generated)
apps/web/.vinxi/ – TanStack Start build cache (gitignored)
.turbo/ – Turborepo cache (gitignored)

Do not edit generated files manually. They are recreated on build or dev server start.

Workspace Layout

On this page