.context.codebase.md

Mochi Web Codebase Context

Project Overview

Mochi Web is a front-end repository for the Mochi Web application. It's built using modern web technologies and follows best practices for scalable and maintainable web development.

Tech Stack

• NextJS - React framework for building web applications
• TailwindCSS - Utility-first CSS framework
• TypeScript - Typed superset of JavaScript
• wagmi - React Hooks library for Ethereum
• iconify - Icon framework
• headlessui - Unstyled, fully accessible UI components
• @dwarvesf/react-hooks - Custom React hooks
• @dwarvesv/react-utils - React utility functions
• Storybook - Tool for developing UI components in isolation
• ESLint - JavaScript linting utility
• Prettier - Code formatter

Project Structure

The project follows a typical Next.js structure with some custom directories:

• app/: App router components and layouts
• components/: Reusable React components
• constants/: Constant values and configurations
• context/: React context providers
• hooks/: Custom React hooks
• pages/: Next.js pages (for pages router)
• public/: Static assets
• store/: State management (likely using Zustand)
• styles/: Global styles and CSS modules
• types/: TypeScript type definitions
• utils/: Utility functions
• .storybook/: Storybook configuration

Styling

The project uses TailwindCSS for styling, with a custom configuration defined in tailwind.config.js. This includes:

• Custom color palette
• Custom font families
• Extended theme configurations for spacing, shadows, and animations

Design Conventions

Based on the analysis of Storybook files, the following design conventions are used in the project:

1. Component Variants: Components often have multiple variants or appearances. For example, buttons have the following appearances:

   • primary
   • secondary
   • tertiary
   • gray
   • mochi
   • text
   • pill

   Example usage:

   <Button appearance="primary">Primary Button</Button>
   <Button appearance="secondary">Secondary Button</Button>

2. Component Sizes: Components typically come in multiple sizes. For buttons, the sizes are:

   • xs (extra small)
   • sm (small)
   • base (default)
   • icon
   • icon-sm (small icon)

   Example usage:

   <Button size="sm">Small Button</Button>
   <Button size="base">Default Size Button</Button>

3. Consistent Prop Naming: Props for appearance and size are consistently named across components (e.g., appearance and size).

4. Storybook Usage: Each component has a corresponding Storybook file (e.g., button.stories.tsx) that documents its usage and variants.

5. Autodocs: Storybook's Autodocs feature is used to automatically generate documentation for components.

6. Tailwind CSS: Tailwind classes are used for layout and styling within components and their stories. This ensures consistency in spacing, colors, and other design aspects.

7. TypeScript: Components and their stories are written in TypeScript, providing type safety and better developer experience.

8. Centralized Layout: Stories often use a centered layout for better visibility in Storybook.

9. Color Scheme: The project uses a consistent color scheme across components. The main colors include:

   • Primary: Used for primary actions and key UI elements
   • Secondary: Used for secondary actions and less prominent UI elements
   • Mochi: A custom color specific to the Mochi brand
   • Gray: Used for neutral UI elements and text Refer to the Tailwind configuration for the exact color values.

10. Accessibility: Components are designed with accessibility in mind. This includes:

    • Proper contrast ratios for text and background colors
    • Keyboard navigation support
    • ARIA attributes where necessary

11. Responsive Design: Components are built to be responsive by default. This is achieved through:

    • Use of Tailwind's responsive utility classes
    • Flexible layouts that adapt to different screen sizes
    • Mobile-first approach in component design

Example of responsive design in a component:

<div className="flex flex-col md:flex-row">
  <Button className="w-full md:w-auto mb-2 md:mb-0 md:mr-2">Primary Action</Button>
  <Button appearance="secondary" className="w-full md:w-auto">Secondary Action</Button>
</div>

When creating new components or modifying existing ones, adhere to these conventions to maintain consistency across the project.

Component Structure and Conventions

The components/ directory is organized into several subdirectories:

