gdt-tool/QWEN.md

Vutron - Vite + Vue 3 + Electron Template

Project Overview

Vutron is a preconfigured template for developing cross-platform desktop applications using modern web technologies. The project combines:

• Vite as the build tool and development server
• Vue 3 with TypeScript for the user interface
• Electron for creating desktop applications
• Vuetify as the UI component library
• Pinia for state management
• vue-i18n for internationalization
• Playwright for automated testing

The template provides a ready-to-use development environment with hot-reload, cross-platform build support, automated testing, and theme management (dark/light).

Architecture

The project follows the typical Electron architecture with three main processes:

Main Process (src/main/)

• Handles application lifecycle
• Manages windows and system integration
• Located in src/main/index.ts
• Also includes utilities, tray functionality, and IPC handlers

Preload Process (src/preload/)

• Acts as an isolated bridge between main and renderer processes
• Uses contextBridge to securely expose APIs to the renderer
• Located in src/preload/index.ts

Renderer Process (src/renderer/)

• Contains the Vue 3 application
• Uses Vuetify for UI components
• Located in src/renderer/ with:
  • Components (src/renderer/components/)
  • Screens/views (src/renderer/screens/)
  • Router (src/renderer/router/index.ts)
  • State management with Pinia (src/renderer/store/)
  • Internationalization (src/renderer/locales/)
  • Utility functions (src/renderer/utils/)

Building and Running

Prerequisites

• Node.js >= 20.0.0
• pnpm package manager (recommended)

Development

# Install dependencies
pnpm install

# Start development server with hot-reload
pnpm dev

# Development with debug info
pnpm dev:debug

# Force reinstall dependencies and start development
pnpm dev:debug:force

# run Typescript Type check
pnpm typecheck

Building

# Build for all platforms
pnpm build:all

# Build for specific platforms
pnpm build:mac    # macOS
pnpm build:win    # Windows
pnpm build:linux  # Linux

# Build without packaging (useful for quick testing)
pnpm build:dir

# Run type checking, formatting, and build
pnpm build

Testing

# Run Playwright tests
pnpm test

# Run tests on Linux with virtual display
pnpm test:linux

Linting and Formatting

# Check for linting issues
pnpm lint

# Fix linting issues automatically
pnpm lint:fix

Key Features

1. Hot Module Replacement: Develop with instant feedback via Vite's fast hot-reload
2. Type Safety: Full TypeScript support across the application
3. Internationalization: Built-in multi-language support (11 languages available)
4. Theme Management: Easy switching between dark and light themes
5. State Management: Pinia for reactive state management
6. Cross-platform Builds: Build for Windows, macOS, and Linux from a single codebase
7. Testing: Integrated Playwright testing setup
8. Logging: electron-log for both main and renderer processes
9. Security: Secure IPC communication between processes

Project Structure

├── buildAssets/              # Build configurations and icons
├── dist/                     # Build output directory
├── docs/                     # Documentation
├── node_modules/             # Dependencies
├── src/                      # Source code
│   ├── main/                 # Electron main process code
│   ├── preload/              # Preload script for context isolation
│   └── renderer/             # Vue application code
│       ├── components/       # Vue components
│       ├── locales/          # Translation files
│       ├── plugins/          # Vue plugins (i18n, Pinia, Vuetify)
│       ├── router/           # Vue Router configuration
│       ├── screens/          # Application views/pages
│       ├── store/            # Pinia stores
│       ├── utils/            # Utility functions
│       ├── App.vue           # Root component
│       ├── index.html        # HTML entry point
│       └── main.ts           # Vue application entry point
├── tests/                    # Test files
├── .vscode/                  # VS Code settings
├── .editorconfig             # Editor configuration
├── .gitignore                # Git ignore rules
├── .prettierignore           # Prettier ignore rules
├── .prettierrc               # Prettier configuration
├── eslint.config.ts          # ESLint configuration
├── package.json              # Project dependencies and scripts
├── playwright.config.ts      # Playwright test configuration
├── pnpm-lock.yaml            # Dependency lock file
├── pnpm-workspace.yaml       # pnpm workspace configuration
├── README.md                 # Project documentation
├── tsconfig.json             # TypeScript configuration
├── tsconfig.node.json        # TypeScript configuration for Node.js files
└── vite.config.mts           # Vite configuration

Development Conventions

1. Code Style:

   • Uses ESLint with TypeScript and Vue plugin
   • Formatted with Prettier
   • Follows Vue 3 Composition API with TypeScript

2. Component Structure:

   • Components use Vue 3's <script setup> syntax
   • Written in TypeScript with proper typing
   • Utilize Vuetify components for UI

3. Internationalization:

   • Uses vue-i18n for multi-language support
   • Translation files stored in src/renderer/locales/
   • Keys are organized in JSON format

4. State Management:

   • Uses Pinia for state management
   • Stores are defined in src/renderer/store/
   • Follow Pinia's composition store pattern

5. Routing:

   • Uses Vue Router with web hash history
   • Routes defined in src/renderer/router/index.ts

6. IPC Communication:

   • Secure communication between main and renderer processes
   • Uses whitelisted channels defined in preload script
   • Accessible via window.mainApi in renderer process

Internationalization

The application supports multiple languages with the following locale files:

• English (en)
• Korean (ko)
• Simplified Chinese (zh-hans)
• Traditional Chinese (zh-hant)
• German (de)
• Spanish (es)
• Japanese (ja)
• French (fr)
• Russian (ru)
• Portuguese (pt)
• Dutch (nl)

Electron Integration

The application integrates with Electron features through:

• IPC communication for sending messages between processes
• Native file dialog support
• External link opening
• Application version retrieval
• Error handling and logging

Testing

The project includes Playwright for end-to-end testing, with configuration in playwright.config.ts and test files in the tests/ directory.

Build Outputs

Building creates different distribution formats based on the platform:

• macOS: DMG installer for x64, arm64, and universal architectures
• Windows: APPX, ZIP, Portable, and NSIS installers (x64)
• Linux: SNAP, DEB, and RPM packages (x64)

Artifacts are named with the format ${productName} ${version}_${arch}.${ext} and stored in the release/${version} directory.

run pnpm typecheck before finish the task if need，don't run pnpm dev or pnpm build.

Always respond in 中文