Quick Start

Source Files

This page is generated from the following source files:

• README.md
• package.json
• .env.example
• next.config.js
• src/app/test-speech/page.tsx
• src/components/MediaInput.tsx
• src/hooks/useVoiceRecorder.ts
• src/components/VoiceRecognitionPanel.tsx
• postcss.config.js
• tailwind.config.js

This project is a gamified writing learning platform built with Next.js 14, designed to help sixth-grade students master writing skills through interactive exercises. The application features a serverless architecture with localStorage-based data persistence and optional AI-powered essay grading through user-provided API keys (README.md:1-113).

Environment Preparation and Dependency Installation

System Requirements

The project requires Node.js and supports multiple package managers. Based on the configuration, the following environment is recommended:

Technology Stack Overview

The project utilizes a modern frontend stack optimized for Vercel deployment:

• Framework: Next.js 14 with App Router (README.md:15)
• Language: TypeScript 5.4+ (package.json:40)
• Styling: Tailwind CSS 3.4 with custom animations (package.json:38)
• State Management: Zustand with localStorage persistence (README.md:18)
• UI Components: Radix UI primitives for accessibility (package.json:14-22)

Installation Steps

Install project dependencies using one of the following commands:

bash
1# Using npm
2npm install
3
4# Using yarn
5yarn install
6
7# Using pnpm
8pnpm install

These commands are documented in the project README at README.md:25-31. The installation process will resolve all dependencies defined in package.json:12-42, including React 18.2, Next.js 14.2, and various UI component libraries.

Environment Variable Configuration

The project supports optional environment variables for default AI API configuration. Create a .env.local file based on the provided template:

bash
1# Copy the example file
2cp .env.example .env.local

The environment variables available for configuration are defined in .env.example:1-11:

Note: Environment variables are optional. Users can configure AI settings directly in the application's settings page as stated in .env.example:4.

Local Development Server Startup

Recommended Quick Start Path

The fastest way to run the project locally is using the development server:

bash
1# Start development server
2npm run dev

This command executes next dev as defined in package.json:7. Alternative package manager commands are also available:

bash
1# Using yarn
2yarn dev
3
4# Using pnpm
5pnpm dev

Accessing the Application

After starting the development server, access the application at:

http://localhost:3000

This URL is documented in README.md:43. The development server runs on port 3000 by default (standard Next.js behavior - explicit port configuration not found in source files, needs confirmation).

Project Structure Overview

Understanding the directory structure helps navigate the codebase effectively (README.md:75-85):

src/
├── app/           # Next.js App Router pages
├── components/    # Reusable UI components
├── data/          # Static data configurations
├── lib/           # Utility functions and state management
├── types/         # TypeScript type definitions
└── styles/        # Global stylesheets

Next.js Configuration

The project uses specific Next.js optimizations configured in next.config.js:1-20:

• React Strict Mode: Enabled for development warnings (next.config.js:4)
• SWC Minification: Enabled for faster builds (next.config.js:5)
• Image Optimization: Disabled (unoptimized: true) for Vercel compatibility (next.config.js:6-8)
• Webpack Configuration: Custom rule for .mjs files to resolve deployment issues (next.config.js:10-16)

Production Build and Deployment

Building for Production

Create an optimized production build using:

bash
1# Build production version
2npm run build
3
4# Alternative package managers
5yarn build
6pnpm build

The build command executes next build as specified in package.json:8. This generates an optimized production bundle in the .next directory.

Starting Production Server

After building, start the production server:

bash
1# Start production server
2npm start
3
4# Alternative package managers
5yarn start
6pnpm start

This command runs next start as defined in package.json:9. The complete build and start workflow is documented in README.md:45-63.

Vercel Deployment

The project is pre-configured for seamless Vercel deployment. Follow these steps from README.md:65-74:

1. Push code to a GitHub repository
2. Log in to Vercel and import the project
3. Select the GitHub repository
4. Vercel automatically detects Next.js configuration
5. Click "Deploy" to initiate deployment

The deployment process leverages the standard Next.js preset, with the configuration in next.config.js:3 explicitly noting Vercel deployment support.

Deployment Flow

正在加载图表渲染器...

Core Feature Verification

Feature Overview

The platform provides several key features documented in README.md:5-11:

