Frontend Build Toolchain

Relevant source files

• ui/eslint.config.mjs
• ui/index.html
• ui/scripts/eslint/rules/no-root-relative-url.mjs
• ui/scripts/vite/plugins/preserve-files-plugin.ts
• ui/src/components/AppDocument.tsx
• ui/src/components/AppLocale.tsx
• ui/src/components/AppTheme.tsx
• ui/src/components/AppVersion.tsx
• ui/src/components/icons/createIconComponent.ts
• ui/src/domain/app.ts
• ui/src/global.css
• ui/src/hooks/index.ts
• ui/src/hooks/useVersionChecker.ts
• ui/src/i18n/index.ts
• ui/src/index.css
• ui/src/main.tsx
• ui/src/pages/ConsoleLayout.tsx
• ui/src/pages/login/Login.tsx
• ui/src/pages/settings/SettingsAppearance.tsx
• ui/src/pages/workflows/WorkflowNew.tsx
• ui/src/repository/_pocketbase.ts
• ui/src/utils/cron.ts
• ui/src/utils/url.ts
• ui/tsconfig.app.json
• ui/tsconfig.json
• ui/tsconfig.node.json
• ui/vite.config.ts

This page documents the frontend build infrastructure for Certimate, based on Vite and React. It covers how the application is compiled, how it integrates with the Go backend during development, and the specific optimizations used for production delivery.

Vite Configuration Overview

Certimate uses Vite as its primary build tool and development server. The configuration is defined in ui/vite.config.ts and handles several critical tasks: version synchronization with the backend, path aliasing, and asset optimization.

Version Injection

To ensure the UI displays the correct version number and can perform update checks, the build toolchain extracts the AppVersion constant directly from the Go source code.

1. The config reads internal/app/app.go using fs.readFileSync ui/vite.config.ts14
2. It uses a regular expression to match the AppVersion string ui/vite.config.ts15
3. If the command is serve (development mode), it appends a -dev suffix ui/vite.config.ts18-20
4. The version is injected into the frontend code via the Vite define feature as __APP_VERSION__ ui/vite.config.ts32
5. This injected value is consumed in ui/src/domain/app.ts to export APP_VERSION ui/src/domain/app.ts1

Development Proxy

During development, the Vite server proxies API requests to the local PocketBase/Go backend to avoid Cross-Origin Resource Sharing (CORS) issues.

• Target: http://127.0.0.1:8090 ui/vite.config.ts67
• Prefix: /api ui/vite.config.ts66

Path Aliasing

The @ symbol is configured as an alias for the ./src directory to simplify imports across the project. This is reflected in the Vite config ui/vite.config.ts61-63

Sources:

• ui/vite.config.ts11-33
• ui/vite.config.ts60-70
• ui/src/domain/app.ts1-8

---

Build Pipeline & Plugins

The build process utilizes several plugins to manage styles, compatibility, and file persistence.

Custom preserveFilesPlugin

This plugin ensures that specific files in the dist directory are not deleted during the Vite build "emptyOutDir" phase.

• Usage: Currently used to preserve dist/.gitkeep ui/vite.config.ts56-58
• Implementation: Defined in ui/scripts/vite/plugins/preserve-files-plugin.ts ui/vite.config.ts9

Tailwind CSS Integration

Certimate uses Tailwind CSS v4. The @tailwindcss/vite plugin is integrated into the Vite pipeline ui/vite.config.ts3 ui/vite.config.ts55 The CSS setup in ui/src/global.css handles the layer conflicts between Tailwind and Ant Design ui/src/global.css1-7 It defines custom variants and theme variables that bridge Tailwind's utility classes with Ant Design's design tokens ui/src/global.css13-43

Browser Compatibility (legacyPlugin)

Certimate targets modern browsers while providing polyfills for older environments.

• Modern Targets: Chrome >= 111, Firefox >= 113, Safari >= 15.4 ui/vite.config.ts49
• Legacy Targets: "defaults, not IE 11" ui/vite.config.ts48
• Configuration: It renders modern chunks and includes polyfills but skips legacy chunk rendering (renderLegacyChunks: false) to keep the bundle size optimized ui/vite.config.ts50-53

Asset Chunking (Rollup)

To optimize loading, the i18n locale files are split into a separate manual chunk named locales.

• Implementation: The manualChunks function in build.rolldownOptions.output checks if the module ID includes /src/i18n/ ui/vite.config.ts37-41

Sources:

• ui/vite.config.ts45-59
• ui/src/global.css1-43

---

Data Flow: Build-Time Version Injection

The following diagram illustrates how the version string travels from the Go backend source code into the compiled TypeScript environment.

Version Injection Flow

Sources:

• ui/vite.config.ts11-33
• ui/src/domain/app.ts1

---

Version Checking & Updates

Certimate includes a frontend service to check for new releases on GitHub or Gitee.

useVersionChecker Hook

This hook manages the update detection logic ui/src/hooks/useVersionChecker.ts41

1. Semver Extraction: Parses version strings to remove "v" prefixes and development suffixes via extractSemver ui/src/hooks/useVersionChecker.ts11-16
2. Comparison: Implements compareVersions to determine if a fetched release is newer than the current APP_VERSION ui/src/hooks/useVersionChecker.ts18-33
3. API Fallback: Attempts to fetch from GitHub API; if it fails, it falls back to Gitee ui/src/hooks/useVersionChecker.ts61-79
4. Persistence: Stores the latest known version in localStorage under certimate-ui-newver ui/src/hooks/useVersionChecker.ts35

UI Integration

The version info is displayed in the UI via the AppVersion component. The ConsoleLayout uses isBrowserHappy() to check runtime compatibility ui/src/pages/ConsoleLayout.tsx27 If the browser is outdated, a warning alert is displayed ui/src/pages/ConsoleLayout.tsx59-61

Sources:

• ui/src/hooks/useVersionChecker.ts1-122
• ui/src/pages/ConsoleLayout.tsx59-61
• ui/src/utils/browser.ts1-10

---

Theming and Appearance Tooling

The build toolchain supports a highly configurable appearance system that synchronizes Tailwind CSS and Ant Design tokens.

Theme Token Synchronization

The application calculates theme tokens based on the current themeMode (light/dark) ui/src/pages/settings/SettingsAppearance.tsx42-50 These tokens are matched with CSS variables defined in ui/src/global.css using the @theme and @layer base directives ui/src/global.css13-43

Settings UI

Users can modify appearance settings through the SettingsAppearance page ui/src/pages/settings/SettingsAppearance.tsx11-34

• Theme Switching: Managed by SettingsAppearanceTheme, allowing users to toggle between light and dark modes ui/src/pages/settings/SettingsAppearance.tsx37-74
• Language Selection: Managed by SettingsAppearanceLanguage, which triggers i18n.changeLanguage and updates the UI locale ui/src/pages/settings/SettingsAppearance.tsx77-106

Entity Mapping: Appearance and Theming

Sources:

• ui/src/global.css1-43
• ui/src/pages/settings/SettingsAppearance.tsx1-172
• ui/src/pages/login/Login.tsx24-41
• ui/src/pages/ConsoleLayout.tsx58-61