Developer Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• vite.config.ts
• tsconfig.app.json
• index.html
• src/App.tsx
• src/utils/i18n.ts
• src/types.ts
• src/components/Pomodoro.tsx
• src/components/TaskManager.tsx

This document provides a comprehensive guide for setting up the development environment for the Endfield Pomodoro project. It covers prerequisites, installation, project structure, build tooling, and code organization principles to help developers get started quickly. The project is a web-based Pomodoro application with a cyber UI style, built with React 19, Vite, and TypeScript.

Sources: README.md

1. Prerequisites and Installation

Before starting, ensure your development environment meets the following requirements. The project uses pnpm as its recommended package manager.

Environment Requirements:

• Node.js: version 18 or higher
• Package Manager: pnpm (recommended), npm, or yarn

Sources: README.md:80-82

Installation Steps

The following diagram and steps outline the process for cloning the repository and installing dependencies.

This flowchart shows the standard developer workflow from cloning the repository to running various build and development scripts.

1. Clone the repository:

   git clone https://github.com/ChuwuYo/Endfield-Pomodoro.git
   cd endfield-pomodoro
   

2. Install dependencies:

   pnpm install
   

Sources: README.md:85-93

Core Scripts

The project's package.json defines several scripts for common development tasks.

Script	Command	Description
dev	vite	Starts the Vite development server with hot module replacement.
build	tsc -b && vite build	Type-checks the project and then creates a production-ready build.
lint	eslint .	Runs ESLint to analyze the codebase for potential errors and style issues.
preview	vite preview	Serves the production build locally for previewing.

Sources: package.json:6-11

2. Project Architecture

The project follows a standard structure for a React + Vite application, with clear separation of concerns.

Project Structure Overview

The directory structure is organized to separate source code, public assets, and documentation.

This diagram illustrates the high-level folder and file structure of the project.

Sources: README.md:105-146

Code Organization Principles

The codebase adheres to the following principles to maintain clarity and modularity:

• Component Layering: UI components are separated into src/components/ui/ (base UI), src/components/themes/ (theme-specific effects), and business logic components (e.g., Pomodoro.tsx).
• Centralized Configuration: All configuration files are located in src/config/.
• Constants: Global constants are defined in src/constants.ts.
• Types: All core TypeScript type definitions are centralized in src/types.ts.
• Utilities: Pure functions and helpers are placed in the src/utils/ directory.
• Custom Hooks: Reusable logic is extracted into custom hooks within src/hooks/.

Sources: README.md:214-221

3. Build and Tooling

The project leverages Vite for its build process, along with several key plugins and configurations for TypeScript, React, and PWA support.

Vite Configuration

The build process is managed by Vite and configured in vite.config.ts. It uses plugins to add support for React, TailwindCSS, and Progressive Web App (PWA) features.

This diagram shows how Vite processes source files through its plugin pipeline.

Key plugins include:

• @vitejs/plugin-react: Provides React support. It is configured to use babel-plugin-react-compiler for automatic performance optimizations.
• @tailwindcss/vite: Integrates the TailwindCSS v4 engine.
• vite-plugin-pwa: Generates a service worker and manifest file to make the application a PWA.

Sources: vite.config.ts:1-12, README.md:223-234

TypeScript Configuration

The project uses TypeScript to ensure code quality and maintainability. The configuration is split between tsconfig.app.json for the application source code and tsconfig.node.json for Node.js scripts like vite.config.ts.

Key compilerOptions for the app (tsconfig.app.json):

• target: ES2022 - Compiles to modern JavaScript syntax.
• module: ESNext - Uses modern ES module syntax.
• moduleResolution: bundler - The modern resolution strategy for bundlers like Vite.
• jsx: react-jsx - Uses the new JSX transform.
• strict: true - Enables all strict type-checking options.

Sources: tsconfig.app.json:2-25, tsconfig.node.json

Progressive Web App (PWA)

PWA capabilities are configured via vite-plugin-pwa. This includes auto-updating the service worker, defining the web app manifest, and setting up complex caching strategies with Workbox.

Runtime Caching Strategy:
The service worker uses a NetworkOnly strategy for API calls and audio streams to ensure fresh data, while caching static assets like Google Fonts with a CacheFirst strategy.

URL Pattern	Handler	Cache Name	Description
/index.html	NetworkFirst	index-html	Ensures the user always gets the latest version of the main HTML file.
https://api.injahow.cn/meting/.*	NetworkOnly	-	Online music API calls are never cached.
Audio/Video requests	NetworkOnly	-	Audio streams from platforms like Netease are not cached.
https://fonts.googleapis.com/.*	CacheFirst	google-fonts-stylesheets	Caches Google Fonts CSS files for up to a year.
https://fonts.gstatic.com/.*	CacheFirst	google-fonts-webfonts	Caches Google Fonts font files (.woff2) for up to a year.

Sources: vite.config.ts:13-118

4. Customization

The application is designed to be easily customizable, particularly regarding themes and internationalization.

Adding a New Theme

To add a new visual theme, a developer needs to perform two main steps:

1. Define Theme Colors: Add a new theme preset key to the ThemePreset enum in src/types.ts. Then, define the corresponding CSS variable values in the THEMES object in src/config/themes.ts.

   // src/types.ts
   export const ThemePreset = {
     // ... existing themes
     YOUR_THEME: 'YOUR_THEME'
   } as const;
   
   // src/config/themes.ts
   [ThemePreset.YOUR_THEME]: {
     '--color-base': '#RRGGBB',
     '--color-primary': '#RRGGBB',
     // ... other color variables
   }
   

2. Add to UI: Add the new theme as an option in the settings UI located in src/App.tsx.

If the theme requires special background or foreground effects, corresponding components can be added to src/components/themes/BackgroundEffects.tsx and src/components/themes/ForegroundEffects.tsx.

Sources: README.md:181-197, src/App.tsx:437-450, src/types.ts:19-29

Adding a New Language

Internationalization (i18n) is managed in src/utils/i18n.ts. To add support for a new language:

1. Add a new language key to the Language enum in src/types.ts.
2. Add a new translation object in src/utils/i18n.ts with the new language key.

   // src/utils/i18n.ts
   export const translations = {
     // ... existing languages
     [Language.NEW_LANG]: {
       APP_TITLE: 'Translated Title',
       // ... other translated strings
     }
   }
   

3. Add the new language to the selection dropdown in src/App.tsx.

The useTranslation hook will automatically provide the correct strings based on the user's selection, and the UI will update instantly without a page refresh.

Sources: README.md:199-205, src/utils/i18n.ts:3-200, src/App.tsx:426-432