CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Follow (Folo) is a modern RSS aggregator and content management platform with multiple applications across different platforms. It's built as a monorepo using pnpm workspaces with Turbo for build orchestration.

Repository Structure

Applications (`apps/`)

apps/desktop/ - Electron desktop application with main and renderer processes
apps/mobile/ - React Native mobile app for iOS and Android
apps/ssr/ - Server-side rendered web application
apps/mobile/web-app/ - HTML renderer for mobile web views

Packages (`packages/`)

packages/internal/ - Internal shared packages (components, database, hooks, store, etc.)
packages/configs/ - Shared configuration files (Tailwind, TypeScript)
packages/utils/ - Utility functions and helpers
packages/readability/ - Content readability parsing
packages/vite-plugin-route-builder/ - Custom Vite plugin for route generation

Essential Commands

Development

# Install dependencies (from root)
pnpm install

# Desktop app development (browser - recommended)
cd apps/desktop && pnpm run dev:web

# Desktop app development (Electron)
cd apps/desktop && pnpm run dev:electron

# Mobile app development
cd apps/mobile && pnpm run dev

# SSR development
cd apps/ssr && pnpm run dev

# Build web version
pnpm run build:web

Code Quality

# Lint all code
pnpm run lint

# Fix linting issues
pnpm run lint:fix

# TypeScript linting
pnpm run lint:tsl

# Format code
pnpm run format

# Type checking
pnpm run typecheck

# Run tests
pnpm run test

Package Management

# Build shared packages
pnpm run build:packages

# Generate i18n templates
pnpm run generator:i18n-template

# Sync icons from SVG to React Native
pnpm run icons:sync

Architecture Guidelines

Multi-Platform Architecture

Desktop: Electron app with main/renderer processes, using Vite for both
Mobile: React Native with Expo, shared UI components with web
Web/SSR: Next.js-style SSR application for server-side rendering
Shared Logic: Common business logic in packages/internal/

State Management

Jotai for atomic state management across all platforms
Zustand for complex state stores (in packages/internal/store/)
React Query for server state management

Styling

Tailwind CSS for styling across all platforms
Platform-specific Tailwind configs in each app
Shared Tailwind utilities in packages/configs/tailwindcss/

UIKit Colors for Desktop Components

For desktop components (apps/desktop/**/*) and shared UI components (packages/internal/components/**/*), use Apple UIKit color system with Tailwind classes. Important: Always use the correct Tailwind prefix for each color category:

System Colors: text-red, bg-red, border-red (same for orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown, gray)

Fill Colors:

Background: bg-fill, bg-fill-secondary, bg-fill-tertiary, bg-fill-quaternary, bg-fill-quinary, bg-fill-vibrant, bg-fill-vibrant-secondary, bg-fill-vibrant-tertiary, bg-fill-vibrant-quaternary, bg-fill-vibrant-quinary
Border: border-fill, border-fill-secondary, etc.

Text Colors: text-text, text-text-secondary, text-text-tertiary, text-text-quaternary, text-text-quinary, text-text-vibrant, text-text-vibrant-secondary, text-text-vibrant-tertiary, text-text-vibrant-quaternary, text-text-vibrant-quinary

Material Colors: bg-material-ultra-thick, bg-material-thick, bg-material-medium, bg-material-thin, bg-material-ultra-thin, bg-material-opaque

Control Colors: bg-control-enabled, bg-control-disabled

Interface Colors: bg-menu, bg-popover, bg-titlebar, bg-sidebar, bg-selection-focused, bg-selection-focused-fill, bg-selection-unfocused, bg-selection-unfocused-fill, bg-header-view, bg-tooltip, bg-under-window-background

These colors automatically adapt to light/dark mode following Apple's design system. Remember to use the appropriate prefix (text-, bg-, border-) based on the CSS property you're styling.

Icons

For icon usage, prioritize the MingCute icon library with the i-mgc- prefix. Icons are available in the format i-mgc-[icon-name]-[style] where style can be re (regular), fi (filled), etc.

Important: Always try to find an appropriate icon with the i-mgc- prefix first. Only use the i-mingcute- prefix as a fallback when no suitable i-mgc- icon exists.

Examples:

Preferred: i-mgc-copy-cute-re, i-mgc-external-link-cute-re
Fallback only: i-mingcute-copy-line (only if no mgc equivalent exists)

Database

Drizzle ORM with SQLite for local data storage
Platform-specific database implementations in packages/internal/database/
Migration system with versioned SQL files

Internationalization

i18next for internationalization
Locale files in locales/ directory organized by feature
Custom ESLint rules for i18n validation

i18n Writing Guidelines

Follow i18next formatting guidelines
Use flat keys only - Use . notation for separation, no nested objects
For plural-sensitive languages, use _one and _other suffixes
Avoid conflicting flat keys - During build, flat dot-separated keys (e.g., 'exif.custom.rendered.custom') are automatically converted to nested objects, which can cause conflicts. For example, 'exif.custom.rendered.custom' conflicts with 'exif.custom.rendered'. Avoid such patterns.

Example:

{
  "personalize.title": "Personalization",
  "personalize.prompt.label": "Personal Prompt",
  "shortcuts.add": "Add Shortcut",
  "shortcuts.validation.required": "Name and prompt are required"
}

Development Setup Notes

Prerequisites

Enable Corepack: corepack enable && corepack prepare
For mobile development: macOS with Xcode required

Environment Setup

Copy .env.example to .env in relevant app directories
For development, use VITE_API_URL=https://api.follow.is
Browser development uses https://app.folo.is/__debug_proxy for API access

Mobile Development

iOS development requires Xcode and iOS simulator
Native module development in apps/mobile/native/
Use pnpm expo prebuild --clean for clean builds

Code Organization Patterns

Import Conventions

Use pathe instead of node:path for cross-platform compatibility
Shared utilities should be imported from packages/internal/
Platform-specific code should be clearly separated

Component Structure

Shared UI components in packages/internal/components/
Platform-specific components in respective app directories
Use TypeScript interfaces for component props

Error Handling

Custom error parsing utilities in packages/internal/utils/
Sentry integration for error reporting across platforms

Build and Deployment

Build Outputs

Desktop: apps/desktop/out/ for packaged applications
Web: apps/desktop/out/web/ for static web assets
Mobile: Platform-specific build directories

Turbo Configuration

Build orchestration via turbo.json
Dependency-aware builds with output caching
Parallel execution for independent packages

Testing Strategy

Vitest for unit testing across packages
Platform-specific test configurations
Test files co-located with source code

Key Dependencies

Build: Vite, Turbo, pnpm workspaces
Frontend: React 19, Electron, React Native, Expo
State: Jotai, Zustand, TanStack Query
Styling: Tailwind CSS, Framer Motion
Database: Drizzle ORM, SQLite
Utils: Day.js, Zod, i18next

Innei/follow.md