Skip to content

CLAUDE.md

Latest commit

 

History

History
386 lines (275 loc) · 12.9 KB

CLAUDE.md

File metadata and controls

386 lines (275 loc) · 12.9 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Open Source Bazaar (开源市集) is an open-source project showcase platform built with Next.js 15, TypeScript, React Bootstrap, and MobX. The platform serves as a comprehensive hub for open-source collaboration, featuring license filtering tools, Wiki knowledge base integration, volunteer showcases, and GitHub repository management.

Key Features

  • License Filter Tool: Interactive multi-step license selection process with comprehensive i18n support
  • Wiki Knowledge Base: Integration with GitHub ContentModel to access policy documents
  • Volunteer Showcase: GitHub organization contributor displays with OSS Insight widgets
  • Project Repository: GitHub repository listings and management
  • Multi-language Support: Full i18n with Chinese (Simplified/Traditional) and English
  • Lark Integration: Enterprise collaboration platform integration
  • PWA Support: Progressive Web App capabilities

Repository Structure

Important Directories

  • pages/ - Next.js pages and API routes

    • index.tsx - Homepage with animated welcome content
    • license-filter.tsx - Interactive license selection tool
    • policy/ - Wiki/policy document pages
    • volunteer.tsx - Contributor showcase
    • project.tsx - GitHub repository listings
    • api/ - API routes for external integrations

  • components/ - Reusable React components with Bootstrap styling

    • Layout/ - Page layout components (PageHead, Navigation, Footer)
    • Git/ - GitHub-related components
    • Navigator/ - Navigation components
    • PageContent/ - Content display components
    • License/ - License filter components

  • models/ - MobX stores and data models

    • Base.ts - Core configuration and client setup
    • Repository.ts - GitHub repository data models
    • Translation.ts - i18n translation models
    • Wiki.ts - Wiki content models
    • System.ts - System configuration models

  • translation/ - i18n language files

    • zh-CN.ts - Simplified Chinese
    • zh-TW.ts - Traditional Chinese
    • en-US.ts - English

  • styles/ - CSS and styling files

  • public/ - Static assets and PWA manifest

  • types/ - TypeScript type definitions

Configuration Files

  • package.json - Dependencies and scripts
  • next.config.ts - Next.js configuration with MDX, PWA, and proxy rewrites
  • tsconfig.json - TypeScript configuration
  • eslint.config.ts - ESLint configuration with spell checking
  • babel.config.js - Babel configuration for decorators
  • .github/copilot-instructions.md - Detailed development guidelines

Technology Stack

Core Technologies

  • Next.js 15 - React framework with App Router
  • TypeScript 5.9 - Type-safe JavaScript
  • React 19.1 - UI library with hooks
  • React Bootstrap 2.10 - UI component library
  • MobX 6.13 - State management
  • PNPM - Package manager

Key Dependencies

  • MobX Ecosystem:

    • mobx-github - GitHub API integration
    • mobx-i18n - Internationalization
    • mobx-restful - RESTful API client
    • mobx-restful-table - Data table components
    • mobx-lark - Lark integration
    • mobx-react - React bindings

  • Content Processing:

    • @mdx-js/react - MDX support
    • marked - Markdown processing
    • yaml - YAML front-matter processing

  • Development Tools:

    • eslint - Code linting
    • prettier - Code formatting
    • husky - Git hooks
    • lint-staged - Pre-commit linting

  • Utilities:

    • web-utility - Web utility functions
    • license-filter - License filtering logic
    • koajax - HTTP client
    • idea-react - React utilities

Development Environment

Critical Requirements

⚠️ MANDATORY NODE.JS VERSION: This project requires Node.js >=20

  • Check Node.js version: node --version
  • Development and linting commands work on Node.js 20+
  • Use PNPM as package manager, not NPM or Yarn

Initial Setup

  1. Install global pnpm: npm install -g pnpm
  2. Install dependencies: pnpm install -- takes 1-3 minutes. NEVER CANCEL
  3. Verify setup: pnpm --version (should be 10.x+)

Important: If you see "node_modules missing" error, you MUST run pnpm install first before any other commands.

Development Workflow

# Development
pnpm dev             # Start development server (5-15s) on http://localhost:3000
pnpm build           # Production build (30s-2min)
pnpm start           # Start production server

# Code Quality
pnpm lint            # Run ESLint with auto-fix (15s)
pnpm test            # Run tests (lint-staged + lint, 15s)

# Git Hooks
pnpm prepare         # Install husky hooks

Development Standards

Architecture and Code Organization

Component Standards

  • ALWAYS use React Bootstrap components instead of custom HTML elements
  • Use utilities from established libraries: 'web-utility'
  • Import './Base' in model files for proper configuration
  • Use semantic HTML structure: <article>, <header>, <section>

Import Patterns

// ✅ Correct - use React Bootstrap components
import { Button, Badge, Breadcrumb, Card, Container } from 'react-bootstrap';

// ✅ Correct - import from established sources
import { ContentModel } from 'mobx-github';
import { githubClient } from 'mobx-github';
import { treeFrom } from 'web-utility';
import './Base';  // For GitHub client setup

// ❌ Wrong - custom HTML elements
<a href={url} className="btn btn-outline-primary">Edit</a>
<span className="badge bg-secondary">{label}</span>

Error Handling

  • Natural error throwing for static generation - let errors bubble up to catch build issues
  • Ensure build passes before pushing - resolve issues at compile time

Translation and Internationalization

