Application Configuration
Relevant source files
The following files were used as context for generating this wiki page:Introduction
Application Configuration in the Endfield-Pomodoro project is a centralized system for managing user-specific settings. It governs the behavior and appearance of the application, including timer cycles, interface themes, language, audio feedback, and online music sources.
Configuration is managed primarily within the main App component. Settings are loaded from the browser's localStorage on startup, providing persistence across sessions. If no saved settings are found, a set of default values is applied. Users can modify these settings through the "SYSTEM CONFIG" view in the UI.
Sources: src/App.tsx:61-76, 408-410
Configuration Management
The core of the configuration system resides in src/App.tsx. It uses React state and effects to load, manage, and persist settings.
State Initialization and Persistence
On application load, the settings state is initialized by attempting to read and parse data from localStorage. If this fails or no data is present, it falls back to a DEFAULT_SETTINGS object. Any changes made by the user to the settings state trigger a useEffect hook that serializes the state object back into localStorage.
Sources: src/App.tsx:61-76, 206-212
The following diagram illustrates the configuration loading and saving flow:
Sources: src/App.tsx:61-76, 206-212, src/constants.ts:2
Default Settings
The DEFAULT_SETTINGS object provides a baseline configuration for first-time users or when stored settings are corrupted. It also defines the structure of the Settings object.
| Key | Default Value | Description |
|---|---|---|
workDuration | 25 | Duration of a work session in minutes. |
shortBreakDuration | 5 | Duration of a short break in minutes. |
longBreakDuration | 15 | Duration of a long break in minutes. |
autoStartBreaks | true | Automatically start break timers after a work session. |
autoStartWork | true | Automatically start work timers after a break. |
soundEnabled | true | Enable/disable audio feedback for timer events. |
soundVolume | 0.5 | Volume for audio feedback (0.0 to 1.0). |
notificationsEnabled | false | Enable/disable desktop notifications. |
language | Language.CN or Language.EN | Application language, detected from the browser. |
theme | ThemePreset.INDUSTRIAL | The default visual theme. |
musicConfig | defaultMusicConfig | Default settings for the online music player. |
Sources: src/App.tsx:21-38
Configuration Categories
Settings are grouped into logical categories within the "SYSTEM CONFIG" UI.
Timer Configuration (CYCLE_PARAMETERS)
This section controls the core Pomodoro timer functionality.
| Setting | Type | UI Control | Description |
|---|---|---|---|
workDuration | number | Number Input | Sets the length of a "work" session in minutes. |
shortBreakDuration | number | Number Input | Sets the length of a "short break" session in minutes. |
longBreakDuration | number | Number Input | Sets the length of a "long break" session in minutes. |
These values are passed as props to the Pomodoro component, which uses them to calculate the timeLeft for each timer mode.
Sources: src/App.tsx:420-449, src/components/Pomodoro.tsx:142-153
Interface & Appearance (INTERFACE_CUSTOMIZATION)
This section allows users to customize the look and feel of the application.
| Setting | Type | UI Control | Description |
|---|---|---|---|
language | Language (enum) | Custom Select | Changes the display language (English/Chinese). |
theme | ThemePreset (enum) | Custom Select | Changes the application's color scheme and visual effects. |
Language System
The language setting is passed to the useTranslation hook, which returns a translation function t. This function retrieves the correct string from the translations object for the currently selected language.
Sources: src/App.tsx:470-482, src/utils/i18n.ts:241-245
Theme System
The theme system uses CSS variables for dynamic styling. When the theme setting changes, a useLayoutEffect hook updates the CSS variables on the :root element based on the selected theme's color palette defined in src/config/themes.ts.
The following diagram shows how a theme is applied:
Sources: src/App.tsx:224-230, 483-498, README.md
Automation & Feedback (AUTOMATION_FEEDBACK)
These settings control automatic behaviors and system notifications.
| Setting | Type | UI Control | Description |
|---|---|---|---|
autoStartBreaks | boolean | Checkbox | If true, breaks start automatically after a work session. |
autoStartWork | boolean | Checkbox | If true, work sessions start automatically after a break. |
soundEnabled | boolean | Checkbox | Toggles start/end sound effects for timers. |
notificationsEnabled | boolean | Checkbox | Toggles browser desktop notifications for timer completion. |
When notificationsEnabled is checked, the application requests permission from the user via the browser's Notification API. If permission is denied, an alert is shown.
Sources: src/App.tsx:518-554
Online Music Configuration (ONLINE_MUSIC_CONFIG)
This section configures the source for the online music player. Changes are staged in a temporary state (tempMusicConfig) and applied only when the user clicks "APPLY CONFIG".
| Setting | Type | UI Control | Description |
|---|---|---|---|
musicConfig.server | string | Custom Select | The music platform (e.g., 'netease', 'tencent'). |
musicConfig.type | string | Custom Select | The type of content to fetch (e.g., 'playlist'). |
musicConfig.id | string | Text Input | The ID of the playlist or content. |
Sources: src/App.tsx:81, 142-154, 557-598
PWA Configuration
The application's Progressive Web App (PWA) features are configured in vite.config.ts. This includes the web app manifest and service worker behavior.
Web App Manifest
The manifest provides metadata for the PWA, such as its name, icons, and theme color.
| Manifest Key | Value | Description |
|---|---|---|
name | Endfield Protocol - Pomodoro Terminal | The full name of the application. |
short_name | Endfield | A shorter name for the app, used on home screens. |
theme_color | #fff7d0 | The theme color for the UI, used by the OS. |
display | standalone | Instructs the browser to open the app in its own window. |
start_url | / | The entry point of the application. |
Sources: vite.config.ts:14-35
Service Worker
The service worker, configured via workbox, manages caching and offline capabilities. It uses an autoUpdate strategy to ensure users get the latest version. The configuration specifies which assets to cache and defines caching strategies for different resources, such as NetworkOnly for API calls and audio streams to ensure fresh content.
Sources: vite.config.ts:13, 37-97
Conclusion
The application's configuration is a robust and flexible system that empowers users to tailor their experience. By persisting settings in localStorage and providing a clear UI, it offers a personalized and consistent environment. The separation of concerns—with timer logic in Pomodoro.tsx, state management in App.tsx, and static configs in dedicated files—creates a maintainable and scalable architecture.