CLAUDE.md

CLAUDE.md

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

🎯 CRITICAL: Code Component Usage Priority

⭐ UniversalEditor Component (HIGHEST PRIORITY)

ALWAYS use the <UniversalEditor> component for ALL code comparisons in learning module content.

The UniversalEditor component provides:

• Interactive code editing in the browser
• Side-by-side language comparison
• Real-time code execution (where supported)
• Consistent user experience across all modules

When to Use UniversalEditor:

✅ ALWAYS USE for:

• Side-by-side language comparisons
• Interactive code examples
• Code pattern demonstrations
• Before/after code transformations
• Language feature comparisons

❌ NEVER USE (unless specifically required):

• Static code blocks without comparison
• Single-language examples without comparison context
• Non-interactive code displays

UniversalEditor Syntax:

<UniversalEditor title="Descriptive Title">
```language !! syntax-highlighter
// Your code here

// Your comparison code here

```

Example:

<UniversalEditor title="Variable Declaration Comparison">
```python !! py
# Python - Dynamic typing
name = "Alice"
age = 25

// Rust - Static typing
let name: &str = "Alice";
let age: i32 = 25;

```

IMPORTANT: UniversalEditor is the DEFAULT and PREFERRED component for all code examples in learning modules.

Exception: <PythonEditor> for Python runtimes (js2py / py2js)

For content/docs/js2py/ and content/docs/py2js/ only, use <PythonEditor compare={true}> for side‑by‑side JavaScript + Python examples that must run Python in the browser via Pyodide (same pattern as the existing js2py module rules). Do not replace these with UniversalEditor unless UniversalEditor gains equivalent Pyodide execution for those paths.

For all other language pairs, keep using UniversalEditor.

Other Code Components (Use Only When Appropriate):

<Code> Component

For simple syntax highlighting without interactivity:

import { Code } from '@/components/code'

<Code language="python">{`code here`}</Code>

Use cases:

• Documentation sections
• Configuration files
• Non-interactive code snippets

<VirtualizedEditor> Component

For single-language interactive editing:

import { VirtualizedEditor } from '@/components/virtualized-editor'

<VirtualizedEditor
  language="python"
  value={code}
  onChange={(value) => setCode(value)}
  height={300}
/>

Use cases:

• Single-language code editors
• Exercise/practice areas
• When only one language needs to be shown

Project Overview

LangShift.dev is a programming language conversion learning platform built with Next.js 15.5.9 and Fumadocs 15.6.1. It helps developers learn new programming languages through comparative learning, starting from their existing language knowledge.

Core Philosophy: Teach new languages by comparing them to a known language, showing syntax mappings, concept translations, and performance differences.

Supported Language Conversions

• JavaScript → Python (13 modules) ✅
• JavaScript → Rust (14 modules) ✅
• JavaScript → Go (14 modules) ✅
• JavaScript → Kotlin (14 modules) ✅
• JavaScript → C++ (15 modules) ✅
• JavaScript → Swift (15 modules) ✅
• JavaScript → C (15 modules) ✅
• JavaScript → Java (20 modules) ✅
• Python → JavaScript ✅
• Python → Rust (planned)

Development Commands

# Development server (runs on port 8000)
pnpm dev

# Production build
pnpm build

# Start production server
pnpm start

# Type checking
pnpm type-check

# Linting
pnpm lint

# SEO checking (builds and validates sitemap/robots.txt)
pnpm seo-check

# Bundle analysis
pnpm analyze

Important: Always use pnpm as the package manager. The project uses Turbopack for faster development builds.

Architecture Overview

Tech Stack

• Framework: Next.js 15.5.9 with App Router
• Documentation: Fumadocs 15.6.1 + MDX
• Styling: Tailwind CSS 4.0.9
• Editor: Monaco Editor 4.7.0
• Type Safety: TypeScript 5.8.2 (strict mode)
• Search: Orama 3.1.1 full-text search
• i18n: Support for English, Simplified Chinese, Traditional Chinese

Content Creation Guidelines

1. Module Structure

Each language conversion path follows this structure:

content/docs/{source}2{target}/
├── meta.json           # Module metadata (keep simple!)
├── index.mdx           # English introduction
├── index.zh-cn.mdx     # Simplified Chinese introduction
├── index.zh-tw.mdx     # Traditional Chinese introduction
├── module-00-{topic}.mdx
├── module-00-{topic}.zh-cn.mdx
├── module-00-{topic}.zh-tw.mdx
└── ... (more modules)

2. meta.json Format

KEEP IT SIMPLE - Only include title and root:

