Skip to content

AGENTS.md

Latest commit

 

History

History
165 lines (113 loc) · 4.52 KB

AGENTS.md

File metadata and controls

165 lines (113 loc) · 4.52 KB

AGENTS.md - Agent Guidelines for awesome-github-app

Project Overview

A modern GitHub mobile client built with Expo 55 (CNG), React Native 0.83, Expo Router, and Uniwind (Tailwind CSS for React Native). Uses bun as the package manager.

Commands

Development

bun run start       # Start Expo dev server
bun run android     # Prebuild → run on Android
bun run ios         # Run on iOS simulator
bun run web         # Web preview
bun run native:sync # Regenerate android/ ios/ from app.json
bun run go          # Format, lint, typecheck, then start dev server

Quality Assurance

bun run typecheck   # TypeScript strict check (tsc --noEmit)
bun run lint        # ESLint check
bun run lint:fix   # ESLint with auto-fix
bun run format     # Prettier (auto-sorts imports)
bun run prebuild   # format && lint:fix && typecheck

Testing

bun test                          # Run all tests
bun test --watch                  # Watch mode
bun test path/to/test             # Run a single test file
bun test -t "test name"            # Run tests matching a pattern
bun test --coverage                # With coverage

Code Style

Formatting (Prettier)

  • Double quotes (", not ')
  • Trailing commas everywhere
  • 2-space indent, 80-character print width
  • singleAttributePerLine: true for JSX
  • Run bun run format before committing — auto-sorts imports

TypeScript

  • Strict mode enabled
  • Use explicit types for function parameters and return values
  • Use interface for object shapes, type for unions/intersections
  • ESLint allows any for GitHub API responses (@typescript-eslint/no-explicit-any: warn)

Imports

  • Auto-sorted by prettier-plugin-sort-imports — don't manually order
  • Use barrel exports: src/components/ui/index.ts, src/lib/api/hooks/index.ts

Naming Conventions

Type Convention Examples
Components PascalCase Button.tsx, AuthContext.tsx
Hooks camelCase with use useAuth.ts, useNotifications.ts
Utils/lib camelCase github.ts, theme.ts
Booleans is/has/can/should isLoading, hasError
Types PascalCase ButtonProps, User

Component Patterns

UI Components (src/components/ui/)

export interface ButtonProps {
  title: string;
  variant?: ButtonVariant;
}

export function Button({ title, variant = "primary" }: ButtonProps) {
  return <Pressable className={...}>{title}</Pressable>;
}

Styling

  • Use Uniwind (className prop) for layout/colors
  • Use StyleSheet.create() for complex styles and animations
  • Use expo-image (<Image />), not React Native's built-in Image
  • Custom utilities: bg-background, bg-card, bg-primary, text-primary, etc.
  • Use dark: prefix for dark mode

Icons

  • Always use Ionicons from expo-vector-icons
  • Type: icon?: keyof typeof Ionicons.glyphMap

Architecture

Routing (Expo Router)

  • Routes in src/app/ with file-based routing
  • Dynamic segments: repo/[owner]/[repo]/
  • Auth gating in root _layout.tsx

Data Fetching

  • Hooks call getOctokit() / getGraphQL() internally — never pass client as prop
  • TanStack Query: staleTime: 5 min, retry: 2, refetchOnWindowFocus: false
  • Infinite scroll: useInfiniteQuery with page-based pagination (pageParam starts at 1, 30 items/page)

Provider Stack (outermost first)

QueryClientProvider → ThemeProvider → ToastProvider → AuthProvider

Auth

  • Token in expo-secure-store under github_access_token
  • Call resetOctokit() after token changes

Error Handling

  • Let TanStack Query handle loading/error states via useQuery/useMutation
  • Use toast notifications for user-facing errors
  • Use unknown for catch blocks, then narrow

Testing

  • Preset: jest-expo, Environment: jsdom
  • Path aliases: @/* maps to src/*
  • Test files: *.test.tsx or *.test.ts, co-locate with component
  • See jest.setup.js for existing mocks

Git Workflow

  1. Run bun run prebuild (format, lint:fix, typecheck)
  2. Run bun test to ensure tests pass

CNG (Continuous Native Generation)

  • android/ and ios/ are git-ignored
  • Generated by expo prebuild
  • Run bun run native:sync after changing app.json or native dependencies