Tech Stack - Evaly

Overview

Evaly is built with modern, cutting-edge technologies focused on developer experience, performance, and scalability. The stack is carefully chosen to provide real-time capabilities, serverless architecture, and excellent TypeScript support.

Frontend Stack

Core Framework

React 19

Latest React with improved performance and concurrent featuresVersion: 19.2.0

TanStack Start

React 19 meta-framework with file-based routingVersion: 1.134.9

TanStack Router

Type-safe routing with nested layoutsVersion: 1.134.4

TanStack Query

Powerful data fetching and cachingVersion: 5.90.6

Styling & UI

Styling
Component Library
Additional UI

Tailwind CSS v4 (4.1.12)

Custom design tokens
JIT compilation
Vite plugin integration (@tailwindcss/vite)
Typography plugin (@tailwindcss/typography)
Animation utilities (tailwindcss-animate)
Utility merging (tailwind-merge)

shadcn/ui + Radix UIComponents:

@radix-ui/react-accordion
@radix-ui/react-alert-dialog
@radix-ui/react-avatar
@radix-ui/react-checkbox
@radix-ui/react-collapsible
@radix-ui/react-dialog
@radix-ui/react-dropdown-menu
@radix-ui/react-hover-card
@radix-ui/react-label
@radix-ui/react-navigation-menu
@radix-ui/react-popover
@radix-ui/react-progress
@radix-ui/react-radio-group
@radix-ui/react-scroll-area
@radix-ui/react-select
@radix-ui/react-separator
@radix-ui/react-slider
@radix-ui/react-slot
@radix-ui/react-switch
@radix-ui/react-tabs
@radix-ui/react-toggle
@radix-ui/react-tooltip

vaul (1.1.2) - Drawer component
cmdk (1.1.1) - Command menu
sonner (2.0.7) - Toast notifications
class-variance-authority (0.7.1) - CVA for component variants

Rich Text Editing

TipTap (2.12.0) - Extensible rich text editor

Core

@tiptap/react - React integration
@tiptap/starter-kit - Essential extensions

Extensions

@tiptap/extension-character-count - Character counting
@tiptap/extension-code-block-lowlight - Syntax highlighting
@tiptap/extension-image - Image support
@tiptap/extension-link - Link handling
@tiptap/extension-placeholder - Placeholder text
@tiptap/extension-text-style - Text styling
@tiptap/extension-underline - Underline formatting

Form Management

React Hook Form

Performant form state managementVersion: 7.56.3

Zod

TypeScript-first schema validationVersion: 4.1.12

Hookform Resolvers

Integration between React Hook Form and ZodVersion: 5.0.1

TanStack Zod Adapter

Router integration with ZodVersion: 1.139.12

Data Visualization

Charts
Animations
Other

Recharts (2.15.4)

Composable charting library
Built on D3.js
Responsive charts
Customizable tooltips

Motion (12.23.24) - Framer Motion fork

Declarative animations
Gesture handling
Layout animations

GSAP (3.13.0)

Advanced animation library
Timeline sequencing
SVG morphing

@number-flow/react (0.5.10) - Animated number transitions
canvas-confetti (1.9.4) - Celebration animations
lenis (1.3.15) - Smooth scrolling

Specialized Libraries

Icons & Assets

@phosphor-icons/react (2.1.10) - Icon library
qrcode.react (4.2.0) - QR code generation

Date & Time

date-fns (4.1.0) - Date utilities
dayjs (1.11.13) - Date parsing/formatting
react-day-picker (9.11.1) - Date picker component

PDF

pdf-lib (1.17.1) - PDF generation/manipulation
pdfjs-dist (5.4.394) - PDF rendering

Tables & Lists

@tanstack/react-table (8.21.3) - Headless table library
@tanstack/react-virtual (3.13.8) - Virtual scrolling

Layout

react-resizable-panels (3.0.1) - Resizable panel layouts
react-moveable (0.56.0) - Draggable/resizable elements

Input

input-otp (1.4.2) - OTP input component

Utils

@uidotdev/usehooks (2.4.1) - Collection of React hooks
html-react-parser (5.2.10) - HTML string parsing

Backend Stack

Convex Platform

Convex Core

Serverless backend with real-time databaseVersion: 1.28.0

Convex Auth

Authentication with multi-provider supportVersion: 0.0.90

Convex Helpers

Community utilities and patternsVersion: 0.1.104

React Query Integration

TanStack Query integrationVersion: 0.0.0-alpha.11

Convex Extensions

Storage
Real-time
Billing
AI

@convex-dev/r2 (0.7.3)

Cloudflare R2 integration
Direct file uploads
CDN support

@convex-dev/presence (0.3.0)

Presence tracking
Heartbeat system
Active user monitoring

@convex-dev/polar (0.7.2)

Subscription management
Usage tracking
Plan enforcement

@convex-dev/agent (0.3.0)

AI agent framework
Conversation management

AI Integration

Google Generative AI

Google Gemini API for AI question generationPackage: @ai-sdk/google (2.0.33)Features:

Question generation
Option suggestions
Content translation
Result analysis

Authentication

Auth.js Core (@auth/core 0.37.0)

Multi-provider OAuth
Session management
JWT tokens
Provider support:
- Google OAuth
- Email/Password
- Magic links

Development Tools

Build System

Bundler
Compiler
Router Plugin

Vite (6.1.0)

Lightning-fast HMR
Optimized builds
Plugin ecosystem

Plugins:

@vitejs/plugin-react - React support
vite-tsconfig-paths - Path alias resolution
@tailwindcss/vite - Tailwind integration
@cloudflare/vite-plugin - Cloudflare Workers

