TUUI Development Setup and Dependency Management: Complete Guide

TUUI uses an Electron-Vite-Vue architecture with Node.js 22.12.0+, managed through a single package.json that defines strict engine requirements, runtime libraries, and build scripts for cross-platform desktop packaging.

The ai-ql/tuui repository is a modern desktop application built on Vue 3 and Electron. All development tooling, dependency constraints, and build orchestration are centralized in the root package.json, enabling reproducible installs via lockfile enforcement. This guide breaks down the exact dependency versions, npm scripts, and configuration files that power the development workflow.

Project Architecture and Tech Stack

TUUI is structured as a Vue 3 single-page application running inside an Electron native shell, bundled by Vite 7 for rapid hot-module replacement during development.

Electron-Vite-Vue Foundation

The stack combines:

• Vue 3 (^3.5.28) with Composition API for the renderer process UI
• Vuetify 3 (^3.11.8) for Material Design components
• Pinia (^3.0.4) for state management and Vue-Router (^5.0.2) for client-side navigation
• Electron (^40.4.1) providing the native desktop window and Node.js runtime
• Vite 7 (^7.3.1) as the build tool and development server

Node.js Engine Requirements

The project enforces a minimum Node.js version to ensure compatibility with modern ECMAScript features and security patches. In package.json lines 46-48, the engines field specifies:

{
  "engines": {
    "node": ">=22.12.0"
  }
}

This constraint guarantees that developers use Node.js 22.12.0 or newer, preventing runtime errors from unsupported syntax or API changes.

Runtime Dependencies

The dependencies section in package.json (lines 49-71) defines libraries required in the production bundle. Key runtime dependencies include:

• vue (^3.5.28) – Core UI framework
• vuetify (^3.11.8) – Component library with Material Design 3
• pinia (^3.0.4) – TypeScript-friendly state management
• vue-router (^5.0.2) – Declarative routing for SPA navigation
• electron (^40.4.1) – Desktop shell and main process APIs
• @anthropic-ai/mcpb and @modelcontextprotocol/sdk – AI/LLM integration tools
• @nut-tree-fork/nut-js – Native UI automation and control
• highlight.js, katex, mermaid – Syntax highlighting and diagram rendering
• localforage – Offline-capable storage wrapper
• md-editor-v3 – Markdown editing component

These packages are bundled into the final Electron application by the build pipeline.

Development Dependencies and Tooling

The devDependencies section (lines 73-99) contains build-time tools and type definitions that are not shipped to end users.

Vite Plugin Ecosystem

TUUI leverages several Vite-specific plugins defined in package.json:

• vite-plugin-electron and vite-plugin-electron-renderer – Bridge Vite's dev server with Electron's main and renderer processes
• vite-plugin-vuetify – On-demand Vuetify component tree-shaking
• @vitejs/plugin-vue and @vitejs/plugin-vue-jsx – Vue 3 SFC and JSX support

Type Checking and Linting

• typescript (^5.9.3) – Static type system
• vue-tsc (^3.2.4) – Type-checking for Vue single-file components via vue-tsc --noEmit
• eslint with Vue and Prettier configurations – Code quality enforcement
• prettier – Opinionated code formatting

Testing and Packaging

• @playwright/test – End-to-end testing framework executed via npm test
• electron-builder – Creates distributable installers for Windows, macOS, and Linux

NPM Scripts and Build Workflow

The scripts field in package.json (lines 24-45) orchestrates the entire development lifecycle from hot-reloading to production packaging.

Development Server (Hot Module Replacement)

The primary development command starts Vite's dev server and Electron simultaneously:

npm run dev

This executes the dev script, which launches Vite on http://localhost:5173. The Electron main process loads this URL via the debug.env.VITE_DEV_SERVER_URL configuration defined in package.json lines 19-23, enabling instant UI updates without restarting the desktop shell.

Production Build Pipeline

The build process uses a two-stage approach:

1. npm run build:pre – Runs formatting checks, TypeScript compilation (vue-tsc --noEmit), and Vite production bundling
2. npm run build – Executes build:pre followed by electron-builder to generate platform-specific installers (.exe, .dmg, .AppImage)

For macOS-specific builds, the repository provides npm run build:mac, which chains build:pre with Electron-Builder configured for Apple platforms.

Code Quality and Testing

Linting and formatting scripts enforce consistency before commits:

npm run lint        # ESLint check

npm run lint:fix    # Auto-fix ESLint errors

npm run format      # Prettier check

npm run format:fix  # Auto-format with Prettier

The test suite runs via:

npm test

This executes build:pre first to ensure type safety, then launches Playwright for end-to-end testing.

Key Configuration Files

Beyond package.json, the development setup relies on several configuration files:

File	Purpose
vite.config.mts	Vite configuration integrating Vue, Vuetify, and Electron plugins
src/renderer/main.ts	Entry point for the Vue application inside the Electron renderer process
src/main/index.ts	Entry point for the Electron main (Node.js) process
buildAssets/builder/config.js	Electron-Builder settings for code signing, icons, and target platforms
src/renderer/plugins/vuetify.ts	Vuetify theme, icon font, and internationalization setup
src/renderer/plugins/i18n.ts	Vue-i18n configuration for multi-language support

Local Development Quickstart

To set up the TUUI development environment:

1. Clone and install dependencies using the lockfile for exact version reproducibility:

   git clone https://github.com/ai-ql/tuui.git
   cd tuui
   npm ci

2. Start the development server with hot-reloading:

   npm run dev

3. Verify code quality before submitting changes:

   npm run lint
   npm run format

4. Run the test suite to validate functionality:

   npm test

5. Build the production application:

   npm run build

Summary

• Node.js 22.12.0+ is required, enforced by the engines field in package.json
• Runtime stack includes Vue 3, Vuetify 3, Pinia, and Electron 40, defined in dependencies (lines 49-71)
• Development tools include Vite 7, TypeScript 5.9, ESLint, Prettier, and Playwright, listed in devDependencies (lines 73-99)
• npm run dev starts the Vite dev server on port 5173, loaded by Electron for instant HMR feedback
• npm run build executes type-checking, linting, Vite bundling, and Electron-Builder packaging
• Configuration is split between vite.config.mts for bundling and buildAssets/builder/config.js for installer generation

Frequently Asked Questions

What Node.js version is required for TUUI development?

TUUI requires Node.js 22.12.0 or newer, as specified in the engines field of package.json (lines 46-48). This ensures compatibility with the modern JavaScript features used by Vite 7 and Electron 40. Attempting to install dependencies with an older version will trigger an engine mismatch error from npm.

How does TUUI handle dependency installation reproducibility?

The project uses package-lock.json alongside the npm ci command. Unlike npm install, which may update versions based on semver ranges, npm ci installs exact versions recorded in the lockfile. This guarantees that every developer and CI pipeline uses identical dependency trees, preventing "works on my machine" issues with Electron or Vite plugins.

What is the difference between build:pre and build scripts?

The build:pre script performs validation and compilation steps: it runs Prettier formatting checks, executes vue-tsc --noEmit for TypeScript type checking, and triggers Vite's production build. The build script calls build:pre first, then runs electron-builder to package the compiled code into OS-specific installers. This separation allows the CI pipeline to fail fast on type errors before attempting the slower packaging step.

How do I add a new runtime library to TUUI?

Install the package as a production dependency using npm:

npm install library-name@^version

This updates the dependencies section in package.json automatically. After installation, import the library in your Vue components or Electron main process code. Always run npm run build:pre afterward to ensure the new dependency does not introduce TypeScript compilation errors before committing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}