Build & Deployment

Relevant source files

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

• vite.config.ts
• package.json
• index.html
• tsconfig.app.json
• tsconfig.json
• README.md
• src/App.tsx

The Endfield-Pomodoro project utilizes a modern web development toolchain centered around Vite for building and serving the application. The build process is configured to handle TypeScript, React (with the experimental React Compiler), and TailwindCSS. A key aspect of the deployment strategy is its functionality as a Progressive Web App (PWA), enabled by vite-plugin-pwa, which provides offline capabilities and a native-like installation experience.

The entire process is orchestrated through npm scripts, which handle development, linting, and production builds. The configuration ensures optimized output, automatic performance enhancements via the React Compiler, and a robust caching strategy for offline use.

Technology Stack & Dependencies

The project's build and deployment capabilities are defined by its core dependencies and development tools listed in package.json.

Sources: package.json

Key Dependencies

Dependency	Version	Role
react	^19.2.0	The core UI library.
vite	^7.2.4	The build tool and development server.
typescript	~5.9.3	Provides static typing for the codebase.
tailwindcss	^4.1.17	A utility-first CSS framework for styling.
@vitejs/plugin-react	^5.1.1	Vite plugin to enable React support.
babel-plugin-react-compiler	^1.0.0	Automatically optimizes React components, enabled via the Vite config.
vite-plugin-pwa	^1.2.0	Generates the service worker and manifest for PWA capabilities.
workbox-window	^7.4.0	A library to register the service worker and manage its lifecycle.

Sources: package.json:12-21, package.json:25-26, package.json:33-34

Build Process

The build process is managed by scripts defined in package.json. Vite serves as the central orchestrator, transforming the src directory into optimized static assets for production.

Sources: package.json:6-10, vite.config.ts

Build Commands

Script	Command	Description
dev	vite	Starts the Vite development server with Hot Module Replacement (HMR).
build	tsc -b && vite build	First, runs the TypeScript compiler to check for errors (tsc -b), then bundles the application for production using Vite.
lint	eslint .	Lints the codebase for potential errors and style issues.
preview	vite preview	Serves the production build locally to preview the final application.

Sources: package.json:7-10

The following diagram illustrates the production build flow:

This diagram shows how the pnpm build command initiates a type check followed by the Vite build process, which results in a dist directory ready for deployment.
Sources: package.json:8, vite.config.ts

Vite Configuration

The file vite.config.ts is the heart of the build system. It defines plugins, PWA settings, and other build-time behaviors.

Sources: vite.config.ts

Plugins

Vite's functionality is extended through a series of plugins.

This diagram shows the main plugins used by Vite in this project.
Sources: vite.config.ts:7-20

1. @vitejs/plugin-react: This plugin provides React support. It is configured to use babel-plugin-react-compiler, which automatically memoizes components and hooks, eliminating the need for manual useMemo and useCallback in most cases.

   // vite.config.ts:8-12
   react({
     babel: {
       plugins: ['babel-plugin-react-compiler'],
     },
   }),
   

   Sources: vite.config.ts:8-12, README.md:143-154

2. @tailwindcss/vite: Integrates the TailwindCSS v4 engine into the Vite build process, processing CSS files and enabling the use of utility classes.
   Sources: vite.config.ts:13

3. vite-plugin-pwa: This is the most extensive plugin, responsible for turning the application into a Progressive Web App. It generates a manifest.json file and a service worker using Workbox.
   Sources: vite.config.ts:14-154

TypeScript Configuration

The project uses two main TypeScript configuration files, referenced in tsconfig.json.

• tsconfig.app.json: Configures TypeScript for the application source code in the src directory. It targets ES2022 and uses modern bundler-aware settings like "moduleResolution": "bundler".
• tsconfig.node.json: Configures TypeScript for Node.js-specific files, such as vite.config.ts.

Sources: tsconfig.json, tsconfig.app.json, tsconfig.node.json

Progressive Web App (PWA)

The application is configured as a PWA to provide offline support and an installable experience. This is managed by vite-plugin-pwa and its underlying Workbox configuration.

Sources: vite.config.ts:14-154, index.html:10-14

Web App Manifest

The manifest provides metadata for the PWA, such as its name, icons, and theme colors.

Property	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.
display	standalone	Opens the app in its own window, without browser UI.
start_url	/	The entry point of the application.
theme_color	#fff7d0	The theme color for the app's UI.
background_color	#e5e5e5	The background color for the splash screen.
icons	[...]	A list of icons for different device resolutions.

Sources: vite.config.ts:18-42, index.html:8

Service Worker & Caching

The service worker, generated by Workbox, intercepts network requests and serves cached assets when offline. The caching strategy is defined in the runtimeCaching array.

The following diagram shows how the service worker handles different types of requests:

Caching Rules Summary

URL Pattern	Handler	Cache Name	Description
/index.html	NetworkFirst	index-html	Always tries to fetch the latest index.html from the network first to ensure the user gets the newest version. Falls back to cache if offline.
api.injahow.cn/meting/	NetworkOnly	N/A	All requests to the online music API are network-only and not cached.
Audio/Video requests	NetworkOnly	N/A	Audio and video files, including those from music streaming services, are never cached.
Google Fonts API	CacheFirst	google-fonts-stylesheets	Font stylesheets are served from the cache first for performance.
Google Fonts files	CacheFirst	google-fonts-webfonts	Font files (.woff2) are served from the cache first.
Other static assets	(Implicitly handled)	workbox-precache	All assets matching globPatterns (js, css, png, etc.) are precached during the service worker installation.

Sources: vite.config.ts:59-151

A key configuration is the navigateFallbackDenylist, which prevents the service worker from serving index.html for API or audio file requests, ensuring those requests are handled by the network.

// vite.config.ts:53-56
navigateFallbackDenylist: [
  /^\/api/,
  /\.(mp3|m4a|flac)$/i
],

Sources: vite.config.ts:53-56

Application Entry Point

The application's entry point is index.html. This file sets up the basic document structure, includes PWA-related meta tags, and loads the main React application.

Key elements in index.html:

• <meta name="viewport">: Ensures proper scaling on mobile devices.
• <meta name="theme-color">: Sets the browser toolbar color.
• Apple PWA tags: apple-mobile-web-app-capable and apple-touch-icon provide a better experience on iOS.
• <link rel="stylesheet" href="/src/index.css">: Preloads the global stylesheet to ensure the correct theme is applied on the first paint.
• <script type="module" src="/src/main.tsx">: Loads and executes the main TypeScript file that renders the React application into the <div id="root">.

Sources: index.html