Critical Requirements

  • ALL user-facing text MUST be translated using i18n system
  • Use the t() function from I18nContext for all translations
  • This includes button text, labels, error messages, placeholder text, and dynamic content

Translation Patterns

// ✅ Correct - use translation function
<Button variant="outline-primary" size="sm">
  {t('edit_on_github')}
</Button>

// ❌ Wrong - hardcoded text
<Button variant="outline-primary" size="sm">
  Edit on GitHub
</Button>

Translation Key Management

  • Use generic terms unless specifically scoped: t('knowledge_base') not t('policy_documents')
  • Add translation keys to ALL language files: zh-CN.ts, en-US.ts, zh-TW.ts
  • Remove unused translation keys when replacing with generic ones

Data Modeling and GitHub Integration

Content Model Patterns

  • Use ContentModel with configured client from mobx-github
  • Import configuration via './Base' to ensure proper GitHub client setup
  • Handle Base64 content decoding when processing GitHub API responses

GitHub API Usage

// ✅ Correct - use configured client
import { githubClient } from './models/Base';

// ❌ Wrong - create separate instances
const client = new GitHubClient();

Authentication and Rate Limiting

  • GitHub API authentication is configured in models/Base.ts
  • Use the configured client to avoid rate limiting and authentication issues
  • Don't create separate GitHub API instances

Code Quality Standards

Modern ECMAScript Features

  • Use optional chaining and modern JavaScript features
  • Let TypeScript infer types when possible to avoid verbose annotations
  • Use modern ECMAScript patterns for cleaner, more maintainable code

Import and Type Management

  • Import from established sources: ContentModel from mobx-github, utilities from web-utility
  • Import configuration files where needed: './Base' for GitHub client setup
  • Use minimal exports and avoid unnecessary custom implementations

Build and Development Process

Pre-commit Standards

  1. Run linting: pnpm lint to auto-fix formatting
  2. Check build: Ensure pnpm build passes
  3. Validate translations: Verify all text is properly translated
  4. Remove unused code: Clean up unused imports and translation keys

Testing Requirements

After making ANY changes, ALWAYS validate by running through these scenarios:

  1. Start development server: pnpm dev and verify it starts without errors
  2. Navigate to homepage: Visit http://localhost:3000 and verify page loads
  3. Test core pages:
  4. Test API endpoints: Verify GitHub API integrations work
  5. Check responsive design: Test mobile/desktop layouts
  6. Verify i18n functionality: Check language switching works

Project-Specific Patterns

Wiki System Architecture

  • Uses GitHub ContentModel to access policy documents from fpsig/open-source-policy repository
  • Renders markdown content with front-matter metadata
  • Supports hierarchical document structure with breadcrumb navigation
  • Uses treeFrom utility from web-utility for hierarchical data structures

License Filter Integration

  • Interactive multi-step license selection process
  • Uses license-filter package for license recommendation logic
  • Supports multiple languages with comprehensive i18n coverage
  • Complex state management with MobX stores

Volunteer Management

  • Displays GitHub organization contributors
  • Integrates with OSS Insight widgets for contributor analytics
  • Uses GitHub API for real-time contributor data
  • Features contributor cards with activity metrics

Proxy Configuration

The project includes proxy rewrites for external services:

  • GitHub API and raw content
  • Alibaba Geo Data services
  • Lark API integration

Common Issues and Solutions

Build and Development Issues

  • "Unsupported engine" warnings: Expected on Node.js <22, development still works
  • Build hangs: Never cancel builds - they may take several minutes, set appropriate timeouts
  • Missing dependencies: Always run pnpm install first

Component and Styling Issues

  • Custom HTML not working: Replace with React Bootstrap components
  • Translation not showing: Ensure all text uses t() function and keys exist in all language files
  • GitHub API errors: Verify you're using configured githubClient from models/Base.ts

Data and Content Issues

  • Base64 content errors: Use atob(item.content) to decode GitHub API responses
  • Missing content: Check ContentModel configuration and repository access
  • Tree structure problems: Use treeFrom() utility from web-utility

Development Environment Setup

  • Clear browser cache if components don't render properly
  • Restart development server after major configuration changes
  • Verify all translation files are updated when adding new keys

Deployment and CI/CD

Vercel Deployment

  • Project is configured for Vercel deployment
  • Uses GitHub Actions for CI/CD pipeline
  • PWA support enabled for offline functionality

Environment Variables

  • NODE_ENV - Environment detection
  • CI - Continuous integration flag
  • GithubToken - GitHub API authentication
  • API_Host - Backend API host
  • LARK_API_HOST - Lark API host

Contributing Guidelines

Code Review Process

  • Follow exact code suggestions from reviews when provided
  • Use minimal approach - only include explicitly requested functionality
  • Don't add extra features not specified in requirements
  • Address reviewer feedback completely before requesting re-review

Pull Request Template

Checklist（清单）:

- [ ] Labels
- [ ] Assignees
- [ ] Reviewers

Closes #XXXXX

Quality Gates

  • All tests pass
  • Code follows project conventions
  • No linting errors
  • Build succeeds
  • Translations are complete
  • Responsive design verified
  • API integrations working

Resources and Documentation

Internal Resources

  • .github/copilot-instructions.md - Detailed development guidelines
  • README.md - Project overview and quick start
  • package.json - Complete dependency list
  • Translation files - All supported languages and keys

External Dependencies

Key Repository Links

Contact and Support

For project-specific questions, refer to the existing documentation and GitHub issues. For development guidance, follow the patterns and conventions established in the codebase and the detailed copilot instructions.