Skip to main content

Ring App Style Guide

This style guide outlines the coding conventions, file structure, naming conventions, and best practices for the Ring main web app project. Following these guidelines will ensure consistency across the codebase and improve maintainability.

Table of Contents​

  1. File Structure
  2. Naming Conventions
  3. TypeScript and JavaScript
  4. React and Next.js
  5. CSS and Styling
  6. Testing
  7. Internationalization
  8. State Management
  9. API and Data Fetching
  10. Performance
  11. Accessibility
  12. Documentation

File Structure​

  • Use the App Router structure provided by Next.js 15.
  • Keep related files close to each other in the directory structure.
  • Use lowercase with hyphens for directory and file names, except for React components.

/app                 # Next.js 15 App Router pages and layouts
/components          # Reusable React components
/common              # Commonly used components
/layout              # Layout components
/pages               # Page-specific components
/providers           # Context providers
/ui                  # UI components (buttons, forms, etc.)
/constants           # Constant values and configurations
/hooks               # Custom React hooks
/lib                 # Utility functions and libraries
/public              # Static assets
/styles              # Global styles and Tailwind CSS configuration
/types               # TypeScript type definitions
/**tests**           # Test files

Naming Conventions​

  • Use PascalCase for React component names (e.g., Button.tsx, Header.tsx).
  • Use camelCase for function names, variables, and file names that are not components.
  • Use UPPER_CASE for constant values.
  • Use kebab-case for CSS class names and file names (except for components).

TypeScript and JavaScript​

  • Use TypeScript for all new files.
  • Enable strict mode in tsconfig.json.
  • Use ES6+ features when possible.
  • Use const for variables that won't be reassigned, and let for those that will.
  • Avoid using any type; use proper type annotations or unknown if necessary.
  • Use interface for object shapes and type for unions, intersections, and mapped types.

React and Next.js​

  • Use functional components with hooks instead of class components.
  • Use the useCallback hook for memorizing functions passed as props to child components.
  • Use the useMemo hook for expensive computations.
  • Implement proper error boundaries using the ErrorBoundary component.
  • Use Next.js built-in components like Link and Image for optimal performance.
  • Implement proper SEO practices using Next.js metadata API.

CSS and Styling​

  • Use Tailwind CSS for styling components.
  • Use CSS modules for component-specific styles that can't be achieved with Tailwind.
  • Follow the BEM (Block Element Modifier) naming convention for custom CSS classes.
  • Use the cn utility function from lib/utils.ts for conditional class names.

Testing​

  • Write unit tests for all components and utility functions.
  • Use Jest as the testing framework and React Testing Library for component testing.
  • Name test files with the .test.ts or .test.tsx extension.
  • Aim for high test coverage, especially for critical parts of the application.

Internationalization​

  • Use the custom useLanguage hook for translations.
  • Store all text content in the locales directory JSON files.
  • Use the t function from the useLanguage hook to translate text in components.

State Management​

  • Use React's built-in useState and useContext for local and shared state.

API and Data Fetching​

  • Use the fetch API for data fetching.
  • Implement proper error handling and loading states for all API calls.
  • Use Next.js API routes for backend functionality.

Performance​

  • Implement code-splitting and lazy loading for large components or pages.
  • Use Next.js Image component for optimized image loading.
  • Minimize the use of third-party libraries and consider their impact on bundle size.

Accessibility​

  • Ensure all interactive elements are keyboard accessible.
  • Use proper ARIA attributes where necessary.
  • Maintain a color contrast ratio of at least 4.5:1 for text and background colors.
  • Provide alternative text for images and icons.

Documentation​

  • Include JSDoc comments for functions, components, and complex logic.
  • Keep the README.md file up-to-date with project setup instructions and important information.
  • Document any non-obvious design decisions or complex implementations.

By following these guidelines, we can maintain a consistent and high-quality codebase for the Ring app.