Files
xpack-mcp/frontend/docs/development.md
T

8.8 KiB

Development Guide

Getting Started

Prerequisites

  • Node.js 18+
  • pnpm (recommended package manager)
  • Git

Development Setup

  1. Clone and Install

    git clone <repository-url>
    cd apps/op
    pnpm install
    
  2. Environment Configuration

    Create the environment file:

    cp .env.example .env.local
    

    Update variables as needed:

    # Backend Service API URL Prefix
    NEXT_PUBLIC_API_URL=http://127.0.0.1:8001
    
  3. Start Development Server

    pnpm dev
    

    The app will be available at http://localhost:3000

Project Structure

Core Directories

src/
├── app/                    # Next.js App Router pages
│   ├── marketplace/        # Service marketplace pages
│   ├── console/           # Admin console
│   ├── dashboard/         # User dashboard
│   ├── signin/            # User authentication
│   ├── admin-signin/      # Admin authentication
│   └── loginSuccess/      # Login success page
├── components/            # Feature-specific components
│   ├── console/           # Console management
│   ├── dashboard/         # Dashboard components
│   ├── marketplace/       # Marketplace components
│   ├── mcp-services/      # MCP service management
│   ├── revenue-management/# Revenue tracking
│   ├── system-setting/    # System configuration
│   ├── user-management/   # User administration
│   └── wallet/            # Wallet management
├── shared/               # Shared utilities
│   ├── components/       # Reusable UI components
│   ├── hooks/           # Custom React hooks
│   ├── store/           # Zustand state stores
│   ├── types/           # TypeScript definitions
│   ├── lib/             # Utility libraries
│   ├── rpc/             # RPC services
│   ├── providers/       # React providers
│   ├── contexts/        # React contexts
│   ├── config/          # Configuration files
│   ├── data/            # Static data and mocks
│   └── utils/           # Utility functions
├── services/            # Backend API integration
│   ├── marketplaceService.ts  # Marketplace API
│   ├── mcpService.ts         # MCP service API
│   ├── userService.ts        # User management API
│   ├── revenueService.ts     # Revenue tracking API
│   ├── paymentChannelService.ts # Payment API
│   ├── systemConfigService.ts   # System config API
│   ├── platformConfigService.ts # Platform config API
│   └── overviewService.ts    # Overview/stats API
├── hooks/               # App-specific hooks
│   ├── useAdminLogin.tsx     # Admin authentication
│   ├── useLogin.tsx          # User authentication
│   ├── useMCPServicesList.ts # MCP services data
│   ├── useMCPServiceDetail.ts # Service details
│   ├── useUserManagement.ts  # User management
│   ├── useRevenueManagement.ts # Revenue data
│   ├── usePaymentChannelManagement.ts # Payment channels
│   └── useSystemConfigManagement.ts   # System config
├── store/               # Zustand stores
│   └── admin.ts         # Admin state management
├── types/               # TypeScript type definitions
│   ├── admin.ts         # Admin types
│   ├── dashboard.ts     # Dashboard types
│   ├── mcp-service.ts   # MCP service types
│   ├── payment.ts       # Payment types
│   ├── revenue.ts       # Revenue types
│   ├── system.ts        # System types
│   ├── user.ts          # User types
│   └── global.d.ts      # Global type declarations
├── rpc/                 # RPC layer
│   └── admin-api.ts     # Admin API client
└── utils/               # Utility functions
    └── getEmail.ts      # Email utilities

Key Files

  • src/app/layout.tsx - Root layout with providers and platform config
  • src/app/page.tsx - Homepage with marketplace
  • src/shared/components/Navigation.tsx - Main navigation
  • src/shared/store/ - Global state management with Zustand
  • next.config.ts - Next.js configuration with NextUI optimization
  • tailwind.config.ts - Tailwind CSS configuration

Development Workflow

Code Style

  • TypeScript: Strict mode enabled
  • ESLint: Next.js recommended + custom rules
  • Prettier: Automatic formatting
  • File naming: kebab-case for files, PascalCase for components

State Management

Using Zustand for global state:

// Example store
import { create } from "zustand";

interface UserStore {
  user: User | null;
  setUser: (user: User) => void;
}

export const useUserStore = create<UserStore>((set) => ({
  user: null,
  setUser: (user) => set({ user }),
}));

API Integration

Custom fetch wrapper with SWR:

// Using SWR for data fetching
import useSWR from "swr";
import { fetchServices } from "@/shared/api/services";

function useServices() {
  const { data, error, isLoading } = useSWR("/api/services", fetchServices);
  return { services: data, error, isLoading };
}

Internationalization

Using react-i18next:

// In components
import { useTranslation } from '@/shared/lib/useTranslation'

function MyComponent() {
  const { t } = useTranslation()
  return <h1>{t('Welcome')}</h1>
}

Translation files are in public/locales/{lang}/translation.json

Available Scripts

# Development
pnpm dev              # Start dev server (port 3000)
pnpm build            # Production build
pnpm start            # Start production server

# Code Quality
pnpm lint             # Run ESLint
pnpm type-check       # TypeScript type checking

# Utilities
pnpm format           # Format code with Prettier

Adding New Features

1. Create a New Page

# Create page directory
mkdir src/app/my-feature

# Create page component
touch src/app/my-feature/page.tsx
// src/app/my-feature/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Feature | XPack',
}

export default function MyFeaturePage() {
  return (
    <div>
      <h1>My Feature</h1>
    </div>
  )
}

2. Add Components

// src/components/my-feature/MyComponent.tsx
import React from 'react'
import { useTranslation } from '@/shared/lib/useTranslation'

export function MyComponent() {
  const { t } = useTranslation()

  return (
    <div className="p-4">
      <h2>{t('My Component')}</h2>
    </div>
  )
}

3. Add Translations

// public/locales/en/translation.json
{
  "My Component": "My Component",
  "My Feature": "My Feature"
}

// public/locales/zh-CN/translation.json
{
  "My Component": "我的组件",
  "My Feature": "我的功能"
}

4. Add Types

// src/shared/types/my-feature.ts
export interface MyFeatureData {
  id: string;
  name: string;
  description: string;
}

5. Add API Services

// src/shared/api/my-feature.ts
import { apiRequest } from "./base";
import type { MyFeatureData } from "@/shared/types/my-feature";

export async function fetchMyFeatureData(): Promise<MyFeatureData[]> {
  return apiRequest("/api/my-feature");
}

Testing

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

Writing Tests

// __tests__/components/MyComponent.test.tsx
import { render, screen } from '@testing-library/react'
import { MyComponent } from '@/components/my-feature/MyComponent'

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent />)
    expect(screen.getByText('My Component')).toBeInTheDocument()
  })
})

Debugging

Development Tools

  • React DevTools: Browser extension for React debugging
  • Next.js DevTools: Built-in development features
  • TypeScript: Compile-time error checking
  • ESLint: Code quality and error detection

Common Issues

  1. Port conflicts: Change port in package.json if 3000 is occupied
  2. Environment variables: Ensure all required env vars are set
  3. TypeScript errors: Run pnpm type-check to identify issues
  4. Build failures: Check for missing dependencies or syntax errors

Performance

Optimization Tips

  • Use Next.js Image component for images
  • Implement proper loading states
  • Use React.memo for expensive components
  • Optimize bundle size with dynamic imports
  • Enable SSR for dynamic content and SEO optimization

Monitoring

  • Use Next.js built-in analytics
  • Monitor Core Web Vitals
  • Check bundle analyzer for size optimization

Deployment

See Deployment Guide for production deployment instructions.