1. base/: Contains basic UI components like alerts, avatars, buttons, inputs, etc.
2. Dashboard/: Components specific to the dashboard functionality
3. Home/: Components used on the home page
4. MochiWidget/: Components for the Mochi widget functionality
5. Pay/: Components related to payment features
6. TipNetwork/: Components for the tip network feature
7. Toast/: Toast notification components
8. Wallet/: Wallet-related components

Naming Conventions

• Use PascalCase for component file names (e.g., Button.tsx, ProfileDropdown.tsx)
• Use kebab-case for non-component files (e.g., gift-icon.tsx)
• Group related components in subdirectories (e.g., Dashboard/, Home/)

Component Creation

When creating new components:

1. Place reusable components in the appropriate subdirectory within components/
2. Use functional components with TypeScript
3. Utilize TailwindCSS for styling
4. For complex components, consider breaking them down into smaller, more manageable pieces
5. Use the @consolelabs/mochi-ui component library when possible
6. Create story files for components using Storybook (e.g., button.stories.tsx)
7. Follow the established design conventions for variants, sizes, and prop naming

Key Components

1. Home Components (components/Home/):

   • Used to build the landing page
   • Include sections like Banner, ApiIntegration, ChainAndPartner, etc.

2. Dashboard Components (components/Dashboard/):

   • Used for the main application dashboard
   • Include reusable elements like Card, Form, Input, Menu, Pagination, etc.

3. MochiWidget (components/MochiWidget/):

   • Implements the core Mochi functionality
   • Includes features like gift, paylink, payme, and tip

4. Pay Components (components/Pay/):

   • Handle payment-related functionality
   • Include elements like PaymentButton, WalletButton, QRCodeButton, etc.

Page Creation

To create a new page:

1. Add a new file in the pages/ directory (for pages router) or app/ directory (for app router)
2. Use the appropriate Next.js conventions (e.g., export default function for pages router or React Server Components for app router)
3. Implement SEO using the custom seo.tsx component in the app/layout/ directory

State Management

The project uses a combination of React hooks, context, and Zustand for state management:

1. Use React's useState and useReducer for component-level state
2. Utilize React Context for sharing state across components (see context/ directory)
3. For more complex global state, use Zustand stores (found in the store/ directory)

API Integration

The project uses SWR for data fetching and caching. When integrating with APIs:

1. Create custom hooks for data fetching in the hooks/ directory
2. Use the @consolelabs/mochi-rest package for API calls
3. Handle loading and error states appropriately

Testing and Documentation

1. Use Storybook for component development and documentation
   • Run Storybook with pnpm storybook
   • Write stories for new components in their respective .stories.tsx files
   • Utilize Storybook's Autodocs feature for automatic documentation generation
2. Implement unit tests for critical components and functions (testing framework to be determined)

Code Quality and Formatting

1. Use ESLint for code linting (configuration in .eslintrc)
   • Run linting with pnpm lint (add this script to package.json if not present)
2. Use Prettier for code formatting (configuration in .prettierrc)
   • Run formatting with pnpm format (add this script to package.json if not present)
3. Consider setting up pre-commit hooks to run linting and formatting automatically

CI/CD Pipeline

The project uses Vercel for continuous integration and deployment:

1. Preview builds are automatically created for each pull request
2. Production builds are triggered on merging into the master branch
3. Ensure all tests pass and there are no linting errors before merging

Best Practices

1. Follow the conventional commits specification for version control
2. Use TypeScript for type safety
3. Implement responsive design using TailwindCSS classes
4. Optimize performance by lazy loading components and images where appropriate
5. Write unit tests for critical components and functions
6. Use environment variables for configuration (refer to .env.example)
7. Follow accessibility guidelines, utilizing headlessui components for accessible UI elements
8. Adhere to the established design conventions when creating or modifying components

Development Workflow

1. Use pnpm as the package manager
2. Run pnpm dev:https for local development with HTTPS (required for wallet connect debugging)
3. Follow the PR process: create a PR into master when changes are ready
4. Use Vercel for deployments (preview builds on PR, production build on merging into master)

This document provides an overview of the project structure and development practices. For more detailed information, refer to specific files and the project's documentation.