{
  "title": "Python → Rust",
  "root": true
}

Do NOT add extra fields like pages, language, modules, etc.

3. Language Versioning

File naming convention:

• Main file: module-xx-topic.mdx (English)
• Chinese simplified: module-xx-topic.zh-cn.mdx
• Chinese traditional: module-xx-topic.zh-tw.mdx

CRITICAL: The main file MUST be in English. Chinese versions use the appropriate suffix.

4. Module Content Guidelines

When creating learning content:

1. Always use UniversalEditor for code comparisons

   • This is the highest priority rule
   • Every code comparison should use UniversalEditor
   • Provide meaningful titles for each comparison

2. Start with the source language

   • Explain new concepts by comparing them to the source language
   • Show "before" (source) and "after" (target) code
   • Highlight key differences

3. Provide runnable code examples

   • Code should be syntactically correct
   • Include comments explaining key concepts
   • Show realistic, production-relevant examples

4. Include performance analysis

   • Compare performance characteristics
   • Explain memory management differences
   • Discuss optimization strategies

5. Show common pitfalls

   • Highlight mistakes developers make when transitioning
   • Provide solutions and best practices
   • Include "gotcha" warnings

6. Use progressive difficulty

   • Start with basic concepts
   • Build complexity gradually
   • Each module should build on previous knowledge

5. MDX Frontmatter

Each module file must have frontmatter:

---
title: "Module XX: Topic Name"
description: "Brief description of what this module covers"
---

6. UniversalEditor Best Practices

DO:

• Use descriptive titles that explain the comparison
• Include helpful comments in code
• Show realistic, practical examples
• Keep code snippets focused and concise
• Demonstrate idiomatic code in both languages

DON'T:

• Use overly simplistic "hello world" examples (unless it's module 0)
• Show contrived or unrealistic code
• Make code snippets too long (>50 lines preferred)
• Skip error handling or edge cases

7. Module Planning

When creating a new language conversion path:

1. Analyze the source and target languages

   • Identify key conceptual differences
   • Map syntax patterns between languages
   • Note unique features of each language

2. Plan 15-20 modules covering:

   • Module 0: Introduction and environment setup
   • Modules 1-5: Basic syntax and concepts
   • Modules 6-10: Intermediate features and OOP
   • Modules 11-15: Advanced features and ecosystem
   • Modules 16-20: Best practices and real-world projects

3. Create consistent structure

   • Each module should follow a similar pattern
   • Include learning objectives at the start
   • Provide exercises at the end
   • Add summary sections

File Naming Conventions

• Learning modules: module-{number:02d}-{topic}.mdx (e.g., module-01-basics.mdx)
• Language conversion directories: {source}2{target} (e.g., py2rust)
• Components: PascalCase (e.g., VirtualizedEditor.tsx)
• Utilities: camelCase (e.g., monaco-manager.tsx)

Header Navigation

When adding a new language conversion path, update components/header.tsx:

const SOURCE_LANGUAGES = [
  {
    id: 'python',
    name: 'Python',
    icon: '🐍',
    gradient: 'from-green-500 to-emerald-500',
    targets: [
      {
        id: 'rust',
        name: 'Rust',
        icon: '🦀',
        gradient: 'from-orange-500 to-red-500',
        path: 'py2rust',
        status: 'completed' as const,
      }
    ]
  }
]

Common Patterns

Component Structure

'use client'  // Required for interactive components

import { useState, useEffect } from 'react'
import { useMonacoManager } from '@/components/monaco-manager'

export function MyComponent() {
  const { isReady, isLoading } = useMonacoManager()
  // Component logic
}

Error Handling

• Always handle network errors for API calls
• Provide user-friendly error messages
• Log errors to console for debugging
• Implement retry logic where appropriate

Internationalization

• Use useTranslations from Fumadocs UI
• Add translation keys to /messages/*.json
• Test all three languages (en, zh-cn, zh-tw)
• Ensure language detection works correctly

Testing Before Deployment

1. Type checking: pnpm type-check must pass
2. Linting: pnpm lint must pass
3. Build: pnpm build must succeed
4. SEO: pnpm seo-check validates sitemap and robots.txt
5. Manual testing: Test UniversalEditor components for each language
6. Performance: Run pnpm analyze to check bundle size

Summary of Key Rules

1. ⭐ ALWAYS use UniversalEditor for code comparisons (Highest Priority)
2. Main module files MUST be in English
3. Keep meta.json simple (only title and root)
4. Use consistent file naming conventions
5. Provide practical, realistic code examples
6. Include progressive difficulty levels
7. Test all three language versions