Frontend Style Guide

This guide outlines the coding standards, conventions, and best practices for our frontend codebase across all platforms.

Technology Stack

Mobile Apps (Primary Frontend)

• React Native with Expo for iOS and Android apps
• TypeScript for type safety and better development experience
• React patterns and hooks for component development

Web Properties

• Next.js for OurOtters web app, marketing site, and Studio
• TypeScript for consistent type safety across platforms
• React for component architecture

Code Organization

Project Structure

src/
├── components/          # Reusable UI components
├── screens/            # App screens/pages (mobile)
├── pages/              # Next.js pages (web)
├── hooks/              # Custom React hooks
├── utils/              # Utility functions
├── types/              # TypeScript type definitions
├── constants/          # App constants and configuration
└── assets/             # Images, fonts, and static assets

Component Architecture

• Use functional components with hooks over class components
• Implement custom hooks for reusable logic
• Follow single responsibility principle for components
• Use TypeScript interfaces for all props and data structures

Naming Conventions

Files and Directories

• PascalCase for component files: UserProfile.tsx
• camelCase for utility files: dateHelpers.ts
• kebab-case for page routes: user-profile.tsx
• Use index.ts files for clean imports

Components and Functions

• PascalCase for React components: <UserAvatar />
• camelCase for functions and variables: getUserData()
• UPPER_SNAKE_CASE for constants: API_BASE_URL

TypeScript Guidelines

Type Definitions

• Define interfaces for all component props
• Use strict TypeScript configuration
• Prefer interface over type for object shapes
• Use generic types for reusable components

interface UserProfileProps {
  userId: string;
  onUpdate: (user: User) => void;
  showAvatar?: boolean;
}
 
const UserProfile: React.FC<UserProfileProps> = ({
  userId,
  onUpdate,
  showAvatar = true
}) => {
  // Component implementation
};

State Management

• Use React's built-in state management (useState, useContext)
• Implement custom hooks for complex state logic
• Consider Zustand or Redux Toolkit for global state if needed

React Native Specific Guidelines

Platform-Specific Code

• Use Platform.OS for platform-specific logic
• Create .ios.tsx and .android.tsx files when needed
• Test on both platforms during development

Performance Optimization

• Use React.memo() for expensive components
• Implement useMemo() and useCallback() for optimization
• Use FlatList for large data sets
• Optimize images with appropriate formats and sizes

Navigation

• Use React Navigation for app navigation
• Implement deep linking for better user experience
• Follow navigation best practices for accessibility

Next.js Specific Guidelines

Routing and Pages

• Use file-based routing in the pages/ directory
• Implement API routes in pages/api/
• Use dynamic routing with [slug].tsx files

Performance

• Optimize images with next/image
• Use getStaticProps and getServerSideProps appropriately
• Implement proper caching strategies

Styling Guidelines

React Native Styling

• Use StyleSheet.create() for component styles
• Follow consistent spacing and sizing patterns
• Use responsive design principles
• Implement dark mode support

Web Styling

• Use CSS modules or styled-components
• Follow responsive design principles
• Maintain consistent design system across platforms

Testing Standards

Unit Testing

• Write tests for all utility functions
• Test component props and state changes
• Use Jest and React Testing Library
• Aim for meaningful test coverage

Integration Testing

• Test user flows and interactions
• Mock external dependencies appropriately
• Test platform-specific functionality

Code Quality

ESLint and Prettier

• Use ESLint with React and TypeScript rules
• Configure Prettier for consistent formatting
• Set up pre-commit hooks for code quality

Code Review Guidelines

• Review for TypeScript type safety
• Check for proper error handling
• Ensure accessibility standards are met
• Verify cross-platform compatibility

Best Practices

Error Handling

• Implement proper error boundaries
• Use try/catch for async operations
• Provide meaningful error messages to users

Accessibility

• Use semantic HTML elements (web)
• Implement proper accessibility labels (mobile)
• Test with screen readers
• Ensure keyboard navigation works properly

Security

• Validate all user inputs
• Sanitize data before rendering
• Use HTTPS for all API calls
• Never store sensitive data in client-side code