Speech Recognition Testing

A dedicated test page is available for verifying speech recognition functionality. Access the test page at /test-speech route to validate browser compatibility with the Web Speech API.

The test page implementation in src/app/test-speech/page.tsx:1-101 provides:

• Real-time speech-to-text conversion
• Chinese language recognition (zh-CN) at line 22
• Continuous recognition mode at line 23
• Interim results display at line 24

Browser Compatibility Check

Before using speech recognition features, verify browser compatibility. The application displays an alert if the browser doesn't support the Web Speech API:

您的浏览器不支持语音识别，请使用 Chrome、Edge 或 Safari 浏览器

This check is implemented in src/app/test-speech/page.tsx:14-16 and src/components/MediaInput.tsx:206-210.

Supported browsers per README.md:104-109:

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

AI Configuration Verification

To verify AI grading functionality:

1. Navigate to the Settings page in the application
2. Configure the API key for the AI service
3. Optionally set a custom API endpoint (supports DeepSeek, Moonshot, or other OpenAI-compatible services)
4. Select the desired AI model

The BYOK (Bring Your Own Key) approach is documented in README.md:9 and README.md:90, ensuring no backend is required for AI features.

Common Issues and Troubleshooting

Issue 1: Speech Recognition Not Working

Symptoms: The speech recognition button doesn't respond or shows an error.

Possible Causes and Solutions:

1. Browser Incompatibility: Ensure using Chrome, Edge, or Safari. The code checks for SpeechRecognition or webkitSpeechRecognition API availability at src/app/test-speech/page.tsx:12.

2. Microphone Permission Denied: Grant microphone access when prompted by the browser. The getUserMedia call in src/hooks/useVoiceRecorder.ts:98 requires explicit permission.

3. HTTPS Requirement: Speech recognition requires secure context (HTTPS or localhost). Production deployments must use HTTPS.

Issue 2: Build Fails on Vercel

Symptoms: JavaScript syntax errors during Vercel deployment.

Solution: The project includes a webpack configuration to handle .mjs files:

javascript
1// From next.config.js:10-16
2webpack: (config) => {
3  config.module.rules.push({
4    test: /\.mjs$/,
5    include: /node_modules/,
6    type: 'javascript/auto',
7  });
8  return config;
9}

This configuration resolves module resolution issues with certain npm packages. If issues persist, check the build logs for specific error messages.

Issue 3: AI Grading Not Functioning

Symptoms: AI grading feature returns errors or doesn't respond.

Possible Causes and Solutions:

1. Missing API Key: Configure the API key in Settings page or via NEXT_PUBLIC_DEFAULT_API_KEY environment variable per .env.example:5.

2. Invalid API Endpoint: Verify the base URL is correct and accessible. Custom endpoints must be OpenAI-compatible as noted in README.md:91.

3. CORS Issues: If using a custom API endpoint, ensure it supports CORS requests from the application domain.

Issue 4: LocalStorage Data Not Persisting

Symptoms: Learning progress or essays are lost after browser refresh.

Possible Causes:

• Browser privacy settings blocking localStorage
• Private/Incognito mode usage
• Browser storage quota exceeded

Solution: The application uses Zustand with localStorage for state persistence (README.md:18). Check browser settings to ensure localStorage is enabled and not cleared on exit.

Issue 5: Development Server Port Conflicts

Symptoms: EADDRINUSE error when starting development server.

Solution: Port 3000 is already in use. Either:

• Terminate the process using port 3000
• Specify a different port (common practice: npm run dev -- -p 3001 - not documented in source, needs confirmation)

Next Steps

After successfully setting up the development environment, explore the following areas:

Customizing Writing Tools

Modify src/data/tools.ts to adjust writing tool content, add practice topics, or customize examples as mentioned in README.md:100-102.

Understanding Component Architecture

Review the component structure for extending functionality:

• MediaInput Component: Handles image upload and voice recording (src/components/MediaInput.tsx:130-349)
• VoiceRecorder Hook: Manages audio recording with segmentation (src/hooks/useVoiceRecorder.ts:1-220)

Advanced Configuration

For production deployments requiring custom AI endpoints, refer to the environment variable configuration in .env.example:1-11 and the serverless architecture design principles in README.md:87-92.