This page is generated from the following source files:
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).
The project requires Node.js and supports multiple package managers. Based on the configuration, the following environment is recommended:
| Requirement | Specification | Evidence |
|---|---|---|
| Node.js | Version compatible with Next.js 14.2 | package.json:32 |
| Package Manager | npm, yarn, or pnpm | README.md:25-31 |
| Browser | Chrome 60+, Firefox 55+, Safari 12+, Edge 79+ | README.md:104-109 |
The project utilizes a modern frontend stack optimized for Vercel deployment:
Install project dependencies using one of the following commands:
bash1# 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.
The project supports optional environment variables for default AI API configuration. Create a .env.local file based on the provided template:
bash1# Copy the example file 2cp .env.example .env.local
The environment variables available for configuration are defined in .env.example:1-11:
| Variable | Purpose | Default |
|---|---|---|
NEXT_PUBLIC_DEFAULT_API_KEY | AI API key for grading | Empty (user configures in settings) |
NEXT_PUBLIC_DEFAULT_BASE_URL | Custom API endpoint | Empty |
NEXT_PUBLIC_DEFAULT_MODEL | AI model selection | gpt-4 |
NEXT_PUBLIC_APP_NAME | Application display name | 六年级作文成长手册 |
NEXT_PUBLIC_APP_DESCRIPTION | Application description | 游戏化作文学习平台 |
Note: Environment variables are optional. Users can configure AI settings directly in the application's settings page as stated in .env.example:4.
The fastest way to run the project locally is using the development server:
bash1# Start development server 2npm run dev
This command executes next dev as defined in package.json:7. Alternative package manager commands are also available:
bash1# Using yarn 2yarn dev 3 4# Using pnpm 5pnpm dev
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).
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
The project uses specific Next.js optimizations configured in next.config.js:1-20:
unoptimized: true) for Vercel compatibility (next.config.js:6-8).mjs files to resolve deployment issues (next.config.js:10-16)Create an optimized production build using:
bash1# 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.
After building, start the production server:
bash1# 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.
The project is pre-configured for seamless Vercel deployment. Follow these steps from README.md:65-74:
The deployment process leverages the standard Next.js preset, with the configuration in next.config.js:3 explicitly noting Vercel deployment support.
正在加载图表渲染器...
The platform provides several key features documented in README.md:5-11:
| Feature | Description |
|---|---|
| Gamified Learning | 7 progressive writing tool levels |
| Real-time Writing | Built-in essay editor with auto-save |
| AI Grading | BYOK (Bring Your Own Key) API configuration |
| Progress Tracking | Local storage of learning progress |
| Responsive Design | Multi-device screen adaptation |
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:
zh-CN) at line 22Before 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:
To verify AI grading functionality:
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.
Symptoms: The speech recognition button doesn't respond or shows an error.
Possible Causes and Solutions:
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.
Microphone Permission Denied: Grant microphone access when prompted by the browser. The getUserMedia call in src/hooks/useVoiceRecorder.ts:98 requires explicit permission.
HTTPS Requirement: Speech recognition requires secure context (HTTPS or localhost). Production deployments must use HTTPS.
Symptoms: JavaScript syntax errors during Vercel deployment.
Solution: The project includes a webpack configuration to handle .mjs files:
javascript1// 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.
Symptoms: AI grading feature returns errors or doesn't respond.
Possible Causes and Solutions:
Missing API Key: Configure the API key in Settings page or via NEXT_PUBLIC_DEFAULT_API_KEY environment variable per .env.example:5.
Invalid API Endpoint: Verify the base URL is correct and accessible. Custom endpoints must be OpenAI-compatible as noted in README.md:91.
CORS Issues: If using a custom API endpoint, ensure it supports CORS requests from the application domain.
Symptoms: Learning progress or essays are lost after browser refresh.
Possible Causes:
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.
Symptoms: EADDRINUSE error when starting development server.
Solution: Port 3000 is already in use. Either:
npm run dev -- -p 3001 - not documented in source, needs confirmation)After successfully setting up the development environment, explore the following areas:
Modify src/data/tools.ts to adjust writing tool content, add practice topics, or customize examples as mentioned in README.md:100-102.
Review the component structure for extending functionality:
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.