TypeScript (5.8.3)

Strict type checking
Path aliases
Incremental builds

Babel:

babel-plugin-react-compiler (1.0.0) - React Compiler

@tanstack/router-plugin (1.114.3)

File-based routing codegen
Type-safe route definitions

Testing

Vitest

Unit & integration testingVersion: 3.0.5

React Testing Library

Component testing utilitiesVersion: 16.2.0

Playwright

End-to-end testingVersion: 1.57.0

jsdom

Browser environment simulationVersion: 26.0.0

Content Management

Content Collections - MDX content management

Core

@content-collections/core (0.12.0) - Core functionality
@content-collections/vite (0.2.7) - Vite integration

Processing

@content-collections/mdx (0.2.2) - MDX support
remark-gfm (4.0.1) - GitHub Flavored Markdown

Deployment

Cloudflare Platform

Workers
R2 Storage

Wrangler (4.45.3)

CLI for Cloudflare Workers
Local development
Production deployments
Type generation

Plugin:

@cloudflare/vite-plugin (1.16.1)

Cloudflare R2

S3-compatible object storage
Global CDN
Zero egress fees
Integration via @convex-dev/r2

Runtime & Package Manager

Bun

JavaScript runtime and package managerNot Node.js - Bun is used exclusivelyFeatures:

Fast package installation
Built-in test runner
Native TypeScript support
Drop-in Node.js replacement

Vinxi

App composition frameworkVersion: 0.5.6Powers TanStack Start’s server capabilities

Monitoring & Analytics

Web Vitals

Core Web Vitals measurementPackage: web-vitals (4.2.4)Metrics:

LCP (Largest Contentful Paint)
FID (First Input Delay)
CLS (Cumulative Layout Shift)
TTFB (Time to First Byte)

Development Commands

# Install dependencies
bun install

# Start dev servers (already running in development)
bun run dev              # Frontend dev server
npx convex dev          # Backend dev server

Package Management

Key Dependencies Summary

Total Dependencies: 104 production packages Total Dev Dependencies: 25 development packages

Stability Notes

Some packages are in alpha/beta:

@convex-dev/react-query (alpha.11)
React 19 (stable but recent)
Tailwind CSS v4 (latest)

The project uses exact versions for Convex packages to ensure compatibility with the Convex platform.

TypeScript Configuration

Path Aliases:

@/* → ./src/*
@convex/* → convex/*
content-collections → ./.content-collections/generated

Compiler Options:

Strict mode enabled
JSX: React 19
Module resolution: Bundler
ES2022 target

Type Definitions

Custom Types

@types/node - Node.js types
@types/react - React 19 types
@types/react-dom - React DOM types
@types/canvas-confetti - Canvas confetti types
@types/pdfjs-dist - PDF.js types
@types/recharts - Recharts types

Environment Variables

Required Variables

Frontend
Backend

.env.local

CONVEX_DEPLOYMENT=your-deployment-name

Convex Dashboard

# Auth
AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret
SITE_URL=https://your-domain.com

# Storage (Cloudflare R2)
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
R2_BUCKET=your-bucket-name
R2_ENDPOINT=https://your-account.r2.cloudflarestorage.com
R2_CDN_URL=https://your-cdn-url.com
R2_TOKEN=your-r2-token

# Email (Plunk)
PLUNK_SECRET_API_KEY=your-plunk-api-key
PLUNK_API_URL=https://api.useplunk.com
PLUNK_FROM_EMAIL=[email protected]

# AI (Google Gemini)
GOOGLE_GENERATIVE_AI_API_KEY=your-gemini-api-key

# Auth Tokens (auto-generated by Convex Auth)
JWKS=auto-generated
JWT_PRIVATE_KEY=auto-generated

Version Strategy

Major versions: Pinned for stability (e.g., @tanstack/react-query: 5.90.6)
Convex packages: Exact versions for platform compatibility
UI libraries: Caret ranges for patch updates (e.g., ^2.1.10)
Dev tools: Latest compatible versions

Run bun update regularly to get security patches while respecting version constraints.

Self-Hosting

Technical

Contributing

​Overview

​Frontend Stack

​Core Framework

React 19

TanStack Start

TanStack Router

TanStack Query

​Styling & UI

​Rich Text Editing

​Form Management

React Hook Form

Zod

Hookform Resolvers

TanStack Zod Adapter

​Data Visualization

​Specialized Libraries

​Backend Stack

​Convex Platform

Convex Core

Convex Auth

Convex Helpers

React Query Integration

​Convex Extensions

​AI Integration

Google Generative AI

​Authentication

​Development Tools

​Build System

​Testing

Vitest

React Testing Library

Playwright

jsdom

​Content Management

​Deployment

​Cloudflare Platform

​Runtime & Package Manager

Bun

Vinxi

​Monitoring & Analytics

Web Vitals

​Development Commands

​Package Management

​Key Dependencies Summary

​Stability Notes

​TypeScript Configuration

​Type Definitions

​Environment Variables

​Required Variables

​Version Strategy

Build docs developers (and LLMs) love

Overview

Frontend Stack

Core Framework

Styling & UI

Rich Text Editing

Form Management

Data Visualization

Specialized Libraries

Backend Stack

Convex Platform

Convex Extensions

AI Integration

Authentication

Development Tools

Build System

Testing

Content Management

Deployment

Cloudflare Platform

Runtime & Package Manager

Monitoring & Analytics

Development Commands

Package Management

Key Dependencies Summary

Stability Notes

TypeScript Configuration

Type Definitions

Environment Variables

Required Variables

Version Strategy